The LanScape namespace is the focal point of your managed VOIP application development. Within this namespace, you have access to all of the powerful features the LanScape VOIP Media Engine™ has to offer.

Classes

  ClassDescription
VoipMediaEngine
The VoipMediaEngine class is the primary class for accessing all the capabilities of the LanScape VOIP Media Engine.
VoipMediaEngine..::.ASSIGN_INCOMING_PHONE_LINE
This object is passed to the applications when the media engine receives an incoming call. The media engine uses this object to communicate with the application in order to assign the incoming call to an available phone line. For further information, see the SipIncomingCallAssignPhoneLine immediate event.
VoipMediaEngine..::.AudioOut
Supports generic software based digitally mixed audio output support.
VoipMediaEngine..::.CHALLENGE_AUTHENTICATION
This object is passed to application software when the media engine’s authentication mechanism is enabled. Applications enable authentication events by calling the SetChallengeAuthenticationState(Boolean) API procedure. Once this is done, then SipIncomingAuthentication authentication events will be sent to the application along with an instance of this object for further processing.
VoipMediaEngine..::.CHALLENGE_ERROR_DATA
This class is used to pass challenge error information back to the application. The application creates an instance of this type and then calls one of the following API procedures to have the class initialized: GetChallengeErrorData(Int32, VoipMediaEngine..::.CHALLENGE_ERROR_DATA), GetRegisterChallengeErrorData(VoipMediaEngine..::.CHALLENGE_ERROR_DATA), GetSubscribeChallengeErrorData(UInt32, VoipMediaEngine..::.CHALLENGE_ERROR_DATA), and GetNotifyChallengeErrorData(UInt32, VoipMediaEngine..::.CHALLENGE_ERROR_DATA).

Normally your application will initialize the media engine with authentication credentials using the AddAuthorizationCredentials(String, String, String) API procedure. When the media engine performs an operation, it handles all of the details associated with processing an authentication challenge. If an authentication challenge response cannot be constructed based on the authorization credentials previously specified, then the media engine returns a value or sends an event to your application signaling that a challenge operation could not successfully be performed.

The challenge error data is available when you receive the API return values:

API Return ValueComments
SipEventNotifyNotAcceptedWhen you receive this return value as the result of calling the SendEventNotification(String, UInt32, UInt32%) API procedure, call the GetNotifyChallengeErrorData(UInt32, VoipMediaEngine..::.CHALLENGE_ERROR_DATA) API procedure to get the challenge error data for the NOTIFY operation.
SipRegisterAuthorizationErrorIf your application performs registrations using the and EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) API procedure and receives this return value, call the GetRegisterChallengeErrorData(VoipMediaEngine..::.CHALLENGE_ERROR_DATA) API procedure to get the challenge error data for the register operation.

Challenge error data is also available when you receive the following events:

Event ClassEventsComments
Phone Line EventsSipOutgoingCallDigestAuthenticationRequired, SipOutgoingCallBasicAuthenticationRequired, SipOutgoingCallUnsupportedAuthenticationWhen you receive these events, call the GetChallengeErrorData(Int32, VoipMediaEngine..::.CHALLENGE_ERROR_DATA) API procedure to get the challenge error data for out bound call operations.
Global EventsSipRegisterAuthorizationErrorWhen you receive this event, call the GetRegisterChallengeErrorData(VoipMediaEngine..::.CHALLENGE_ERROR_DATA) API procedure to get the challenge error data for the register operation. This event allows your application to track subsequent register operations as time progresses.
Immediate EventsSipSubscriptionRequiresAuthenticationWhen you receive this event, call the GetSubscribeChallengeErrorData(UInt32, VoipMediaEngine..::.CHALLENGE_ERROR_DATA) API procedure to get the challenge error data for the subscribe operation.

