 Caution: |
|---|
| IMPORTANT: If your VOIP application exchanges fully encrypted RTP packets with another telephony device (RTP headers and payloads are fully encrypted), you will have to disable the media engine's default RTP packet filtering behavior. For additional details, see the remarks section below. |
An application should call this API procedure any time prior to initiating or receiving phone calls.
Assembly: LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700
Syntax
| C# |
|---|
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableRawRtpPacketAccess( VoipMediaEngine MediaEngine, int PhoneLine, bool EnableState, VoipMediaEngine..::.RTP_CALLBACK_PROC RtpCallback, Object UserData ) |
| Visual Basic (Declaration) |
|---|
Public Function EnableRawRtpPacketAccess ( _ MediaEngine As VoipMediaEngine, _ PhoneLine As Integer, _ EnableState As Boolean, _ RtpCallback As VoipMediaEngine..::.RTP_CALLBACK_PROC, _ UserData As Object _ ) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE |
| Visual C++ |
|---|
public: VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableRawRtpPacketAccess( VoipMediaEngine^ MediaEngine, int PhoneLine, bool EnableState, VoipMediaEngine..::.RTP_CALLBACK_PROC^ RtpCallback, Object^ UserData ) |
| J# |
|---|
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE EnableRawRtpPacketAccess( VoipMediaEngine MediaEngine, int PhoneLine, boolean EnableState, VoipMediaEngine..::.RTP_CALLBACK_PROC RtpCallback, Object UserData ) |
Parameters
- MediaEngine
- Type: LanScape..::.VoipMediaEngine
An instance of the media engine.
- PhoneLine
- Type: System..::.Int32
The zero based phone line to enable or disable RTP packet access. Application software can enable/disable RTP packet access individually for each phone line.
- EnableState
- Type: System..::.Boolean
Specifies the enable state of RTP access for the phone line. If set to a non zero value, the media engine will send phone line RTP packets to application using the specified callback procedure.
- RtpCallback
- Type: LanScape..::.VoipMediaEngine..::.RTP_CALLBACK_PROC
The user supplied callback procedure of type VoipMediaEngine..::.RTP_CALLBACK_PROC. This procedure will be called by the media engine to communicate RTP media packet activity to the application. If your application registers the same callback procedure for all phone lines, make sure you follow proper multi-threaded programming practices. The callback procedure will be called by a different thread context for each phone line.
- UserData
- Type: System..::.Object
A user supplied variable reference. This data reference is passed to the RtpCallback procedure via the VoipMediaEngine..::.RAW_RTP_DATA data structure. This value an be NULL.
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 Value | Description |
|---|---|
| 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) |
| SipInvalidHandle |
Application software specified an invalid telephony handle in one of the API procedures.
This usually indicates memory corruption on the part of application software.
(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) |
| SipBadParameter |
One of the telephony API procedures was called by application software and was passed a pointer to an invalid
memory address. Normally this error will occur when application software passes NULL pointer values to the telephony API.
For managed code applications, you should never see this error unless your process space has exhausted memory.
(API return value) |
Remarks
To change receive RTP packet filtering behavior, your application software can call the FilterReceivedRtpPackets(VoipMediaEngine, Int32, VoipMediaEngine..::.RtpPacketAccess..::.FILTER_RECEIVED_RTP_PACKETS, Boolean) API procedure. Minimally, you will have to disable RTP payload ID filtering if received RTP packets have their RTP header values encrypted. You can disable RTP payload ID filtering by calling the FilterReceivedRtpPackets(VoipMediaEngine, Int32, VoipMediaEngine..::.RtpPacketAccess..::.FILTER_RECEIVED_RTP_PACKETS, Boolean) API procedure with the 'FilterType' parameter set to RTP_FILTER_BAD_PAYLOAD_ID and the 'EnableState' parameter set to FALSE.
In addition, if your received encrypted RTP packets are not the proper default size (in bytes) for the call, you will also have to disable receive RTP packet size filtering. You can disable RTP packet size filtering by calling the FilterReceivedRtpPackets(VoipMediaEngine, Int32, VoipMediaEngine..::.RtpPacketAccess..::.FILTER_RECEIVED_RTP_PACKETS, Boolean) API procedure with the 'FilterType' parameter set to RTP_FILTER_BAD_PAYLOAD_SIZE and the 'EnableState' parameter set to FALSE.
Under normal situations, application software should call the FilterReceivedRtpPackets(VoipMediaEngine, Int32, VoipMediaEngine..::.RtpPacketAccess..::.FILTER_RECEIVED_RTP_PACKETS, Boolean) API procedure before initiating an outbound encrypted call and before answering an incoming encrypted call. When the encrypted call terminates, application software should return the phone line to the default state by re-enabling the default filtering behavior of the phone line.
See Also
