The Receiver object is designed to receive audio and/or video data from one or more sources on a network and play it. Currently, the Receiver will only connect to IP Networks and accept data prepared and transmitted using the Realtime Transport Protocol (RTP) Version 2.0 internet draft standard. Video must be encoded using either the H.263, H.261, or MJPEG video encoding standard and audio must be encoded using the PCMU audio encoding standard.
Note: Only one Receiver object should be created for any given combination of network connection parameters. The Receiver object is designed to scale automatically if more than one source is sending on the network connection parameter combination. See the setup_h323 method call for more information about network connection parameters.
To learn more about the Receiver object, see:
For introductory information, see Collaboration Objects.
The following header file is required for the Receiver object:
UMSNetReceiver.h
The following structure is defined in the header file and is used to hold event data returned from the Receiver object. Specific information on the use of this structure can be found along with the method that uses it.
struct EventData {
EventType type;
unsigned long specific;
unsigned long long1;
unsigned long long2;
unsigned long long3;
char string1[512];
char string2[256];
};
To avoid name collision on defines, integer values have been captured as enumeration lists. The set of valid values from an enumerated list can vary with the application. The detailed method descriptions describe the valid or possible values for the specific use.
Note: The numbers supplied along with the ReturnCode list are for reference only. Be sure and use the enumerated string when checking return codes to ensure that future changes do not affect your code.
The enumerated lists that are defined for this object are listed as follows:
enum OnOff {
Off,
On
};
enum EventType {
Error,
Request
};
enum StreamType {
AudioOnly,
VideoOnly,
Any
};
enum ReturnCode Success, 1 Command completed successfully NoConfigObj, 2 The configuration object failure NoAlias, 3 The device alias is not found NoDevice, 4 Device not found or is invalid CntlScktBindFail, 5 Unable to bind IP cntl socket CntlScktCreatFail, 6 Unable to create IP cntl socket CntlScktMembrFail, 7 Unable to add multicast IP membership CntlScktReuseFail, 8 Unable to set multicast reuse sockopt DataScktBindFail, 9 Unable to bind IP data socket DataScktCreatFail, 10 Unable to create IP data socket DataScktMembrFail, 11 Unable to add multicast IP membership DataScktReuseFail, 12 Unable to set multicast reuse sockopt FreeShmemFail, 13 Failure attach and freeing shared memory InvalidNetType, 14 Invalid network type MonitorFailed, 15 A monitor failed MonitorVDDFFail, 16 Monitor Video Decoder decompress frame failure MonitorVDGCAFail, 17 Monitor Video Decoder get colormap attr failure MonitorVDGCMFail, 18 Monitor Video Decoder get colormap failure MonitorVDGLFFail, 19 Monitor Video Decoder get last frame type fail MonitorVDNFail, 20 Monitor Video Decoder New Failure MonitorVDSDSFail, 21 Monitor Video Decoder set display size failure MonitorVDSIFFail, 22 Monitor Video Decoder set image format failure MonitorVDSISFail, 23 Monitor Video Decoder set image size failure MonitorADDSFail, 24 Monitor Audio Device start failure MonitorADEOFail, 25 Monitor Audio Device enable output failure MonitorADIFail, 26 Monitor Audio Device init failure MonitorADMCNFail, 27 Monitor Audio Device Metaclass New failure MonitorADMMFail, 28 Monitor Audio Device make failure MonitorADSAFFail, 29 Monitor Audio Device set audio format failure MonitorADSBFail, 30 Monitor Audio Device set balance failure MonitorADSBOFail, 31 Monitor Audio Device set byte order failure MonitorADSDBFail, 32 Monitor Audio Device set DMA buffer size failure MonitorADSBSFail, 33 Monitor Audio Device set bits per sample failure MonitorADSNFFail, 34 Monitor Audio Device set number format failure MonitorADSNCFail, 35 Monitor Audio Device set number of channels failure MonitorADSTFFail, 36 Monitor Audio Device set time format failure MonitorADSSRFail, 37 Monitor Audio Device set sample rate failure MonitorADSVFail, 38 Monitor Audio Device set volume failure MonitorADWBUFail, 39 Monitor Audio Device write buff used failure MonitorADWFail, 40 Monitor Audio Device write failure MonitorADeNFail, 41 Monitor Audio Decoder New failure MonitorADeSBRFail, 42 Monitor Audio Decoder set bitrate failure MonitorGISFail, 43 Monitor get image size failure MonitorIWCMapID, 44 Monitor Image Window Colormap ID (event) MonitorIWMCNFail, 45 Monitor Image Window Metaclass New failure MonitorIWMMFail, 46 Monitor Image Window make failure MonitorIWNoScale, 47 Monitor Image Window does not support scaling(event) MonitorIWSDSFail, 48 Monitor Image Window set display size failure MonitorIWSISFail, 49 Monitor Image Window set image size failure MonitorIWSWSFail, 50 Monitor Image Window set window size failure MonitorIWWFail, 51 Monitor Image Window write failure MonitorNSGICFail, 52 Monitor NegotiatorSink get input choice failure MonitorODFail, 53 Monitor Open Display failed MonitorKillFail, 54 Unable to kill a monitor MonitorSMAttFail, 55 Unable to attach monitor shared memory MonitorMsgFail, 56 Unable to send a message to a monitor MonitorMuteFail, 57 Monitor mute failure MonitorUnMuteFail, 58 Monitor unmute failure MonitorXWGCIFail, 59 Monitor Image Window get colormap ID failure MonitorXWSCAFail, 60 Monitor Image Window set colormap attributes failure MonitorXWSCMFail, 61 Monitor Image Window set colormap failure MonitorXWSDPFail, 62 Monitor Image Window set display pointer failure MonitorXWSWFail, 63 Monitor Image Window set window failure NeedDisplayInfo, 64 Request display information for video stream (event) NetRdrCanDefFail, 65 Failure setting cancel defer in the Net Reader thread NetRdrCanEnFail, 66 Failure enabling cancel in the Net Reader thread NetRdrPortSelError, 67 Select Error on port in the Net Reader NetRdrCScktFail, 68 Failure reading the cntl socket in the Net Reader NetRdrDScktFail, 69 Failure reading the data socket in the Net Reader NetRdrSPCFail, 70 Failure creating a stream processor NetRdrSPWakeFail, 71 Failure waking up stream processor NetReadThreadFail, 72 Failure creating the Net Reader thread RecvInvalDataType, 73 Received an invalid data type SPClassFail, 74 Stream Processor Class failure SPFail, 75 Stream Processor general failure SPThreadFail, 76 Stream Processor thread creation failure TooFewAddrFields, 77 Missing fields in IP address DeviceNotReady, 78 The device is not ready. InvalidState, 79 The command is not currently valid. WrongData, 80 Data is the wrong format OutOfRange, 81 Value is out of range for parameter. InvalidCommand, 82 Invalid command Failure, 83 Command fail DecompressFail, 84 Decompress frame failed NoEventPending, 85 No event pending UnknownError 86 An unexpected error occurred InvalidParam, 87 A parameter is invalid or NULL InvalidClass, 88 Invalid Device Class MemoryError, 89 Unable to allocate memory SourceConnReq, 90 Source connection request (event) SourceBye, 91 A Source has sent a bye protocol (event) UnknownSource, 92 Source specified in the get request is unknown UpdateSourceName, 93 Update of a source's name (event) UpdateSourceEMail, 94 Update of source's E-Mail address (event) UpdateSourcePhone, 95 Update of a source's phone number (event) UpdateSourceLoc, 96 Update of a source's geographic location (event) UpdateSourceTool, 97 Update of a source's application tool name (event) UpdateSourceNote, 98 Update of a source's note (event) ImageSizeChanged, 99 A source's video image size has changed (event) ValueChanged 100 Returned values different than requested };
This method is issued in response to a connection request event from the Receiver object. Use this method if it is desired to accept the connection for the data that is being received from the numeric source identifier supplied in the SourceConnReq request EventData structure.
Note: This call can only be made once per source identifier.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq)
This method closes the H323 network connection, but does not shutdown the Receiver.
The following Receiver method calls must be made prior to issuing this method:
This method call returns the colormap ID that is set by the Receiver object in the video window for the given source.
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection get_event (NeedDisplayInfo) set_monitor_display_information
| in long sourceid | This is the source ID number passed in the SourceConnReq event. |
| out long id | Set colormap ID. |
This method fills an EventData structure with information specific to the last event that occurred. Currently there only two types of events supported by the Receiver object; Error events and Request events. Error events are errors that have been detected by the Receiver and reported back to the calling program. Request events are requests from the Receiver to the calling program for actions or information. With either type of events, the EventData structure contains pertinent information about either the error or the request.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq)
This method returns an event handle. The application can use this handle as a file descriptor on which to select and thereby query events. If the file descriptor is readable, an event is queued.
The following Receiver method calls must be made prior to issuing this method:
| inout long handle | Returns event handle, a valid event handle should be nonzero number. |
This method call returns the e-mail address for the given source as sent by the source. It is the application programmers responsibility to free the memory allocated by this method.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection
| in long sourceid | This is the source ID number passed in the SourceConnReq event. |
| inout string email | The source's e-mail address. |
This method call returns the geographic location for the given source as sent by the source. It is the application programmers responsibility to free the memory allocated by this method.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection
| in long sourceid | This is the source ID number passed in the SourceConnReq event. |
| inout string loc | The source's geographic location. |
This method call returns the name for the given source as sent by the source. It is the application programmers responsibility to free the memory allocated by this method.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection
| in long sourceid | This is the source ID number passed in the SourceConnReq event. |
| inout string name | The source's name. |
This method call returns the note for the given source as sent by the source. It is the application programmers responsibility to free the memory allocated by this method.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection
| in long sourceid | This is the source ID number passed in the SourceConnReq event. |
| inout string note | The source's note. |
This method call returns the phone number for the given source as sent by the source. It is the application programmers responsibility to free the memory allocated by this method.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection
| in long sourceid | This is the source ID number passed in the SourceConnReq event. |
| inout string note | The source's phone number. |
This method call returns the application tool name for the given source as sent by the source. It is the application programmers responsibility to free the memory allocated by this method.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection
| in long sourceid | This is the source ID number passed in the SourceConnReq event. |
| inout string tool | The source's applicaion tool name. |
This method returns a boolean into the pending parameter which states whether there is a pending event or not.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 receive
| inout boolean flag | Returns True if there is a pending event. |
This method is used to enable the Receiver to start receiving data from the previously specified network connection.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323
This method is issued in response to a connection request event from the Receiver. Use this method if it is not desired to accept the connection for the data that is being received from the specified source identifier. Once this method is called, the data for the specified source is ignored. and can not be recovered without restarting the Receiver.
Note: This call can be made only once per source identifier.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq)
| in unsigned long sourceid | This parameter specifies the numeric source identifier, as returned in the connection request event. |
This method sets the mute state of the audio in the monitor window playing the audio associated with the specified numeric source identifier.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection
This method sets the volume of the the audio in the monitor window playing the audio associated with the specified numeric source identifier.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection
This method changes the desired display size for the video data associated with the specified numeric source identifier. If scaling is not done in hardware(MonitorIWNoScale request event received) the values of width and height can either be 1 or 2 times the original image size as supplied in the NeedDisplayInfo request event. If scaling is done in hardware, it is not necessary to issue this method call. In this case, simply re-size the window whose ID was passed to the Receiver via the set_monitor_display_information method to any desired size.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection get_event (NeedDisplayInfo) set_monitor_display_information
This method stops or restarts a monitor window which is playing the audio and/or video data associated with the specified numeric source identifier. A monitor is automatically created and started when the accept_connection method call is issued for the specified numeric source identifier. The set_monitor method can be used to stop and restart this monitor.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection If video data is present and accepted get_event (NeedDisplayInfo) set_monitor_display_information
This method is used to pass window information, to the Receiver, that will be used to display the received video data associated with the numeric source identifier. This window should be created as large as the video data's width and height as supplied in the NeedDisplayInfo request event that triggered the need to issue this method call.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq) accept_connection get_event (NeedDisplayInfo)
This method call can be issued by the application program in response to UMSNetReceiver_DataScktBindFail return code from the setup_h323 method call. This error indicates that the specified port is already in use by another application or Receiver object. This method call allows the application program to set a flag which indicates that the following setup_h323 method call should override the previous connection to the port. This can be helpful if the first program which allocates the port abnormally terminates with the port open.
The following Receiver method calls must be made prior to issuing this method:
| in OnOff | Port override on or off. |
This method is used to specify the network connection used to receive audio and/or video data from one or more sending source. This method call sets up the Receiver to receive audio and/or video data being transmitted either directly to the Receiver (unicast connection) or broadcast on the network (multicast connection). The format of the data is expected to conform to the Real-time Transport Protocol (RTP) Version 2.0 internet draft standard. The video data must be encoded with either the H.263, H.261 or MJPEG encoding scheme and the audio must be encoded with the PCMU audio encoding scheme. An application program should only make one of these calls until an end_h323 method call is issued. At which time, one new setup_h323 call can be issued.
The following Receiver method calls must be made prior to issuing this method:
This method is issued in response to a connection request event from the Receiver. Use this method if it is desired to not accept the connection until the "Station Identifier" is present in the "string1" field of the EventData structure filled by the SourceConnReq request event. After this method is called, the Receiver will not notify the calling program of a connection request from the specific numeric source identifier until the sending source transmits it's "Station Identifier". At that time, the Receiver will issue another connection request event, this time with the "string1" (Station Identifier) field filled in.
Note: This call can only be made once per source identifier.
The following Receiver method calls must be made prior to issuing this method:
If network type is H323 setup_h323 get_event_handle receive get_event (SourceConnReq)
| in unsigned long sourceid | This parameter specifies the numeric source identifier, as returned in the connection request event. |
For introductory information, see Collaboration Objects.