CommuniGate Pro
Version 1.0
API
 
 
 
 
 
 
 
 
API

Media Plugin API

The CommuniGate Pro Media Plugin provides a unified API on all supported platforms. This section describes the "object methods" the Media Plugin implements.

Media Legs

The Media Plugin can support several independent channels or "media legs" at the same time, allowing you to implement multi-line communication tools.

CreateLeg(id,inpName,outName)
Use this method to create a new Media Leg.
id is a string to be used as the new Media Leg identifier in all other methods. It should be different from identifiers of all existing Media Legs.
inpName is the name of the sound input device to use. Use an empty string to use the default device.
outName is the name of the sound output device to use. Use an empty string to use the default device.
This method returns an empty string if the new Media Leg has been created, otherwise it returns an error code string.
DestroyLeg(id)
Use this method to remove an existing Media Leg.
id is an existing Media Leg identifier.
This method returns an empty string if the Media Leg has been removed, otherwise it returns an error code string.
After a Media Leg is removed, you can reuse its identifier.

Activation and Deactivation

When a Media leg is activated, the sound input device is initiated and the data recorded via that device is sent to the network. When a Media Leg is deactivated, the sound input device is detached from that Media Leg, and the Media Leg stops sending data to the network.

Initially, when a Media Leg is created, it is deactivated. Activate the Media Leg when the user selects the corresponding "line".

Activate(id)
Use this method to activate an existing Media Leg.
id is an existing Media Leg identifier.
This method returns an empty string if the Media Leg has been activated and the sound input device has been attached to it, otherwise it returns an error code string.
Deactivate(id)
Use this method to deactivate an existing Media Leg.
id is an existing Media Leg identifier.
This method returns an empty string if the Media Leg has been deactivated and the sound input device has been dettached from it, otherwise it returns an error code string.

Session Descriptors

Session descriptors are used to inform the other party (the communication "peer") about the Media Leg data channel parameters (such as network addresses, codecs supported, etc.), and to inform the Media Leg about the other party channel parameters.

You usually use signalling protocols, such as SIP or XIMSS to exchange session descriptor information between the parties.

The format parameter specifies the Session Descriptor data format:

"sdp"
the SDP format.
"xml"
the XML SDP format.

GetLocalSDP(id,format)
Use this method to retrieve a session descriptor for an existing Media Leg.
id is an existing Media Leg identifier.
format specifies the Session Descriptor format.
This method returns the Session Descriptor if the Media Leg is found, otherwise it returns a null-value.
SetRemoteSDP(id,data,format)
Use this method to set the session descriptor of the Media Leg peer.
id is an existing Media Leg identifier.
data is the Session Descriptor string.
format specifies the Session Descriptor string format.
This method returns an empty string if the Media Leg has accepted the peer Session Descriptor, otherwise it returns an error code string.
SetHold(id,flag)
Use this method to put the Media Leg on hold or to release it. When a Media Leg is placed on hold, it does not read the media information from the network; its session descriptor is modified to indicate the Media Leg "send-only" status.
id is an existing Media Leg identifier.
if flag is a true-value, the Media Leg is put on hold, otherwise the Media Leg is released.
This method returns an empty string if the Media Leg has accepted the operation, otherwise it returns an error code string.
Note: to implement a traditional "Hold" telephony function:
  • use SetHold(id,true)
  • use GetLocalSDP(id,format) to get an updated session descriptor and to send it to the peer via the signaling path.
  • use Deactivate(id) to stop sending the peer local audio input.
  • use PlayToRemote(id,music-on-hold data,10000000) to play music on hold to the peer.
To "Release" or "Resume" the line:
  • use PlayToRemote(id,"",0) to stop playing music on hold to the peer.
  • use SetHold(id,false)
  • use GetLocalSDP(id,format) to get an updated session descriptor and to send it to the peer via the signaling path.
  • use Activate(id) to resume sending the peer local audio input.

Sending DTMF commands

A Media Leg can send a DTMF command ("digit") to its peer.

SendDTMF(id,symbol)
Use this method to send a DTMF "digit" to the Media Leg peer.
id is an existing Media Leg identifier.
symbol a 1-symbol string containing the DTMF command. The following commands are allowed:
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, #, A, B, C, D
This method returns an empty string if the Media Leg has queued the DTMF command for sending, otherwise it returns an error code string.

Note: the Media Leg DTMF queue is about 10 symbols, so you should not try to send more than 10 command at once. It takes about 0.2 second to send each DTMF command.


Volume Control

Each Media Leg has independent sound level controls.

