The Sender object is designed to capture audio and/or video data from installed capture options or adapters, package it and send it out onto a network.
To learn more about the Sender object, see:
For introductory information, see Collaboration Objects.
The following header file is required for the Sender object:
UMSNetSender.h
The following structures are defined in the header file and are used to specify the size of the captured video image and also to hold event data returned from the Sender object. Specific information on the use of these structures can be found along with the methods that use them.
typedef struct videosize {
unsigned long width;
unsigned long height;
} UMSH32xVideoSize;
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:
NoAudio,
PCMU
G723
} UMSH32xAudioFormat
enum EventType {
Error,
Request
};
typedef enum nettype {
NoNet,
H323
} UMSH32xNetType;
enum OnOff {
Off,
On
};
typedef enum videoformat{
NoVideo,
H263
H261
MJPEG
} UMSH32xVideoFormat;
enum ReturnCode Success, 1 Command completed successfully Failure, 2 Command failed InvalidParam, 3 A parameter is invalid or NULL InvalidState, 4 The command is not currently valid. NoEventPending, 5 No event pending AudioThreadFail, 6 Audio thread failed VideoThreadFail, 7 Video thread failed DataScktCreatFail, 8 Unable to create IP data socket CntlScktCreatFail, 9 Unable to create IP cntl socket CntlScktMembrFail, 10 Unable to add multicast IP membership CntlScktReuseFail, 11 Unable to set multicast reuse sockopt CntrlScktTTLFail, 12 Unable to set multicast TTL value CntlScktDLoopFail, 13 Unable to set multicast loopback sockopt DataScktMembrFail, 14 Unable to add multicast IP membership DataScktReuseFail, 15 Unable to set multicast reuse sockopt DataScktDLoopFail, 16 Unable to set multicast loopback sockopt DataScktTTLFail, 17 Unable to set multicast TTL value InvalidAddress, 18 Missing fields in IP address DFCGQFFail, 19 Data format control get quality factor failed ADDSFail, 20 Audio Device failure ADEIFail, 21 Audio Device enable input failure ADIFail, 22 Audio Device init failure ADMCNFail, 23 Audio Device Metaclass New failure ADMMFail, 24 Audio Device make failure ADSAFFail, 25 Audio Device set audio format failure ADSBFail, 26 Audio Device set balance failure ADSBOFail, 27 Audio Device set byte order failure ADSDBFail, 28 Audio Device set DMA buffer size failure ADSBSFail, 29 Audio Device set bits per sample failure ADSNFFail, 30 Audio Device set number format failure ADSNCFail, 31 Audio Device set number of channels failure ADSTFFail, 32 Audio Device set time format failure ADSSRFail, 33 Audio Device set sample rate failure ADSVFail, 34 Audio Device set volume failure ADSMFail, 35 Audio Device set monitor ADRFail, 36 Audio Device read failure ADMFail, 37 Audio Device malloc failure ADStartFail, 38 Audio Device start failure ADStopFail, 39 Audio Device stop failure AEFFail, 40 Audio encoder filter failure AENFail, 41 Audio encoder new failure AESNCFail, 42 Audio encoder set number of channels failure AESBPSFail, 43 Audio encoder set bits per second failure AESSPSFail, 44 Audio encoder set samples per second failure CanDefFail, 45 Failure setting cancel defer CanEnFail, 46 Failure enabling cancel IWMCNFail, 47 Image Window Metaclass New failure IWMMFail, 48 Image Window make failure IWSISFail, 49 Image Window set image size failure IWWFail, 50 Image Window write failure NSGICFail, 51 NegotiatorSink get input choice failure ODFail, 52 Open display failure SWFail, 53 Socket write failure VDNFail, 54 Video decoder New failure VDDFFail, 55 Video decoder decode frame failure VDSDSFail, 56 Video decoder set display size failure VDGCAFail, 57 Video decoder get colormap attributes failure VDGCMFail, 58 Video decoder get colormap failure VDSIFFail, 59 Video decoder set image format failure VDSISFail, 60 Video decoder set image size failure VDSOQFail, 61 Video decoder set output quality failure VECFFail, 62 Video encoder compress frame failure VEGPIFail, 63 Video encoder get packet info failure VENFail, 64 Video encoder new failure VESBRFail, 65 Video encoder set bit rate failure VESIFFail, 66 Video encoder set image format failure VESIIFail, 67 Video encoder set i frame interval failure VESISFail, 68 Video encoder set image size failure VESMQFail, 69 Video encoder set max quantizer failure VESPSFail, 70 Video encoder set packet size failure VESQFFail, 71 Video encoder set quality failure VIIFail, 72 VideoIN input failure VIGCMIFail, 73 VideoIN get colormap id failure VIGFFail, 74 VideoIN get format failure VIGOSFail, 75 VideoIN get out spec failure VIMFail, 76 VideoIN monitor failure VINFail, 77 VideoIN new failure VISDPFail, 78 VideoIN set display failure VISICFail, 79 VideoIN set input connector failure VISIFFail, 80 VideoIN set image format failure VISISFail, 81 VideoIN set image size failure VISSFFail, 82 VideoIN set signal format failure VISURFail, 83 VideoIN set update rate failure VISWFail, 84 VideoIN set window failure XWGCIFail, 85 Monitor Image Window get colormap ID failure XWSCAFail, 86 Monitor Image Window set colormap atts failure XWSCMFail, 87 Monitor Image Window set colormap failure XWSDPFail, 88 Monitor Image Window set display pointer failure XWSWFail, 89 Monitor Image Window set window failure MemoryAllocationFailed, 90 Memory alloc failed VideoDeviceNotOpen, 91 Video Monitor off VideoFormatNotSet, 92 Video format=NoVideo AudioFormatNotSet, 93 Video format=NoVideo NetworkNotSet, 94 NetType=NoNet ValueChanged 95 Specified value was changed };
This method is used to add a network connection to the list of connections receiving the audio and/or video data being sent by the sender. By default, no connections exist. Connections can be made at anytime after the set_network_type method call is made.
The following Sender method calls must be made prior to issuing this method:
This method is used to delete a network connection from the list of connections to which the Sender is sending audio and/or video data.
The following Sender method calls must be made prior to issuing this method:
set_network_type (with H323 parameter) add_h323
This method returns a list of valid audio connectors for the audio option/adapter installed in the system executing the object.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_audio_monitor (with UMSNetSender_On parameter)
This method returns a list of valid audio formats for the network type specified in the set_network_type method call.
The following Sender method calls must be made prior to issuing this method:
set_network_type
This method returns the colormap ID used by the video window.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_format set_video_monitor send
| out long id | Colormap ID used in the video window |
This method fills an EventData structure with information specific to the last event that occurred. Currently the only events supported by the Sender object are Error events.
The following Sender method calls must be made prior to issuing this method:
set_network_type send
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 Sender method calls must be made prior to issuing this method:
None
| inout long handle | Returns event handle, a valid event handle should be nonzero number. |
This method returns a boolean into the pending parameter which states whether there is a pending event or not.
The following Sender method calls must be made prior to issuing this method:
set_network_type send
| inout boolean flag | Returns True if there is a pending event. |
This method returns the e-mail address to be sent in the sender identifier information. It is the application programmers responsibility to free the memory allocated by this method.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| inout string email | E-mail address to be sent in the sender identifier information. |
This method returns the geographic location to be sent in the sender identifier information. It is the application programmers responsibility to free the memory allocated by this method.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| inout string loc | Geographic location to be sent in the sender identifier information. |
This method returns the name to be sent in the sender identifier information. It is the application programmers responsibility to free the memory allocated by this method.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| inout string name | Name to be sent in the sender identifier information. |
This method returns the note to be sent in the sender identifier information. It is the application programmers responsibility to free the memory allocated by this method.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| inout string note | Note to be sent in the sender identifier information. |
This method returns the phone number to be sent in the sender identifier information. It is the application programmers responsibility to free the memory allocated by this method.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| inout string phone | Phone number to be sent in the sender identifier information. |
This method returns the application tool name to be sent in the sender identifier information. It is the application programmers responsibility to free the memory allocated by this method.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| inout string tool | Application tool name to be sent in the sender identifier information. |
This method returns the sending statistics as gathered every 5 seconds by the Sender object.
The following Sender method calls must be made prior to issuing this method:
set_network_type if network type is H323 add_h323 (one or more calls to add one or more connection) if audio is desired set_audio_format set_audio_monitor (with UMSNetSender_On parameter) set_audio_connector if video is desired set_video_format set_video_monitor (with UMSNetSender_On parameter) set_video_connector set_video_signal_format set_video_size set_source_name get_event_handle send
This method captures a single frame from the video being sent.
The following Sender method calls must be made prior to issuing this method:
set_network_type if network type is H323 add_h323 (one or more calls to add one or more connection) if audio is desired set_audio_format set_audio_monitor (with UMSNetSender_On parameter) set_audio_connector if video is desired set_video_format set_video_monitor (with UMSNetSender_On parameter) set_video_connector set_video_signal_format set_video_size set_source_name get_event_handle send
This method returns a list of valid video connectors for the video capture option/adapter installed in the system executing the object.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_monitor (with UMSNetSender_On parameter)
This method returns a list of valid video formats for the network type specified in the set_network_type method call.
The following Sender method calls must be made prior to issuing this method:
set_network_type
This method returns a list of valid video signal formats for the video capture option/adapter installed in the system executing the object.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_monitor (with UMSNetSender_On parameter)
This method returns a list of valid video capture sizes for the video capture option/adapter installed in the system executing the object and the specified video format.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_monitor (with UMSNetSender_On parameter) set_video_format
This method starts the capturing and sending of audio and/or video data.
The following Sender method calls must be made prior to issuing this method:
set_network_type if network type is H323 add_h323 (one or more calls to add one or more connection) if audio is desired set_audio_format set_audio_monitor (with UMSNetSender_On parameter) set_audio_connector if video is desired set_video_format set_video_monitor (with UMSNetSender_On parameter) set_video_connector set_video_signal_format set_video_size set_source_name get_event_handle
This method selects which audio input connector is to be used to capture the audio data.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_audio_monitor (with UMSNetSender_On parameter) get_audio_connectors (recommended to get valid connector strings)
| in string connector | Use the get_audio_connectors method call to get the valid strings for the system being used. |
This method is used to set the audio format of the captured and transmitted data.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in UMSH32xAudioFormat format | Currently only the PCMU format is supported. |
This method sets the state of the audio capture device.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_audio_format
| in UMSNetSender_OnOff flag | Currently only the UMSNetSender_On flag is supported. |
This method sets the mute state of the local audio playing. This method does not effect the data that is being transmitted, only the audio being played locally.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_audio_format set_audio_monitor (with UMSNetSender_On parameter) set_audio_connector
| in UMSNetSender_OnOff flag | UMSNetSender_On - No local audio, UMSNetSender_Off - Play local audio. |
This method sets the state of sending audio data. This method only effects the data that is being transmitted, not the audio being played locally.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_audio_format set_audio_monitor (with UMSNetSender_On parameter) set_audio_connector send
| in UMSNetSender_OnOff flag | UMSNetSender_On - Stop sending audio data, UMSNetSender_Off - Resume sending audio data |
This method sets the volume of the local audio playing. This method does not effect the data that is being transmitted, only the audio being played locally.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_audio_format set_audio_monitor (with UMSNetSender_On parameter) set_audio_connector
| in unsigned long volume | The value of this parameter must be between 1 and 100. Where 100 is the maximum volume. |
This method sets the desired average bit rate for the data to be transmitted to each destination. This value is an average bit rate, not an upper or lower bound. Further more, this value is a desired rate. Depending on the video content and size, the desired rate might not be possible. If this is the case, the rate is set as close to the desired value as possible.
Prerequisite Sender Methods
set_network_type set_audio_format set_video_format
| inout long bitrate | The value is specified as an inout because the specified value might be outside the range of the selected encoder, in which case the closest valid value is returned. |
This method sets the Time To Live value for multicast packets. It is only used if one of the add_h323 method calls includes a multicast address and the network routers support the multicast protocol.
Note: Use caution when setting this value, large values can cause your transmission to be sent to many networks beyond your local network. This can cause unnecessary network delays if you did not intend to send the audio and/or video transmission that far.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in long ttl | Multicast TTL value specified in the range of 0-255. |
This method is used to specify the network type that the sender is to configure for and use. This method must be the first method called after creating the Sender object. Currently only a network type of H323 is supported.
The following Sender method calls must be made prior to issuing this method:
This method sets an e-mail address in the the sender identifier information that is sent to all recipients of the data.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in string email | E-mail address to be sent as part of the sender identifier information. |
This method sets a geographic location in the the sender identifier information that is sent to all recipients of the data.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in string loc | Geographic location to be sent as part of the sender identifier information. |
This method sets a name in the the sender identifier information that is sent to all recipients of the data.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in string name | Name to be sent as part of the sender identifier information. |
This method sets a note in the the sender identifier information that is sent to all recipients of the data.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in string note | Note to be sent as part of the sender identifier information. |
Success
Failure
This method sets a phone number in the the sender identifier information that is sent to all recipients of the data.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in string phone | Phone number to be sent as part of the sender identifier information. |
Success
Failure
This method sets an application tool name in the the sender identifier information that is sent to all recipients of the data.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in string tool | Application tool name to be sent as part of the sender identifier information. |
This method selects which video input connector is to be used to capture the video data.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_monitor (with UMSNetSender_On parameter) get_video_connectors (recommended to get valid connector strings)
| in string connector | Use the get_video_connectors method call to get the valid strings for the system being used. |
This method is used to set the video format of the captured and transmitted data. This method can be re-issued with another format after the data is being transmitted. However, in order to do this, you must issue the set_video_monitor call with the paramater Off before re-issuing the set_video format call. Then after the set_video format call, re-issue the set_video_monitor call with the paramater On and the same window and display the information as sent on the first set_video_monitor call.
The following Sender method calls must be made prior to issuing this method:
set_network_type
| in UMSH32xVideoFormat format | Currently only the H.263, H.261, and MJPEG formats are supported. |
This method sets the state of the video capture device and specifies X Window information that is used to handle local monitoring of the video data being captured and transmitted. On most video capture adapters this is a hardware feature and because of this, it does not reflect the actual data being transmitted in terms of frame rate.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_format
| in UMSNetSender_OnOff flag | Currently only the UMSNetSender_On flag is supported. |
| in unsigned long window | This parameter specifies the window ID of the window that is to be used to monitor the video being captured and transmitted. |
| 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. |
This method sets the state of sending video data. This method only effects the data that is being transmitted, not the video being played locally.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_format set_video_monitor (with UMSNetSender_On parameter) set_video_connector set_video_signal_format set_video_size send
| in UMSNetSender_OnOff flag | UMSNetSender_On - Stop sending video data UMSNetSender_Off - Resume sending video data |
This method selects the signal format of the incoming video data.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_monitor (with UMSNetSender_On parameter) get_video_signal_formats (recommended to get valid signal format strings)
| in string format | Use the get_video_signal_format method call to get the valid strings for the system being used. |
This method sets the size of the captured and transmitted video data.
The following Sender method calls must be made prior to issuing this method:
set_network_type set_video_format set_video_monitor (with UMSNetSender_On parameter) get_video_sizes (recommended to get the available valid sizes)
| in UMSH32xVideoSize size | Use the get_video_sizes method call to get the valid sizes for the capture device being used. |
This method sets the "Station ID" of the sender.
The following Sender method calls must be made prior to issuing this method:
None
| in string name | This parameter is a character string that specifies the "Station Identifier" of the sending source. This string must be 256 characters or less in length. |
For introductory information, see Collaboration Objects.