[ Previous | Next | Contents | Glossary | Home | Search ]
Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

Receiver Object

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.

Header Files

The following header file is required for the Receiver object:

UMSNetReceiver.h

Structures

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];
};

Enumeration Lists

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
 };

Method Descriptions

ReturnCode accept_connection(in unsigned long sourceid, in StreamType type)

Description

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.
Prerequisite Receiver Methods

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)
Arguments
in unsigned long sourceid This parameter specifies the numeric source identifier, as returned in the connection request event.
in StreamType type This parameter specifies the type of data that the Receiver should accept from the source. Valid choices are:
AudioOnly: This value (defined in the StreamType enum list) specifies that the Receiver should only accept audio from the source. If video data is also being sent, it will be ignored.
VideoOnly: This option is not currently implemented.
Any: This option specifies that the Receiver should accept both audio and video.
Return Values

Success

NetRdrSPCFail

SPClassFail

SPThreadFail

InvalidParam

ReturnCode close_h323()

Description

This method closes the H323 network connection, but does not shutdown the Receiver.

Prerequisite Sender Methods

The following Receiver method calls must be made prior to issuing this method:

setup_h323

Arguments

None

Return Values

Success

Failure

ReturnCode get_colormap_id(in long sourceid out long id)

Description

This method call returns the colormap ID that is set by the Receiver object in the video window for the given source.

Prerequisite Sender Methods
If network type is H323
setup_h323
get_event_handle
receive
get_event (SourceConnReq)
accept_connection
get_event (NeedDisplayInfo)
set_monitor_display_information
Arguments
in long sourceid This is the source ID number passed in the SourceConnReq event.
out long id Set colormap ID.
Return Values

Success

Failure

UnknownSource

ReturnCode get_event(inout EventData event_data)

Description

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.

Prerequisite Receiver Methods

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)
Arguments
inout EventData event_data When an event occurs, the EventData structure returned by this method will contain the following information about the event:
struct EventData {
   EventType      type;      Event Type
   unsigned long   specific;   ReturnCode or Request type
   unsigned long   long1;   Source ID
   unsigned long   long2;   Request dependant data
   unsigned long   long3;   Request dependant data
   char      string1[512];   Request dependant data
   char      string2[256];   Request dependant data
};
Return Values

Success

Failure

InvalidParam

ReturnCode get_event_handle(inout long handle)

Description

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.

Prerequisite Receiver Methods

The following Receiver method calls must be made prior to issuing this method:

None

Arguments
inout long handle Returns event handle, a valid event handle should be nonzero number.
Return Values

Success

ReturnCode get_source_email(in long sourceid inout string email)

Description

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.

Prerequisite Receiver Methods

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
Arguments
in long sourceid This is the source ID number passed in the SourceConnReq event.
inout string email The source's e-mail address.
Return Values

Success

Failure

UnknownSource

InvalidParam

ReturnCode get_source_loc(in long sourceid inout string loc)

Description

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.

Prerequisite Receiver Methods

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
Arguments
in long sourceid This is the source ID number passed in the SourceConnReq event.
inout string loc The source's geographic location.
Return Values

Success

Failure

UnknownSource

InvalidParam

ReturnCode get_source_name(in long sourceid inout string name)

Description

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.

Prerequisite Receiver Methods

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
Arguments
in long sourceid This is the source ID number passed in the SourceConnReq event.
inout string name The source's name.
Return Values

Success

Failure

UnknownSource

InvalidParam

ReturnCode get_source_note(in long sourceid inout string note)

Description

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.

Prerequisite Receiver Methods

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
Arguments
in long sourceid This is the source ID number passed in the SourceConnReq event.
inout string note The source's note.
Return Values

Success

Failure

UnknownSource

InvalidParam

ReturnCode get_source_phone(in long sourceid inout string phone)

Description

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.

Prerequisite Receiver Methods

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
Arguments
in long sourceid This is the source ID number passed in the SourceConnReq event.
inout string note The source's phone number.
Return Values

Success

Failure

UnknownSource

InvalidParam

ReturnCode get_source_tool(in long sourceid inout string tool)

Description

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.

Prerequisite Receiver Methods

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
Arguments
in long sourceid This is the source ID number passed in the SourceConnReq event.
inout string tool The source's applicaion tool name.
Return Values

Success

Failure

UnknownSource

InvalidParam

ReturnCode event_pending(inout boolean flag)

Description

This method returns a boolean into the pending parameter which states whether there is a pending event or not.

Prerequisite Receiver Methods

The following Receiver method calls must be made prior to issuing this method:

If network type is H323
setup_h323
receive
Arguments
inout boolean flag Returns True if there is a pending event.
Return Values

Success

ReturnCode receive()

Description

This method is used to enable the Receiver to start receiving data from the previously specified network connection.

Prerequisite Receiver Methods

The following Receiver method calls must be made prior to issuing this method:

If network type is H323
setup_h323
Arguments

None

Return Values

Success

NetReadThreadFail