SetInputVolume(id,volume)
Use this method to set the input (local recording) volume for the selected Media Leg.
id is an existing Media Leg identifier.
volume is a positive number: 1 for maximum volume, larger numbers up to 100 decrease the volume.
This method returns an empty string if the Media Leg has accepted the volume change, otherwise it returns an error code string.
Note: this operation has any effect only when the Media Leg is activated.
SetOutputVolume(id,volume)
Use this method to set the output (local playing) volume for the selected Media Leg.
id is an existing Media Leg identifier.
volume is a positive number: 1 for maximum volume, larger numbers larger numbers up to 100 decrease the volume.
This method returns an empty string if the Media Leg has accepted the volume change, otherwise it returns an error code string.
GetInputLevel(id)
Use this method to retrieve the input (remote recording) level for the selected Media Leg.
id is an existing Media Leg identifier.
This method returns a non-negative number - the input level.
SetMute(id, flag) (GIPS-based only)
Use this function to switch microphone off and on. This method doesn't affect the microphone level, but replaces the output stream with zeros.
id is an existing Media Leg identifier.
If flag is a true-value, the Media Leg is muted, otherwise the Media Leg is unmuted.
This method returns an empty string if the Media Leg has accepted the operation, otherwise it returns an error code string.
GetMute(id) (GIPS-based only)
Use this function to retrieve mute state for the selected Media Leg.
id is an existing Media Leg identifier.
This function returns a true-value if the specified Media Leg is muted, otherwise it return a false-value.
SetMuteRemote(id, flag) (GIPS-based only)
Use this function to mute the incoming audio stream from the specific Media Leg. This method doesn't affect the sound volume, but causes the incoming stream to be ignored.
id is an existing Media Leg identifier.
If flag is a true-value, the Media Leg is muted, otherwise the Media Leg is unmuted.
This function returns an empty string if the Media Leg has accepted the operation, otherwise it returns an error code string.
GetMuteRemote(id) (GIPS-based only)
Use this function to retrieve mute state for the selected Media Leg.
id is an existing Media Leg identifier.
This function returns a true-value if the specified Media Leg is muted, otherwise it returns a false-value.
SetAEC(flag) (GIPS-based only)
Acoustic echo occurs when there is an acoustic coupling between the speaker and microphone (the microphone can "hear" the speaker output). As a result, the remote peers hear their audio (speech) echoed back to them. The Acoustic Echo Cancellation (AEC) is used to eliminate or to mitigate this echo.
If flag is a true-value, AEC is enabled for all Media Legs, otherwise AEC is disabled for all Media Legs.
GetAEC() (GIPS-based only)
Use this function to retrieve the Acoustic Echo Cancellation state.
This function returns a true-value if AEC is enabled (for all Media Legs), otherwise it returns a false-value.
SetNoiseSuppression(flag) (GIPS-based only)
Noise Suppression (NS) reduces noise in the microphone signal.
If flag is a true-value, NS is enabled for all Media Legs, otherwise NS is disabled for all Media Legs.
GetNoiseSuppression() (GIPS-based only)
Use this function to retrieve the Noise Suppression state.
This function returns a true-value if NS is enabled (for all Media Legs), otherwise it returns a false-value.
SetAGC(flag) (GIPS-based only)
Automatic Gain Control (AGC) adjusts the microphone signal to an appropriate level.
If flag is a true-value, AGC is enabled for all Media Legs, otherwise AGC is disabled for all Media Legs.
GetAGC() (GIPS-based only)
Use this function to retrieve the Automatic Gain Control state.
This function returns a true-value if AGC is enabled (for all Media Legs), otherwise it returns a false-value.

Playback

PlayToLocal(id,audioData,loopMsec)
Use this method to play a pre-recorded media data via the Media Leg sound output channel.
id is an existing Media Leg identifier.
audioData is a string containing a WAV-formated or AU-formatted sound file data in the base64 encoding.
loopMsec if this numeric parameter is larger than 0, the sound file is played for the specified number of the milliseconds. If the file sound is too short, the file is played in loop. Otherwise, the file is played once and entirely.
This method returns an empty string if the Media Leg has started to play the specified sound data, otherwise it returns an error code string.
This method only initiates playing, it does not wait till playing completes.
You can interrupt sound playing by calling this method again, with different parameters (to initiate new playing operation). Use an empty string as the audioData value to interrupt the current playing operation without starting a new one.
PlayToRemote(id,audioData,loopMsec)
Use this method to play a pre-recorded media data to the Media Leg peer over the network.
id is an existing Media Leg identifier.
audioData is a string containing a WAV-formated or AU-formatted sound file data in the base64 encoding.
loopMsec if this numeric parameter is larger than 0, the sound file is played for the specified number of the milliseconds. If the file sound is too short, the file is played in loop. Otherwise, the file is played once and entirely.
This method returns an empty string if the Media Leg has started to play the specified sound data, otherwise it returns an error code string.
This method only initiates playing, it does not wait till playing completes.
You can interrupt sound playing by calling this method again, with different parameters (to initiate new playing operation). Use an empty string as the audioData value to interrupt the current playing operation without starting a new one.

