The SetAudioMediaFormats function allows you to specify one or more codecs that will be used when you place an outgoing call. Calling this API procedure also sets the order that codecs will be used when receiving incoming calls. Different sets of media formats (codecs) can be set for each phone line. Alternatively, all phone lines can use the same codec settings.

For further information, see the remarks section below.

Namespace:  LanScape
Assembly:  LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetAudioMediaFormats(
	int PhoneLine,
	VoipMediaEngine..::.MEDIA_FORMAT_AUDIO[] MediaFormats
)
Visual Basic (Declaration)
Public Function SetAudioMediaFormats ( _
	PhoneLine As Integer, _
	MediaFormats As VoipMediaEngine..::.MEDIA_FORMAT_AUDIO() _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetAudioMediaFormats(
	int PhoneLine, 
	array<VoipMediaEngine..::.MEDIA_FORMAT_AUDIO>^ MediaFormats
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetAudioMediaFormats(
	int PhoneLine,
	VoipMediaEngine..::.MEDIA_FORMAT_AUDIO[] MediaFormats
)

Parameters

PhoneLine
Type: System..::.Int32
The zero based phone line to configure.
MediaFormats
Type: array< LanScape..::.VoipMediaEngine..::.MEDIA_FORMAT_AUDIO >[]()[]
An ordered array of media formats (codec types) that will be used when initiating and receiving calls. It can be any one of the following enumerated values as specified by the VoipMediaEngine..::.MEDIA_FORMAT_AUDIO data type. For outgoing calls, the array's codec order specifies the order of the codecs in the transmitted SIP INVITE message. For incoming calls, the array's codec order specifies the order that codecs will be evaluated to fulfill the call.

Examples:

For outgoing calls: If you enable one or more codecs using this API procedure, all codecs you specified will be included in the SIP INVITE message that will be transmitted to the call destination (or proxy). For example, the following INVITE message shows more than one codec enabled. The codecs that are being used for the call are shown in RED (G729, iLBC, uLaw, aLaw, 8k PCM, 11k PCM and 22k PCM).

To achieve this, the pMediaFormats array was initialized with the following values: Media_Format_G729, Media_Format_iLBC_30Ms, Media_Format_uLaw8k, Media_Format_aLaw8k, Media_Format_Pcm8000, Media_Format_Pcm11050, and Media_Format_Pcm22050.


INVITE sip:111@lanscapecorp.dnsalias.com:7000 SIP/2.0
Via: SIP/2.0/UDP 192.168.1.2:10000
From: 222 <sip:222@lanscapecorp.dnsalias.com:7000>;tag=1fd0c98;
To: <sip:111@lanscapecorp.dnsalias.com:7000>
Contact: <sip:222@lanscapecorp.dnsalias.com:7000>;x-inst=VGVzdCBDYWxsIERhdGEgZnJvbSB0aGUgVlBob25lIGFwcC4=
Call-Id: 19a3e452-6af2-4a57-92a8-b479540a3529-00000670@192.168.1.2
CSeq: 33366184 INVITE
Max-Forwards: 70
Organization: 1D05B88F-516D-483E-B5A1-E22654099440
Content-Length: 386
User-Agent: LanScape VOIP Media Engine/6.0.0.0 (www.LanScapeCorp.com)
Allow: INVITE, ACK, OPTIONS, BYE, CANCEL, SUBSCRIBE, NOTIFY
Content-Type: application/sdp

v=0
o=222 33354312 33354312 IN IP4 192.168.1.2
s=LanScape
c=IN IP4 192.168.1.2
t=0 0
m=audio 19002 RTP/AVP 18 97 0 8 124 125 126 101
a=rtpmap:18 G729/8000/1
a=rtpmap:97 ILBC/8000/1
a=rtpmap:0 PCMU/8000/1
a=rtpmap:8 PCMA/8000/1
a=rtpmap:124 PCM/8000/1
a=rtpmap:125 PCM/11050/1
a=rtpmap:126 PCM/22050/1
 a=rtpmap:101 telephone-event/8000/1
a=fmtp:97 mode=30
a=fmtp:101 0-15

For incoming calls: If you enable one or more codecs using this API procedure, all codecs you specified will be used to resolve the codec requests that are specified in the received SIP INVITE message. The first codec type identified in the received SIP INVITE message will be used for the call. The following response shows that G729 will be used for the answered call. See the data below shown in RED.



SIP/2.0 200 OK
Via: SIP/2.0/UDP 192.168.1.2:10000;received=192.168.1.2:10000
Record-Route: <sip:70.92.167.124:7000>
From: 222 <sip:222@lanscapecorp.dnsalias.com:7000>;tag=20ed1ab;x-UaId=x123;x-PsId=76B162933D64
To: <sip:111@lanscapecorp.dnsalias.com:7000>;tag=1d458d1
Call-ID: 4b6da931-dc1b-49fa-a04c-a3bc6865eac3-00000994@192.168.1.2
CSeq: 34520383 INVITE
Contact: <sip:111@70.92.181.123:6001>
Server: LanScape Centrex Proxy/3.40 (www.LanScapeCorp.com)
Allow: INVITE, ACK, OPTIONS, BYE, CANCEL, SUBSCRIBE, NOTIFY
Content-Type: application/sdp
Content-Length: 166

v=0
o=LanScape 3348258071 3348258071 IN IP4 70.92.181.123
s=LanScape
c=IN IP4 70.92.181.123
t=0 0
m=audio 16212 RTP/AVP 18
a=rtpmap:18 G729/8000/1
a=ptime:20

Return Value

If the function succeeds, the return value will be SipSuccess.

If the function fails, the return value will be one of the following values as specified by the VoipMediaEngine..::.TELEPHONY_RETURN_VALUE data type.

Return ValueDescription
SipCallFailure
This value is returned by telephony API procedures to indicate general API failure. This error value is used as a "catch all error". If you receive this error, check to make sure that all parameters specified in the API procedure call are correct. Particularly, verify that pointers to memory regions are valid. This error return value is only used if a mapping to another specific error value does not exist.

(API return value)

SipBadPhoneLine
Application software called a telephony API procedure and specified an invalid phone line. Phone lines are numbered starting from zero. This error is most commonly returned when attempting to access phone lines in excess of the max number of lines supported by the telephony engine.

(API return value)

SipBadAudioDataType
Indicates that application software attempted to specify an invalid IVR or Audio Output media data type when calling the OpenRxIvrChannel(VoipMediaEngine, Int32, VoipMediaEngine..::.IVRCALLBACKPROC, Object, Boolean, VoipMediaEngine..::.AUDIO_BANDWIDTH, Int32%, Int32%, Boolean%), SetTxIvrDataType(VoipMediaEngine..::.AUDIO_BANDWIDTH), GetTxIvrSampleBlockSize(VoipMediaEngine..::.AUDIO_BANDWIDTH, Int32%, Int32%, Boolean%), or the SetAudioOutDataType(VoipMediaEngine..::.AUDIO_BANDWIDTH) API procedures. Make sure you specify the appropriate VoipMediaEngine..::.AUDIO_BANDWIDTH parameter when calling these API procedures.

(API return value)

Remarks

Application developers should keep in mind that it is not possible to enable G729 and G729A codecs at the same time. Likewise it is not possible to enable the multiple forms of iLBC codecs at the same time.

G729:
G729 and G729A are bit for bit compatible over the wire (i.e. the data that is carried in the RTP payloads). G729 and G729A cannot be specified at the same time because the session description (using sdp) in the SIP INVITE that gets transmitted for the call can only specify the G729 media payload type. Take a look at a SIP log for a call that uses G729 and then look at a SIP log for a call that uses G729A. The session setup will all specify G729 as the media payload type. G729A is used to reduce the CPU load in the application relative to using original G729.

iLBC:
Only one iLBC media type can be specified in the outgoing SIP INVITE. This is because the difference in iLBC negotiation and interchange between call endpoints is not a codec difference but a mode difference of the same codec. See the INVITE sdp for each type of call. One will use mode=30 and the other will use mode=20 in the sdp of the INVITE.

See Also