VoipMediaEngine..::.DTMF_DETECT_DATA
An object of this type is sent to your application when a stand alone DTMF decoder block detects incoming in-band DTMF tones. Supports both ON and OFF digit detection.
VoipMediaEngine..::.DTMF_EVENT_DATA
A reference to this class is passed to the media engine's main event handler VoipMediaEngine..::.SIPCALLBACKPROC whenever an incoming DTMF digit is detected. The contents of this class is used by application software to detect in-band and/or RFC2833 DTMF digit ON and OFF detections. Applications can access this data by processing the SipDtmfDigitEvent in the main media engine callback procedure.
VoipMediaEngine..::.DTMF_FAR_END_INFO
This class holds information about far end DTMF capabilities. In other words, what DTMF capabilities the far end of a call supports.
VoipMediaEngine..::.DTMF_GEN_DATA
An object of this type is sent to your application when a stand alone DTMF generator block generates a sample block containing in-band DTMF signals.
VoipMediaEngine..::.DtmfDecoder
Stand alone in-band DTMF decoder function blocks.
VoipMediaEngine..::.DtmfGenerator
Stand alone in-band DTMF generator function blocks.
VoipMediaEngine..::.FormatRateConverter
Stand alone Format and rate conversion function block support.
VoipMediaEngine..::.FREQUENCY_MAGNITUDE_TABLE_ELEMENT
Magnitude envelope table for inclusion into source code. Used to tune the DTMF detectors when non-standard tuning is required.
VoipMediaEngine..::.FREQUENCY_RATIO_TABLE_ELEMENT
Frequency ratio table for inclusion into source code. Used to tune stand alone DTMF detectors when non-standard tuning is required.
VoipMediaEngine..::.INCOMING_CALL_INITIALIZED_DATA
This object is passed to the applications when the media engine receives an incoming call and the incoming call setup initialization has been performed. For further information, see the SipIncomingCallInitialized immediate event.
VoipMediaEngine..::.IVR_RECOGNITION_DATA
Data struct passed to a user registered IVR callback procedure. Can be used to perform speech recognition of received phone line audio data or other signal processing of received audio.
VoipMediaEngine..::.LINE_STATE
Used to hold a phone lines current state.
VoipMediaEngine..::.LS_WAVEINCAPS
Encapsulates wave input device capabilities. For complete information, see the definition for the native WAVEINCAPS structure in the MSDN documentation.
VoipMediaEngine..::.LS_WAVEOUTCAPS
Encapsulates wave output device capabilities. For complete information, see the definition for the native WAVEOUTCAPS structure in the MSDN documentation.
VoipMediaEngine..::.Notify
Telephony Engine Notify event interface. Use this object when your VOIP application needs to send NOTIFY SIP requests to other SIP UAs or devices.
VoipMediaEngine..::.NOTIFY_REQUEST
This object is passed back to applications when the media engine receives event notifications.
VoipMediaEngine..::.PersistNotifyData
A data type that acts as a container for encoded persistent NOTIFY data. Used when saving/restoring NOTIFY client information when acting as a SIP NOTIFY server.
VoipMediaEngine..::.PHONE_LINE_RECORD_DATA
Data struct passed to a user registered phone line call record callback procedure. Used to allow the application to gain real time access to phone line recorded data.
VoipMediaEngine..::.PHONE_LINE_VU_METER_DATA
Data struct passed to a user registered phone line VU meter callback procedure. Used to allow the application to gain real time access to digitally mixed phone line sample data. Useful for driving VU meter displays in your application.
Note:
VU meter functionality shares the phone line's digital mixer that is used during phone call recording. You must configure the media enigne to enable call recording if you want VU meter sample data. This does not mean that call recording has to be active during any call in order to get VU meter sampled data. It just means the media enigne's phone line record digital mixers must be created to support VU merter callback functionaliy.
VoipMediaEngine..::.PhoneLineRecord
Create objects of this type to perform phone line recording.
VoipMediaEngine..::.PhoneLineVuMeter
Phone line VU meter data (Similar to the phone line recording class).
VoipMediaEngine..::.RAW_RTP_DATA
Data struct passed to an application that has enabled raw RTP packet access.
VoipMediaEngine..::.RECEIVED_RTP_MEDIA_CONFLICT
Data struct passed to an application when the media engine detects that RTP media for the call is not coming from the far end call endpoint as negotiated by SIP call setup. This data can be sent to the application if the media engine application is communicating with SIP user agents and the UAs are behind thier own NATs.
VoipMediaEngine..::.REGISTER_DETAILS
The REGISTER_DETAILS structure contains information to allow application software to determine if it wants to accept a registration request from another application or device.

If your application needs to perform registrar oriented services in support of other telephony applications or devices, then it can process the SipRegisterReceived event. When it does, it will have access to a REGISTER_DETAILS object in memory. Your application can take the contents of this object to determine if the far end entity can register with your application.