Media Mixer

The Media Plugin can mix several audio streams and send the mixed stream back to each mixed channel, allowing you to implement client-side conference.

AttachToMixer(id) (GIPS-only)
Use this method to attach an existing Media Leg to the media mixer.
id is an existing Media Leg identifier.
This method returns an empty string if the Media Leg has been attached, otherwise it returns an error code string.
DetachFromMixer(id) (GIPS-only)
Use this method to detach an existing Media Leg from the media mixer.
id is an existing Media Leg identifier.
This method returns an empty string if the Media Leg has been detached, otherwise it returns an error code string.

Services

GetVersion()
This method returns a string containing the Media Plugin version.
SetLocalIP(ipAddress)
Use this method to specify the network (IP) address the newly created Media Legs should use.
If the local network address is not set explicitly, the Media Legs do not "bind" their communication sockets to any particular address, but the generated Session Descriptors contain the first available local IP address.
If the local network address is set, the Media Legs "bind" their communication sockets to that address and the generated Session Descriptors contain that address, too.
ipAddress is a string containing the new IP address. Specify "0.0.0.0" to reset the local IP address set.
This method returns an empty string if the new IP address has been accepted, otherwise it returns an error code string.
SetLocalPorts(from,till,roundRobin)
Use this method to specify the network (IP) ports the newly created Media Legs should use.
from and till are numbers, specifying the new port range to use.
roundRobin is a boolean value. If this value is a true-value, new ports for new Legs will be assigned using the round-robin algorithm, when each new Leg gets the next pair of ports. If this value is a false-value, each new Leg will get the lowest-number unused port pair.
If this method has not been called, the Media Legs will use ports in the 50000-50099 range, without the round-robin algorithm.
This method returns an empty string if the new IP port range has been accepted, otherwise it returns an error code string.
ListDevices(type)
Use this method to retrieve the local media device names. You can use these names as parameters for the CreateLeg method calls.
The type is a string specifying the device type. The supported values are audioInp and audioOut.
This method returns a string containing the names of all available devices, enclosed in the quote (") symbols, and separated with the semicolon (; symbol.
SetLogLevel(level)
Use this method to set the Log Level.
ipAddress is a new level number:
  • -1 - logging is disabled
  • 0 - log crashes/assertion violations only
  • 1 - log failures and crashes
  • 2 - log major events and failures
  • 3 - log major events and intermediate problems
  • 4 - log problems and low-level information
  • 5 - log everything
The Log is stored in the CommuniGateMedia.log file. When this file reaches 10Mbyte in size, it is renamed into CommuniGateMediaOld.log (deleting an existing file with this name, if any), and the Log is stored into the newly created CommuniGateMedia.log file.
SetCodecOrder(level) (GIPS-only)
Use this function to set the codecs priority:
The level value should be an integer:
  • 1 - Highest quality. The local SDP lists supported codec in the following order:
    ISAC, AMR-WB, IPCMWB, ISAC-LC, G.722, EG.711, G.711, iLBC, G.729
  • 2 - Normal quality. The local SDP lists supported codec in the following order:
    ISAC, AMR-WB, ISAC-LC, G.722, EG.711, G.711, iLBC, G.729, IPCMWB
  • 3 - Low quality. The local SDP lists supported codec in the following order:
    ISAC, AMR-WB, ISAC-LC, G.729, iLBC, ISAC-LC, G.722, G.711, EG.711, IPCMWB
The codecs shown in bold are enabled only if the Server has the codec-enabling License Key.

Licensing

GetLicenseChallenge()
This method returns a string with base64-endoded License challenge daya.
If the returned string is not empty, it should be sent to the CommuniGate Pro Server using the XIMSS licenseCheck command (the string should be sent as the base64 XML element body).
If the returned string is empty, this version of the Media Plugin does not require an explicit License check with the Server.
ProcessLicenseResponse(response)
This method should be used when the licenseResponse data message is received via a XIMM connection to the CommuniGate Pro Server in response to the licenseCheck command.
the response string should be the licenseResponse data message base64 XML element body.
This method returns an empty string if the License reponse has been accepted, otherwise it returns an error code string.

CommuniGate® Pro Guide. Copyright © 1998-2010, Stalker Software, Inc.