Media Plugin API

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.

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.

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.

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.

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.

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.