VoipMediaEngine..::.RTP_TRANSCEIVER_STATISTICS
The RTP_TRANSCEIVER_STATISTICS structure defines the information an application can request when calling the GetRtpTransceiverStatistics(Int32, VoipMediaEngine..::.RTP_TRANSCEIVER_STATISTICS) API procedure. RTP transceiver statistics can be used to monitor or determine RTP transmitter and receiver activity. One such use of this information is to detect RTP transmit and receive errors on a polled basis or to detect received media timeouts. The values contained in the structure are reset to zero at the beginning of each call.
VoipMediaEngine..::.RtpPacketAccess
Supports raw RTP media packet access.
VoipMediaEngine..::.RxIvrChannel
The RxIvrChannel object is used to access IVR receiver support on a per phone line basis. If you need to receive audio sample blocks from the media engine's phone lines (for example - if you are developing an IVR server application that use speech recognition), you will need to instantiate an instance of this class.
VoipMediaEngine..::.SIP_ACTIVE_CALL_INFO
Informatiion about the active call.
VoipMediaEngine..::.SIP_INCOMING_CALL_INFO
Information associated with an inbound phone call.
VoipMediaEngine..::.SIP_MESSAGE
Object used to encapsulate a RAW SIP message.
VoipMediaEngine..::.SIP_MESSAGE_IMMEDIATE_DATA
This object is passed to the applications when the media engine receives or is ready to transmit a SIP mesage. The application can use the information in this object to modify or ignore the received/transmiting SIP message when the application processes the SipModifySipmessage event.
VoipMediaEngine..::.SIP_MESSAGE_PARSE_IMMEDIATE_DATA
This object is passed to the applications when the media engine detects a parse error associated with a received SIP message. Passed to application software via the SipReceivedSipMessageParseError immediate event.
VoipMediaEngine..::.SIP_OUTGOING_CALL_ERROR_INFO
Extended error information associated with who we are calling.
VoipMediaEngine..::.SIP_OUTGOING_CALL_INFO
Information associated with who we are calling (Outgoing calls).
VoipMediaEngine..::.SPEECH_RECOGNITION_DATA
Data struct passed to a user registered speech recognition callback proc. Used for local speech recognition.
VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS
This object is used to specify startup parameters and values for the VOIP Media Engine.
VoipMediaEngine..::.Subscribe
Telephony Engine subscribe event interface.
VoipMediaEngine..::.SUBSCRIBE_REQUEST
This object is passed back to applications when the media engine receives event subscription requests.
VoipMediaEngine..::.SUBSCRIBE_RESULTS
This object is passed back to application space when the media engine's event subscription mechanism is active. When applications receive this information, it represents the results of event subscriptions that were sent to targets you previously specified. In other words, the media engine tried to subscribe to events offered by other devices/targets and this information gives us the result of the subscribe operation.
VoipMediaEngine..::.TELPHONY_ENGINE_VERSION_INFO
A reference to this class is passed to the GetMediaEngineVersionInfo(VoipMediaEngine..::.TELPHONY_ENGINE_VERSION_INFO) API procedure. After calling the API procedure, the structure members will be initialized to point to specific telephony system version information.
VoipMediaEngine..::.TxIvrChannel
The TxIvrChannel object is used to access IVR transmitr support on a per phone line basis. If your application needs to stream audio sample block data out ant of the media engine's phone lines, you will need to instantiate an instance of this class.
VoipMediaEngine..::.WAN_IP_NOTIFICATION
This object is passed back to applications when the media engine detects that its internal Wan IP address has been modified.
VoipMediaEngine..::.WaveFile
Wave file read support.

Delegates

  DelegateDescription
VoipMediaEngine..::.AudioRecordCallback_Delegate_def
VoipMediaEngine..::.DTMF_DECODER_CALLBACK_PROC
The DTMF_DECODER_CALLBACK_PROC data type is used by the telephony API to define a callback procedure that is used by the Media Engine's DTMF decoder functionality. This callback procedure is specified when application software calls the CreateDtmfDecoder(VoipMediaEngine, Boolean, Int32, Int32, Int32, Boolean, VoipMediaEngine..::.DTMF_DECODER_CALLBACK_PROC, Object) API procedure. This callback procedure is responsible for passing DTMF digit decode information back to the user's application.
VoipMediaEngine..::.DTMF_GENERATOR_CALLBACK_PROC
The DTMF_GENERATOR_CALLBACK_PROC data type is used by the telephony API to define a callback procedure that is used by the Media Engine's DTMF generator functionality. This callback procedure is specified when application software calls the CreateDtmfGenerator(VoipMediaEngine, VoipMediaEngine..::.DTMF_GENERATOR_CALLBACK_PROC, Object) API procedure. This callback procedure is responsible for passing generated DTMF sample blocks back to the user's application.
VoipMediaEngine..::.DtmfDecoder..::.DtmfDecoderCallback_Delegate_def
VoipMediaEngine..::.DtmfGenerator..::.DtmfGeneratorCallback_Delegate_def
VoipMediaEngine..::.IVRCALLBACKPROC
The IVRCALLBACKPROC data type is used by the telephony API to define a delegate that is registered with the telephony engine. This callback procedure is specified when application software calls the OpenRxIvrChannel(VoipMediaEngine, Int32, VoipMediaEngine..::.IVRCALLBACKPROC, Object, Boolean, VoipMediaEngine..::.AUDIO_BANDWIDTH, Int32%, Int32%, Boolean%) API procedure. This callback procedure is responsible for passing received phone line audio back to the user's application.
VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC
The PHONE_LINE_RECORD_CALLBACK_PROC data type is used by the telephony API to define a callback procedure that is registered with the telephony engine. This callback procedure is specified when application software calls the StartPhoneLineRecording(VoipMediaEngine, Int32, Boolean, Boolean, Boolean, Boolean, Int32, String, VoipMediaEngine..::.PHONE_LINE_RECORD_CALLBACK_PROC, Object) API procedure. This callback procedure allows application software to gain access to full duplex digitally mixed sample block data (phone call audio) on a per phone line basis.