ReturnCode reject_connection(in unsigned long sourceid)

Description

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.
Prerequisite Receiver Methods

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)
Arguments
in unsigned long sourceid This parameter specifies the numeric source identifier, as returned in the connection request event.
Return Values

Success

InvalidParam

ReturnCode set_audio_mute(in unsigned long sourceid, in UMSNetReceiver_OnOff flag)

Description

This method sets the mute state of the audio in the monitor window playing the audio associated with the specified numeric source identifier.

Prerequisite Receiver Methods

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
Arguments
in unsigned long sourceid This parameter specifies the numeric source identifier associated with the monitor window whose audio is to be muted.
in UMSNetReceiver_OnOff flag UMSNetReceiver_On: No audio, UMSNetReceiver_Off: Play audio.
Return Values

Success

MonitorADSVFail

InvalidParam

ReturnCode set_audio_volume(in unsigned long sourceid, in unsigned long volume)

Description

This method sets the volume of the the audio in the monitor window playing the audio associated with the specified numeric source identifier.

Prerequisite Receiver Methods

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
Arguments
in unsigned long sourceid This parameter specifies the numeric source identifier associated with the monitor window whose audio volume is to be changed.
in unsigned long volume This value is between 1 and 100. Where 100 is the maximum volume.
Return Values

Success

MonitorADSVFail

InvalidParam

ReturnCode set_display_size(in unsigned long sourceid, in unsigned long width,, in unsigned long height)

Description

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.

Prerequisite Receiver Methods

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
Arguments
in unsigned long sourceid This parameter specifies the numeric source identifier associated with the monitor window whose video window is to be re-sized.
in unsigned long width This value is 1 or 2 times the image width supplied in the "long2" field of the EventData structure returned as a result of the NeedDisplayInfo request event.
in unsigned long height This value is 1 or 2 times the image height supplied in the "long3" field of the EventData structure returned as a result of the NeedDisplayInfo request event.
Return Values

Success

InvalidParam

ReturnCode set_monitor(in unsigned long sourceid, UMSNetReceiver_OnOff flag)

Description

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.

Prerequisite Receiver Methods

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
Arguments
in unsigned long sourceid This parameter specifies the numeric source identifier associated with the monitor to be stopped or restarted.
in UMSNetReceiver_OnOff flag UMSNetReceiver_On: Restart the monitor. This flag can only be used if a previous set_monitor method call with the UMSNetReceiver_Off parameter for the given source identifier was issued, (UMSNetReceiver_Off: Stop the monitor.
Return Values

Success

InvalidParam

ReturnCode set_monitor_display_information(in unsigned long sourceid, unsigned long window, unsigned long topwin, in string dispstr)

Description

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.

Prerequisite Receiver Methods

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)
Arguments
in unsigned long sourceid This parameter specifies the numeric source identifier associated with the video data to be played in the window.
in unsigned long window This parameter specifies the window ID of the window that is to be used to play the video.
in unsigned long topwin This parameter specifies the window ID of the toplevel widget that owns the window specified in the above window parameter.
in string dispstr This parameter specifies the X display string for the window specified in the above window parameter.
Return Values

Success

InvalidParam

ReturnCode set_h323_socket_reuse(in OnOff flag)

Description

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.

Prerequisite Receiver Methods

The following Receiver method calls must be made prior to issuing this method:

None

Arguments
in OnOff Port override on or off.
Return Values

Success

Failure

InvalidParam

ReturnCode setup_h323(in string interface, in string address, in long port)

Description

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.

Prerequisite Receiver Methods

The following Receiver method calls must be made prior to issuing this method:

None

Arguments
in string interface This parameter specifies the network interface that is to be used to receive the data for this connection. This parameter must be specified as the address of an available network interface.
in string address This parameter specifies the multicast address of the broadcast data. The address must be in the range of 224.0.0.0 up to but not including 240.0.0.0. If the data is being transmitted directly to the Receiver (unicast connection), this parameter is not supplied and passed as a NULL value.
in long port This parameter specifies the port at which the data being sent is to be received. Per the RTP audio/video data payload definition, the value of the port parameter must be specified as an even number. This is because, the control port is automatically selected as the next higher odd numbered port. One port pair is allocated per media type (audio and/our video). For example, if the the port is specified as 5004, the audio data will be sent on port 5004 and the audio control information is sent on port 5005, the video data will be sent on port 5006 and the video control information is sent on port 5007.
Return Values

Success

Failure

CntlScktCreatFail

CntlScktMembrFail

CntlScktReuseFail

DataScktCreatFail

DataScktMembrFail

DataScktReuseFail

TooFewAddrFields

InvalidParam

ReturnCode waitid_connection(in unsigned long sourceid)

Description

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.
Prerequisite Receiver Methods

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)
Arguments
in unsigned long sourceid This parameter specifies the numeric source identifier, as returned in the connection request event.
Return Values

Success

InvalidParam

For introductory information, see Collaboration Objects.


[ Previous | Next | Contents | Glossary | Home | Search ]