This callback procedure allows applications to receive real time phone call recorded data.

VoipMediaEngine..::.PHONE_LINE_VU_METER_CALLBACK_PROC
The PHONE_LINE_VU_METER_CALLBACK_PROC data type is used by the telephony API to define a callback procedure that is registered with the telephony engine. This callback procedure is specified when application software calls the SetPhoneLineVuMeterCallback(VoipMediaEngine, Int32, VoipMediaEngine..::.PHONE_LINE_VU_METER_CALLBACK_PROC, Object) API procedure.

This callback procedure allows applications to receive real time full duplex digitally mixed phone call VU meter sample block data on a per phone line basis.

VoipMediaEngine..::.PhoneLineRecord..::.PhoneLineRecordCallback_Delegate_def
VoipMediaEngine..::.PhoneLineVuMeter..::.PhoneLineVuMeterCallback_Delegate_def
VoipMediaEngine..::.RTP_CALLBACK_PROC
The RTP_CALLBACK_PROC data type is used by the telephony API to define a callback procedure that is used by the Media Engine's raw RTP access functionality. This callback procedure is specified when application software calls the EnableRawRtpPacketAccess(VoipMediaEngine, Int32, Boolean, VoipMediaEngine..::.RTP_CALLBACK_PROC, Object) API procedure. This callback procedure is responsible for passing RTP media packet information to and from the user's 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.
Caution:
Important Note: This callback procedure will be executed by "time critical" code within the media engine. If you are using this functionality to perform RTP media stream encryption, make sure you perform your encryption encoding and decoding as fast as possible. Generally speaking, the media engine uses a 20Ms sample block time for all media related data (iLBC can also use 30Ms sample blocks). If you do not execute efficient code in this callback procedure, you may effect the "real time" behavior of the media engine.

If your encryption process takes time to execute, you also may want to register individual callback procedures for each phone line. This is in lieu of using a single callback procedure for all phone lines.

VoipMediaEngine..::.RtpPacketAccess..::.RtpPacketAccessCallback_Delegate_def
VoipMediaEngine..::.RxIvrChannel..::.RxIvrCallback_Delegate_def
VoipMediaEngine..::.SIPCALLBACKPROC
The SIPCALLBACKPROC delegate is used by the media engine to define a callback procedure that is registered with the telephony engine. This delegate is specified when application software calls the StartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) API procedure. This delegate is responsible for passing all telephony events back to the application software.

You should try to minimize the processing you perform in this event callback procedure. If you perform minimum event processing in this callback, the telephony engine will be able to process calls quickly. Spending too much time in this callback will slow down call session negotiations and call setup completion. If slower call setup is not critical to your application, you can spend as much time as required in this callback.

To allow the telephony engine to perform its tasks as smoothly and as quickly as possible, it is recommended that the PHONE_LINE_NOTIFICATION and GLOBAL_NOTIFICATION event notifications received by your callback be put into a fifo queue. Your application should then have one of its own threads process the fifo event data as appropriate.

Caution:
IMPORTANT - Thread Deadlock Information:

Internally the VOIP Media Engine is fully multi-threaded. The event callback mechanism is non-reentrant. Some media engine API procedures cannot be called from within the main media engine callback procedure. As a general rule: Any API procedure that can generate additional events cannot be called in the "main event handler" when processing the current event. If you call an API procedure that generates additional events while you are executing in the callback procedure, your VOIP application can deadlock. This is by design. Any API procedure that generates events back to your application must be executed by some other thread in your application. Some of the media engine API procedures that will generate events are: MakeCall(String, String, UInt32, Int32, Boolean, UInt32), MakeCallUri(String, Boolean, Int32, Boolean, UInt32), TerminateCall(Int32, Boolean, UInt32), GoOffHook(Int32), AbortIncomingCall(Int32, Int32, String), BusyOutLine(Int32, Boolean), HoldLine(Int32, Boolean), ConferenceLine(Int32, Boolean), TransferLine(String, String, Int32, Int32), TransferLineUri(String, Boolean, Int32), EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) and DisableSipRegisterServer()()().

Note:
If your application registers the same callback procedure with multiple instances of the telephony engine, you should use a critical section object to manage access to the callback procedure's code/data. Each instance of the telephony engine will execute your callback procedure using a differed thread context.
VoipMediaEngine..::.SIPCALLBACKPROC_Delegate_def
VoipMediaEngine..::.SPEECH_RECOGNITION_CALLBACK_PROC
The SPEECH_RECOGNITION_CALLBACK_PROC data type is used by the telephony API to define a callback procedure that is registered with the telephony engine. This callback procedure is specified when application software calls the SetSpeechRecognitionCallback(VoipMediaEngine..::.AUDIO_BANDWIDTH, VoipMediaEngine..::.SPEECH_RECOGNITION_CALLBACK_PROC, Object) API procedure. This callback procedure is responsible for passing all locally recorded audio back to the user's application. The audio data passed back to application software can be used for whatever purpose the application requires.
VoipMediaEngine..::.SpeechRecognitionCallback_Delegate_def

Enumerations

  EnumerationDescription
VoipMediaEngine..::.AUDIO_BANDWIDTH
Used to specify audio formats and rates.
VoipMediaEngine..::.AUTHENTICATE_MESSAGE_TYPE
The AUTHENTICATE_MESSAGE_TYPE enumeration is used to inform the application about the received SIP message type. The application can then decide if it wants to challenge the received message.
VoipMediaEngine..::.AUTHENTICATE_OPERATION
The AUTHENTICATE_OPERATION enumeration defines the types of authentication operations
VoipMediaEngine..::.CALL_DIRECTION
Indicates the call direction relative to the media engine.
VoipMediaEngine..::.CALL_HOLD_TYPE
Defines the type of call hold operation.
VoipMediaEngine..::.CHALLENGE_ALGORITHM
Specifies the authentication challenge algorithms supported.
VoipMediaEngine..::.CHALLENGE_MODE
Specifies the authentication challenge mode your application wants to enforce.
VoipMediaEngine..::.CHALLENGE_TYPE
Supported authentication challenge types.
VoipMediaEngine..::.DTMF_TONE
Defines the supported DTMF tones of the media engine's DTMF generators and decoders. The DTMF tones defined here apply to the fully integrated DTMF generation and detection the media engine supports. These DTMF tones (not including the Flash tone) are also fully supported by the media engine's stand alone DTMF generators and decoders.
VoipMediaEngine..::.FORMAT_RATE_STATUS
Defines return values from stand alone format/rate converter operations.
VoipMediaEngine..::.IN_CALL_PROCESS_PRIORITY
The process priority that the application will enter when at least one call is active.
VoipMediaEngine..::.LINE_MODE
Specifies the mode of how the media engine handles phone lines.
VoipMediaEngine..::.MEDIA_FORMAT_AUDIO
Used to specify audio formats and rates.
VoipMediaEngine..::.MEDIA_FORMAT_VIDEO
Used to specify video formats and rates. Video will be supported in a future release.
VoipMediaEngine..::.NOTIFY_TYPE
Allows the media engine to specify the type of notify request being received.
VoipMediaEngine..::.RtpPacketAccess..::.FILTER_RECEIVED_RTP_PACKETS
The FILTER_RECEIVED_RTP_PACKETS enumeration defines values that are used to specify how certain receive RTP packet errors are to be filtered/ignored. For additional information, see the FilterReceivedRtpPackets(VoipMediaEngine, Int32, VoipMediaEngine..::.RtpPacketAccess..::.FILTER_RECEIVED_RTP_PACKETS, Boolean) API procedure.
VoipMediaEngine..::.SIP_NOTIFY_TYPE
The type of event notification coming from the media engine. Sent to application code.
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Defines event values and return values the application can receive from the media engine.