The AbortIncomingCall procedure is called by application software to abort (Ignore) a received incoming phone call. When this API procedure is called, the media engine will send a SIP status response back to the other user agent or configured SIP proxy.

If your application will be challenged by other telephony software or devices, you can use this API procedure to specify authorization data that will be used to fulfill the far end's authorization challenge. This API procedure can be called multiple times with different authentication data. The authentication data is then maintained internally by the media engine. As your application software executes, the media engine inspects its internal list of authentication credentials to locate credentials that will fulfill any authorization challenge that may occur.

The BusyOutLine procedure is used to take a phone line out of service. When a phone line is out of service, you will not be able to make or receive phone calls on that line.

The ClearRecordedCallStates procedure can be called by application software to clear previously recorded call state information for the phone line. For complete details associated with call state recording, please see the SetCallStateRecording(Int32, Boolean) API procedure.

The ConferenceLine API procedure is used to add an "active call" to a conference session. An "active call" is any phone line that is in the SipInCall state. Note that conferencing capabilities are only possible on versions of the telephony engine that support two or more phone lines and when licensing allows conferencing to be enabled.

The simplest form of conferencing occurs when you have two simultaneous phone calls active. You could be talking to one of the parties while the other is on hold. Alternatively, both calls could be placed on hold. To create a conference session with you and the two other parties, you would call the ConferenceLine API procedure using the appropriate phone line each call is assigned to. Once both active phone lines are added to the conference session, all parties will be able to talk and hear each other using full duplex audio.

As an added benefit, the telephony engine's conferencing functions automatically handle the details associated with conferencing parties that are using different audio formats and rates. Your application software does not have to perform any other operation other than to specify who should be included in the conference session.

While in a conference session, any line can be placed on hold or terminated. If one of the conference participants is placed on hold, they can be brought back into the conference session at a later time by calling ConferenceLine again on that particular phone line.

Once you have established a conference session, you can terminate the session by placing all conference session phone lines on hold or by hanging up the lines.

The ConnectIncomingCallWithoutInviteAck function allows an application to specify that the VOIP Media Engine should enter the "In Call" state for incoming phone calls even though a final INVITE ACK was not received from the far end of the call. Normally an application does not have to call this API procedure unless the far end SIP device does not handle the SIP protocol properly.

If you are having problems connecting inbound phone calls, you must determine if the far end of the call ever sent the final INVITE ACK SIP message. If it does, you probably have a time-out issue. In that case, you might have to increase the final ACK time-out value using the SetInboundInviteAckTimeout(UInt32) API procedure. If you have determined that the far end SIP device does not transmit final INVITE ACKs properly, you can still get the VOIP Media Engine to connect the incoming call by calling this procedure.

If your application will be challenged by other telephony software or devices, you can use this API procedure to remove authorization credentials that were previously set using the AddAuthorizationCredentials(String, String, String) API procedure. After you call this procedure, the specified authorization credentials are removed from the internal list maintained by the media engine.

The DisableOutboundSipProxyServer procedure is used to disable the use of outbound SIP proxy server support.

The DisableSipDomain API procedure allows an application to discontinue the use of a previously specified telephony environment domain name. Before you disable a SIP domain name, you should terminate SIP proxy and registrar functions by calling the DisableSipProxyServer()()() and DisableSipRegisterServer()()() API procedures.

The DisableSipProxyServer procedure is used to disable the use of a SIP proxy server support.

The DisableSipRegisterServer procedure is used to terminate the use if SIP registrar capabilities. If the telephony engine was previously registered with a SIP registrar server, calling this API procedure will force an "unregister" operation and terminate further access to the previously defined registrar server. If your application previously registered with a SIP registrar server, you should call this API procedure before your application terminates.

EnableDialTone can be called by application software to enable or disable the ability of the telephony engine to present dial tone to the user when a phone line is taken off hook.

EnableIncomingPhoneRing can be called by application software to enable or disable the ability of the telephony engine to create an incoming phone ring tone when receiving an inbound call.

The EnableKeepAliveTransmissions API procedure can be called by application software to enable or disable an alternate form of SIP "Keep-alive" traffic. It is also used to control RTP "Keep-alive" traffic.

SIP session "Keep-alive":

If your application communicates with a proxy and registrar, LanScape recommends that you use the SendSipKeepAlive(String, UInt32, Boolean, Int32) functionality of the media engine to send "NULL" SIP messages to your server. If you cannot use the SendSipKeepAlive(String, UInt32, Boolean, Int32) API procedure, then you can use REGISTER messages for SIP session "Keep-alive". See the EnableSipRegisterServer(String, Boolean, Boolean, String, UInt32, UInt32, UInt32, UInt32, Boolean) API procedure for further details.

If your application does not communicate with a proxy server and is situated behind NAT network elements, this alternate form of SIP "Keep-alive" may be of some use to you. This form of SIP "Keep-alive" is only useful if your application is communicating with anther SIP device located in the global network space (the internet) or is behind its own NAT that has been configured to allow port forwarding. When you call these types of far end SIP endpoints and you are behind NAT, the far end will not be able to communicate with your application unless your application keeps the network session open in your NAT device. You can keep a session open in your NAT device during a call if you enable SIP "Keep-alive" using this API procedure.

If you need to support the network environment described above, then you must enable SIP "Keep-alive" transmissions using this API procedure. Keep in mind that the "Keep-alive" SIP messages that are transmitted to the far end device only occur when a call is active. The media engine uses SIP OPTIONS messages for all "Keep-alive" network traffic.

RTP session "Keep-alive":

When RTP "Keep-alive" is enabled, the media engine makes sure that some voice data is transmitted during the specified interval. If no voice data is being generated by your application, a small amount of silence voice data will be transmitted. You might have to enable RTP session "Keep-alive" if you have enabled the noise discrimination (noise gate) capability of the media engine and you are having your RTP media proxied by a media proxy or boundary controller.

The EnableOutboundSipProxyServer procedure is used to specify the network address and UDP port of an outbound SIP proxy server. The telephony engine will then use the outbound proxy for all out going calls and requests. Note: You can enable both normal proxy support and outbound proxy support in your application.

EnableOutgoingBusySignal can be called by application software to enable or disable the ability of the telephony engine to create a busy signal tone when placing an outgoing call and the far end is busy.

EnableOutgoingDtmfDigits can be called by application software to enable or disable the ability of the telephony engine to present dialed DTMF tones to the user when an out going phone call is placed. If DTMF tones are enabled, the tones a user hears represent the IP address of the call destination.

EnableOutgoingErrorSignal can be called by application software to enable or disable the ability of the telephony engine to create an error (fast busy) tone when placing an outgoing call and the far end indicates a call error.

EnableOutgoingPhoneRing can be called by application software to enable or disable the ability of the telephony engine to create an outgoing phone ring when an out going phone call is placed.

The EnableRfc2833DtmfLogging API procedure allows applications to log all transmitted and received RFC2833 DTMF traffic on a per phone line basis. This feature is useful for debugging.

The EnableSipDomain API procedure allows an application to specify the domain name of the telephony environment. You must call this API procedure prior to using any of the SIP proxy and/or SIP registrar services.

The EnableSipProxyServer procedure is used to specify the network address and UDP port of a SIP proxy server. The telephony engine will then use the proxy for all out going calls in addition to receiving information from the proxy for in coming calls.

The EnableSipRegisterServer API procedure is used to specify the network address and UDP port of a SIP registrar server. Registrar servers are used to keep track of SIP enabled devices within a domain. Depending on the registrar server you use, registrar and proxy functions are often the same server entity.

If this API procedure is called, the telephony engine will immediately perform a "register transaction" using the specified registrar server. The telephony engine will then on a periodic basis, update the registrar server with current registration information.

Note also that register functions can also be used to generate SIP "Keep-alive" traffic between your application and the proxy/registrar server. "Keep-alive" traffic may be important if you deploy your applications in network environments where NAT routers and/or firewalls are present. If your application communicates with a proxy and registrar, LanScape recommends that you use REGISTER messages for session "Keep-alive" if you cannot use the normal SendSipKeepAlive(String, UInt32, Boolean, Int32) API procedure.

For additional information regarding SIP and RTP "Keep-alive" capabilities, please see the EnableKeepAliveTransmissions(Boolean, Boolean, UInt32) API procedure.

The FilterEventLogServerEvents API procedure can be called to specify one or more remote event log events you want filtered. Events that are filtered will not be sent to a remote event log server even though you have an event log server enabled. The primary purpose of this API procedure is to allow application software to filter out any events that are not important for the current operation you are investigating or debugging. A good use of this API procedure is to filter out all SipModifySipMessage immediate events.

You can call this procedure as many times as required to add your event filter values to the internal filter list maintained by the media engine.

The GetActiveCallInfo can be called by a user application when the telephony engine indicates that call information for a specific phone line has been established or some line characteristic has changed.

Generally you would call this procedure when the event callback sends you one of the following events: SipIncomingCallConnected, SipOutgoingCallConnected, SipCallHoldOn, SipCallHoldOff, SipFarEndHoldOn, SipFarEndHoldOff, SipInConferenceOn or SipInConferenceOff. For further information see VoipMediaEngine..::.TELEPHONY_RETURN_VALUE.

The GetCallInstanceData API is used when an application is receiving call instance data with a phone call. This API procedure is used by the receiving end of a call to obtain a copy of the call's instance data. Call instance data can be ASCII or raw binary data and its format is dictated by the application. Call instance data that is part of a phone call can be used for whatever reasons the application requires.

Generally you would call this procedure when the event callback sends you the SipIncomingCallStart or the SipTransferExecuting event indication.

The GetCallInstanceDataLength API is used when an application is receiving call instance data with a phone call. This API procedure is used by the receiving end of a call to obtain the number of bytes in the call's instance data. Call instance data can be ASCII or raw binary data and its format is dictated by the application. Call instance data that is part of a phone call can be used for whatever reasons the application requires.

Generally you would call this procedure when the event callback sends you the SipIncomingCallStart or the SipTransferExecuting event indication.

When initiating out bound calls, your application will be notified when authentication challenges fail and your phone call can not be completed. If this is the case, then your application may receive one of the following phone line events:

SipOutgoingCallDigestAuthenticationRequired
SipOutgoingCallBasicAuthenticationRequired
SipOutgoingCallUnsupportedAuthentication

When your application processes these events, you can call the GetChallengeErrorData(Int32, VoipMediaEngine..::.CHALLENGE_ERROR_DATA) API procedure to obtain the challenge error data. Applications use this challenge error data to display "authorization required" messages to users.

The GetDigitalAudioInputDevice procedure allows the application software to obtain the device capabilities for the specified audio input device.

The GetDigitalAudioOutputDevice procedure allows the application software to obtain the device capabilities for the specified audio output device.

The GetDtmfPhoneLineAmplitude API procedure allows applications to retrieve the current volume of outgoing in-band and RFC2833 DTMF information being transmitted from the phone line.

The SetDtmfPlaybackAmplitude API procedure is used to set the volume of all DTMF tones played back on local multimedia hardware.

The GetDtmfToneStateMap API procedure allows an application to receive a bit map of what DTMF tone is turned ON by the API for the specified phone line. This API is faster than calling the IsDtmfToneOn API procedure multiple times in a row for all possible DTMF digits.

The GetEnableJitter procedure allows user software to receive the current enable/disable state of jitter compensation for the specified phone line.

The GetFarEndDtmfInfo API procedure is used to determine the type of DTMF supported by the far end of a call.

For outgoing calls:

This API procedure can be called anytime after the media engine sends the SipOutgoingCallConnected event to the application.

For incoming calls:

This API procedure can be called anytime after the media engine sends the SipIncomingCallStart event to the application.

For most applications, this API procedure can simply be called when the call enters the SipInCall state. The application can then save the returned API data to a temporary location and refer to it as required for the duration of the call.

The SetInBandDtmfDecoderEnableState API procedure is used to enable and disable in-band DTMF decoding for the specified phone line. Application software can call this procedure any time.

The GetInBandDtmfSignalThreshold API procedure allows the application to retrieve the current DTMF detection threshold.

The GetInBandDtmfTwist API procedure allows the application to retrieve the current allowed forward and reverse twist of the DTMF input signal.

The DtmfDecoderGetMinimumDigitOnTime API procedure allows an application to retrieve the current minimum digit ON time for the DTMF decoder.

The GetIncomingCallInfo can be called by a user application when the telephony engine indicates that an incoming SIP call is available via the callback event interface.

Generally you would call this procedure when the event callback sends you the SipIncomingCallStart indication. The incoming call information that will be made available to you is contained in a structure variable of type VoipMediaEngine..::.SIP_INCOMING_CALL_INFO.

The GetJitterTimeMs procedure returns to the caller the current jitter time in milliseconds for the specified phone line.

The GetLineStatus API procedure can be called asynchronously by application software to determine the current state of any phone line.

The GetMaxNoiseThreshold procedure allows the application software to obtain the maximum signal threshold that is used for all RTP transmitter DSP computations. This value is shared by all phone lines.

The GetMaxNumPhoneLines API is used to determine the maximum number of phone lines the telephony engine will support. The maximum number of phone lines supported by your telephony engine is a function of the license options you purchased.

The GetMediaEngineVersionInfo API procedure can be called by application software to obtain internal revision information for the telephony engine and all of its software subsystems.

This API procedure can be called anytime. An instance of the telephony engine does not have to be created before calling this procedure.

The GetMinNoiseThreshold procedure allows the application software to obtain the minimum signal threshold that is used for all RTP transmitter DSP computations. This value is shared by all phone lines.

The GetMuteReceivedPhoneLineAudio procedure can be used to obtain the current phone line receive audio mute state. To set the phone line mute state for received audio, see the SetMuteReceivedPhoneLineAudio(Int32, Boolean) API procedure.

The GetMuteTransmitPhoneLineAudio procedure can be used to obtain the current phone line transmit audio mute state. To set the phone line mute state for transmitted audio, see the SetMuteTransmitPhoneLineAudio(Int32, Boolean) API procedure.

The GetNoiseDiscriminationEnableState procedure returns to the caller the current noise discrimination enable/disable state.

The GetNoiseThreshold procedure allows the application software to obtain the current signal threshold that is used for all RTP transmitter DSP computations. The value returned by this procedure is shared among all phone lines the telephony engine supports. It will be in the range of values as returned by the GetMinNoiseThreshold(UInt32%) and GetMaxNoiseThreshold(UInt32%) API procedures.

When performing notify event operations, your application will be signaled when notify authentication challenges fail and notify operations can not continue.

If this is the case, then your application will receive the return value SipEventNotifyNotAccepted from the SendEventNotification(String, UInt32, UInt32%) API procedure when attempting to send events to other applications or devices.

The GetNumActiveCalls API procedure can be called at any time in order to retrieve the total number of phone calls that are active. Any phone line that is in the SipInCall state is considered an active call.

The GetNumberOfCallsInProgress API procedure can be called by application software to determine the total number of calls that are in progress. A call is considered "in progress" if the phone line is not in any of the following states: SipOnHook, SipCallComplete or SipBusyOut.

The GetNumDigitalAudioInputDevices procedure allows the application software to determine the number of multimedia audio input devices supported by the host system.

The GetNumDigitalAudioOutputDevices procedure allows the application software to determine the number of multimedia audio output devices supported by the host system.

The GetNumPhoneLines API is used to determine the number of phone lines the telephony engine is currently managing. This is the same number of phone lines that was specified by the user when the telephony engine was created. The number of phone lines returned by this API procedure will be less than or equal to the total number of lines you are licensed to use.

The GetNumRecordedCallStates procedure is called by application software to obtain the number of call states that have been recorded for the specified phone line. In order for this API procedure to be of any use, applications software should enable phone line call state recording using the SetCallStateRecording API procedure.

The GetOutgoingCallErrorInfo API procedure can be called by a user application to retrieve additional error information associated with an outgoing call. Under normal operating conditions, a far end SIP device or gateway may respond to a call initiation (INVITE request) by sending back an error response indication.

Application software can call this API procedure any time after it receives the SipFarEndIsBusy or SipFarEndError events from the media engine to retrieve the error information. Note that your application software should also call this API procedure before terminating the phone call using the TerminateCall(Int32, Boolean, UInt32) API procedure.

The out going call information that will be made available to you is contained in a structure variable of type VoipMediaEngine..::.SIP_OUTGOING_CALL_ERROR_INFO.

The GetOutgoingCallInfo can be called by a user application when the telephony engine indicates that we are in the process of placing an out going call or we are in the process of being transferred to a new location.

Generally you would call this procedure when the event callback sends you the SipOutgoingCallStart or the SipTransferingCall indication. The out going call information that will be made available to you is contained in a structure variable of type VoipMediaEngine..::.SIP_OUTGOING_CALL_INFO.

The GetPhoneLineLoopBack procedure can be used to get the current loop back state of a phone line.

The GetRecordedCallStates procedure is called by application software to access the internal list of call states that have been recorded for the specified phone line.

In order for this API procedure to be of any use, applications software should enable phone line call state recording using the SetCallStateRecording(Int32, Boolean) API procedure.

The GetRegistationTimeOut procedure returns to the caller the registration timeout value in milliseconds. The registration timeout value is used by the media engine to detect registration timeouts. If the media engine attempts a registration to a server and does not receive a response within the set registration timeout value, a SipRegistrationTimeOut event will be sent to the application.

When performing register operations with registrar servers, your application will be notified when authentication challenges fail and registration operations can not continue.

If this is the case, then your application will receive the return value and the global event SipRegisterAuthorizationError. For either indication, you can call the GetRegisterChallengeErrorData(VoipMediaEngine..::.CHALLENGE_ERROR_DATA) API procedure to obtain the register challenge error data. Applications use this challenge error data to display registration "authorization required" messages to users.

The GetRfc2833DtmfDecoderEnableState API procedure is used to retrieve the current enable/disable state of the phone line's RFC2833 DTMF decoder.

The GetRtpTransceiverStatistics procedure allows application software to access RTP transceiver statistical information on a per phone line basis. Application software can call this API procedure to determine such things as total number of received and transmitted RTP media packets and total transmitted and received RTP packet errors.

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 RTP statistic values are reset to zero at the beginning of each call.

The GetSilenceDecay procedure will return to the caller the current time value associated with "noise" threshold silence decay. The value returned is in milliseconds.

When performing event subscription operations, your application will be notified when authentication challenges fail and subscription operations can not continue.

If this is the case, then your application will receive the immediate event SipSubscriptionRequiresAuthentication. Application software can then call the GetSubscribeChallengeErrorData(UInt32, VoipMediaEngine..::.CHALLENGE_ERROR_DATA) API procedure to obtain the subscribe challenge error data. Applications use this challenge error data to display subscription "authorization required" messages to users.

The GetTelephonyStatusString API procedure can be called by application software to retrieve an ASCII string representation of all status values specified in the VoipMediaEngine..::.TELEPHONY_RETURN_VALUE enumeration.

This API procedure is generally used during application development.

This API information is preliminary and subject to change.

This API procedure is not currently documented.

The GoOffHook API procedure is called by application software to accept (answer) an incoming phone call. This procedure can be called any time after the telephony engine event callback sends your application software the SipOkToAnswerCall event.

The HoldLine procedure is used to place a phone call on hold. Calling this procedure also notifies the far end of the call with the appropriate hold state. Any number of phone lines that are active can independently be place into or removed from the hold state.

When you place a call on hold, you have the ability to stream audio data to the far end for the duration of the hold operation. For more information regarding streaming audio data to a line that is on hold, see API procedure TransmitOnHoldIvrData(array<Object>[]()[]).

The InitializeRfc2833DtmfDecoder API procedure can be called to initialize RFC2833 DTMF detection for a phone line. Once RFC2833 DTMF detection is initialized and enabled, the media engine will send the SipDtmfDigitEvent events to the application whenever ON or OFF DTMF digit transitions are detected. See the SetRfc2833DtmfDecoderEnableState(Int32, Boolean) API procedure for information regarding enabling RFC2833 DTMF detection for the phone line.

The IsDtmfToneOn API procedure is used to determine if a DTMF tone is currently playing. If you have to verify multiple DTMF tones, you should call the GetDtmfToneStateMap API procedure.

The IsUserNameRegistered procedure allows applications to query the media engine for the current registration state of a user name (phone line extension). Usually applications call this API procedure when processing the SipRegisterSuccess and SipUnRegisterSuccess events. It can however be called anytime.

This API information is preliminary and subject to change.

This API procedure is not currently documented.

The LogPhoneLineSipMessages API procedure can be called if you want to generate SIP log files for individual phone lines. Useful for debugging SIP session related problems.

The MakeCall API procedure is executed by application software to initiate out going phone calls.

The MakeCallUri procedure is called by application software to initiate an outbound phone call using a SIP URI. It is similar in functionality to the MakeCall(String, String, UInt32, Int32, Boolean, UInt32) API procedure.

The ModifySipMessage API procedure can be called by application software to change the contents of a received or ready-to-be-transmitted SIP message. This API procedure can only be called when an application processes the SipModifySipMessage event.

The MutePlaybackAudio procedure can be used to mute all audio that gets played back to the host machine's local multimedia hardware. While local audio playback is muted, the media engine will not play back any audio to the host machine's multimedia hardware.

The MuteRecordAudio procedure can be used to mute recorded (microphone) audio that comes from local multimedia hardware. If locally recorded audio is muted, the host machine's recorded audio will not be transmitted out any of the media engine phone lines when VOIP calls are active.

The PlaybackReceivedRFC2833Dtmf API procedure controls whether incoming RFC2833 DTMF is played back on local multimedia hardware. Normally, in-band DTMF audio information in the call's media channel is not present when using RFC2833 DTMF. If your application needs to "hear" received DTMF from the far end of the call (such as a soft phone), you will want to enable local playback of received RFC2833 DTMF signals.

The RandomlyAssignIncomingCallsToPhoneLines API procedure allows application software to change the way incoming calls are mapped to available phone lines. This API procedure is similar to the behavior of the RandomlyAssignIncomingCallsToPhoneLines startup parameter that is specified in the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS class.

The RegistationErrorRetryTime procedure is used to specify the amount of time to delay before retrying a failed registration attempt. By default, the VOIP Media Enigne will wait 5000 milliseconds before retrying a failed registration.

The ReStartSipTelephony function allows you to stop and then restart the telephony engine using a single API procedure. It is added to the API to simplify operations. You would typically use this procedure to halt a currently running telephony engine and restart a new instance (possibly using a different SIP port and/or and RTP port ranges.

The SendOptionsForInboundCall API procedure can be called by application software to enable or disable the transmission of OPTIONS SIP messages for inbound calls. In some NAT/router/firewall network environments, this may be required in order to allow a network session to be established between the two call endpoints.

For most situations, you do not need to use this API procedure. It is generally used when call endpoints interact with each other directly and not through a proxy server. If you have a proxy server configured that is using Record routing, this API procedure will do nothing.

The SendSipKeepAlive API procedure can be used to send "NULL" SIP protocol messages to any destination you require. A "NULL" SIP message contains a single carriage return - line feed pair (<CR><LF>).

This capability is most often used to keep open a NAT router session when your application communicates with its SIP proxy server. If your SIP proxy cannot handle NULL SIP messages without generating warnings or errors, then you can keep your NAT router session open by registering with the SIP proxy at an interval that is shorter than your NAT router session. Using the SendSipKeepAlive API procedure is preferable to re-registering because it takes less processing power on the part of your VOIP application and your proxy server.

The SendUdpDatagram API procedure can be called by application software to send a user defined UDP datagram to any remote destination host:port address. Applications can use this API procedure anytime. The media Engine does not have to be initialized or started. This procedure is generally used by applications to send application defined data to remote UDP log servers.

If your application intends to send its own SIP formatted protocol messages, you should not use this API procedure. Instead, use the SendUdpDatagramUsingSipPort(Object, String, Int32) API procedure. Doing so will ensure symmetrical SIP session signaling between your VOIP application and the far end SIP server or device.

The SendUdpDatagramUsingSipPort API procedure can be called by application software to send a user defined UDP datagram via the media engine's assigned SIP UDP port to any remote destination host:port address.

This capability is useful if applications want to create and transmit their own formatted SIP messages for transmission. Calling this API procedure when your application wants to transmit a custom SIP message will ensure symmetrical SIP session signaling between your VOIP application and the far end SIP server or device. Symmetrical SIP signaling is important in order to overcome issues associated with most NAT and firewall network elements.

The SetAudioMediaFormat function allows you to specify the single outgoing media type (codec) for each phone line supported by the telephony engine. All phone lines that are supported by the telephony engine can be set to the same media type. Alternatively, you can set the media type of individual phone lines to whatever your application requires. You can configure the phone lines in any media combination you need.

When the telephony engine places an out bound call, the single media format (codec) that will be used for the call is the media format specified by the MediaFormat parameter.

When the telephony engine receives an in-bound call, one or more media formats (codecs) will be requested by the far end (the initiating side of the call). The telephony engine will determine the lowest bandwidth codec from the list of codecs that is specified in the call's INVITE SIP message.

If you want to initiate and receive calls using a specific set of enabled codecs (more than one codec), please see the SetAudioMediaFormats(Int32, array<VoipMediaEngine..::.MEDIA_FORMAT_AUDIO>[]()[]) API procedure.

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.

When incoming request authentication is enabled, the media engine uses random internally generated authentication data that is associated with the authentication challenge. This time varying data is used internally and is not known by your application. It is used to give the Digest authentication mechanism additional means by which to enhance access protection and session security. If you are familiar with "nonce" values and Digest authentication, you should assume this API procedure controls the "stale" nature of authentication parameters.

The SetCallAnswerTimeout function allows you to specify the time that must elapse in order for the media engine to ignore an incoming phone call. After the specified time interval has elapsed for the incoming phone call, the media engine will terminate incoming ring and ignore the call.

The SetCallCancelTimeout procedure allows an application to control how long the media engine will wait for outgoing call CANCEL responses from the far end of the call.

When the media engine transmits a CANCEL request for an outgoing call, it expects to receive a "200 OK" response for the transmitted CANCEL request and a "487 Transaction Terminated" response for the initial INVITE request. Note that the "487 Transaction Terminated" response received will also be answered by a final ACK from the media engine.

The media engine will then wait the "CallCancelTimeout" as set by the API procedure for the "200 OK" response. It will also wait the "CallCancelTimeout" for the "487 Transaction Terminated" response. The order of these responses does not matter. If the media engine does not receive both expected responses, the phone call will proceed with cancel termination. If the responses arrive after the time out as set by the API procedure, the responses will be ignored.

The SetCallHoldType function allows you to specify the type of call hold logic that will be used by the Media Engine.

There are two basic types of call hold logic that are acceptable. One type is defined by RFC2543 (c=0.0.0.0) and the newer call hold type as defined by RFC3261 (sendonly/recvonly).

By default, the Media Engine uses both types at the same time. If however there is a situation that dictates that you use a specific call hold type, call this API procedure to achieve the results you require.

The SetCallInstanceData API is used when an application is transmitting call instance data with a phone call. This API procedure is used by the transmitting end of a call to specify the actual byte values of the call's instance data. Call instance data can be ASCII or raw binary data and its format is dictated by the application. Call instance data that is part of a phone call can be used for whatever reasons the application requires. Generally, an application should associate no more than 512 bytes of instance data with any phone call in order for UDP network packets to remain as small as possible. However, there is no maximum limit imposed on user defined call instance data.

Generally you would call this procedure when the event callback sends you the SipOutgoingCallInitializing or the SipOutgoingTransferInitializing event indication.

The SetCallStateRecording procedure is called by application software to enable or disable call state recording for the specified phone line. This API procedure should be called before the phone line is used by the application for incoming or outgoing calls.

Call state recording allows VOIP applications to view all call states a phone line progresses through as the call is being connected and terminated. This capability is most useful while developing and debugging your VOIP application.

If your VOIP call fails, all you have to do is enable call state recording and all the state transitions for the phone line will be recorded for the duration of the call. The call state list that is created can be inspected to locate error states that may help you in determining the exact cause of the call failure. This is especially useful if your application asynchronously uses the media engine API.

Call state recording can also be used to show you the call states that a phone line transitions through during normal call operations. This ability can be used as a learning tool to better understand the calls states of the VOIP Media Engine.

The internal call state list for the phone line is initially cleared. Your application code calls the SetCallStateRecording API procedure to enable call state recording for the phone line. During an incoming or outgoing call, all call states are recorded until the phone line transitions back to the "on hook" state. At that time, application software may call the GetNumRecordedCallStates(Int32, Int32%) and GetRecordedCallStates(Int32, array<VoipMediaEngine..::.TELEPHONY_RETURN_VALUE>[]()[]) API procedure to access the recorded call state data. Finally, your application software must call the ClearRecordedCallStates(Int32) API procedure to clear the previously recorded call states.

The SetCallTerminateTimeout function allows an application to specify the number of milliseconds that must pass before a call terminate operation (call hang-up) is considered to be in the time-out state. Generally application software does not need to call this API procedure unless a call endpoint is taking a very long time responding to your applications call termination requests. The internal default value for call termination time-out is 2000 Ms.

If your application is required to challenged requests coming from other applications or devices, this API procedure gives you the ability to enable or disable the media engine mechanism associated with inbound request authentication.

The SetConferenceGroupIds API procedure is used to define one or more conference group IDs for each phone line.

The media engine uses the concept of conference session IDs. Conference session IDs can be assigned to individual phone lines using the SetConferenceGroupIds API procedure. When your application places a phone line into the conference state using the ConferenceLine(Int32, Boolean) API procedure, the phone line will share full duplex audio data with any other phone lines that have the same congference IDs.

By assigning one or more conference group IDs to phone lines, your VOIP application can create simple to very complex conference relationships between phone lines.

By default each phone line belongs to the default conference session "0". In this case, placing all lines into conference mode will allow all lines to share full duplex audio data between them. This corresponds to a single conference session model.

If you wanted to group lines into separate individual conference sessions, you would call the SetConferenceGroupIds API procedure to set specific conference session IDs for whatever phone lines you would want to use. Then you would place all lines of interest into the conference mode using the ConferenceLine(Int32, Boolean) API procedure. For additional details, see the remarks section at the bottom of this topic.

The SetDefaultReceiveIlbcFrameMode API procedure is used to set the default iLBC frame mode for received phone calls that do not contain the "mode=" parameter in the calls INVITE sdp information.

Normally you should not call this procedure unless you want to change the default iLBC mode from 30Ms to 20Ms for ill-behaved SIP clients.

The SetDtmfPhoneLineAmplitude API procedure allows the application to specify the volume of outgoing DTMF information being transmitted from the phone line. For RFC2833 DTMF signals, this amplitude value gets converted to values in the range of 0dB to -36dB and then placed into the Volume field of the RFC2833 DTMF payload. For in-band DTMF signals, this value is used to linearly scale the amplitude of the transmitted DTMF samples from 0 to 32767.

The SetDtmfPlaybackAmplitude API procedure is used to set the volume of all DTMF tones played back on local multimedia hardware.

The SetEnableJitter procedure is used to set the enable/disable state of jitter compensation for the specified phone line.

The SetEventLogServer API procedure can be called to specify the network location of an event log server. Using an event log server will give you the ability to view VOIP Media Engine events as they are sent to application software in real time.

This capability is generally used during system debug cycles or to gather further understanding regarding the media engine's event behavior. Event logging can be used for whatever purpose your application requires. A nice feature of real time event logging to a server is the ability to see media engine events in real time. You no longer have to stop your VOIP application to view static log files. The event log server capability can be used at any time - even during media engine start up.

For details associated with enabling event logging when the media engine is initially started, please refer to the EnableEventLogServer, EventLogServer and the EventLogServerPort members of the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS structure.

Application software can call this procedure as many times as required in order to configure more that one remote event log server.

The SetFromHeaderUserName API procedure can be called by application software to specify a temporary "username" that will appear in the SIP "From" header field of a transmitted INVITE message when making the next outgoing call using the MakeCall(String, String, UInt32, Int32, Boolean, UInt32) or MakeCallUri(String, Boolean, Int32, Boolean, UInt32) API procedures.

This capability is useful if an application wants to call various voice mail boxes of a voicemail server without having to change the phone name for all phone lines. In this case, the username of the SIP "from" header can be temporarily modified a single time for the outgoing call so that the voicemail server can determine what voicemail box to access.

When the call is terminated, the default phone name will be used in subsequent SIP "From:" header fields and calls for the phone line.

The SetInBandDtmfDecoderEnableState API procedure is used to enable and disable in-band DTMF decoding for the specified phone line. Application software can call this procedure any time.

The SetInBandDtmfEventTrigger API procedure is used to fine tune how the media engine handles incoming DTMF events. Generally speaking, application software should not call this API procedure unless directed by LanScape support.

The SetInBandDtmfSignalThreshold API procedure can be called to specify the DTMF signal detection threshold for the phone line. DTMF will only be detected by the phone line's DTMF decoder if the incoming DTMF signal power is greater than the power threshold as set by this API procedure. For most application deployments, the default signal threshold for the DTMF decoder should be adequate and you should not have to call this API procedure.

The SetInBandDtmfTwist API procedure allows the application to specify the range of acceptable forward and reverse twist of the DTMF input signal.

The SetInBandMinimumDigitOnTime API procedure can be called by application software to specify the minimum digit ON time for a detected DTMF digit.

Minimum digit ON time is generally set to 40Ms in order to comply with standard in-band DTMF requirements. However, for noisy DTMF signals, specifying a larger DTMF ON time improves noise immunity, improves "talk off" performance and reduces false DTMF digit detections (false positives).

The SetInboundInviteAckTimeout function allows an application to specify the number of milliseconds to wait for the final SIP ACK response to be received from the far end of an incoming call. Normally an application does not have to call this procedure unless you are having problems connecting incoming calls. If the final ACK for the inbound call is not received, the call will not connect unless you have configured the VOIP Media Engine to ignore the reception of final ACKs using the ConnectIncomingCallWithoutInviteAck(Boolean) API procedure.

The SetInCallProcessPriority can be called by application software to modify the current operating system process priority of the telephony engine and the end user's application. The following process priorities can be specified:

PriorityNormal
PriorityHigh
PriorityRealtime

For further information regarding process priorities, see data type VoipMediaEngine..::.IN_CALL_PROCESS_PRIORITY.

Depending on operating system loading, the end user application may want to increase the process priority when it is known that telephony functions will be used in a high demand system. By default, the telephony engine operates under "priority normal" for all conditions unless you call this API procedure.

If no phone calls are active, the telephony engine maintains the "priority normal" state. As soon as an out going or incoming phone call is active, the telephony engine will shift to the process priority specified by the InCallProcessPriority parameter.

When all phone calls terminate, the telephony engine will again enter the "priority normal" state.

The SetIncomingDtmfDigitLossTimeout API procedure is used to specify when the media engine is able to detect lost DTMF digits. The IncomingDtmfDigitLossTimeoutMs parameter value specified by this API procedure sets the maximum time the media engine will tolerate no longer detecting an ON state for a currently ON DTMF digit. This time out value gets assessed as soon as the media engine detects either an incoming in-band or RFC2833 DTMF digit at a phone line. If the media engine does not continually receive further indications from a phone line's RTP receiver logic that the DTMF digit is still ON, the media engine will time out the digit and send the application a DTMF OFF event. This allows the media engine to gracefully handle DTMF OFF indications due to network errors or network cable being unplugged in the middle of receiving DTMF information.

The SetJitterTimeMs procedure allows user software to set the phone line jitter compensation time.

The SetLocalAudioLoopback API procedure is used to enable and disable the loop back of locally recorded audio data to the media engine's local audio playback path. If loop back is enabled, recorded audio samples are sent directly to the internal telephony engine playback subsystem.

Local audio loopback is disabled by default.

The SetLocalAudioLoopbackVolume API procedure is used to set the volume level of local recorded audio that is being looped back for playback. Controllable Volume gain is in the range of 0% to 400%.

The SetMuteReceivedPhoneLineAudio procedure can be used to mute received phone line audio. If phone line audio is muted for a phone line, the received phone call audio will not be played back on local multimedia hardware.

The SetMuteTransmitPhoneLineAudio procedure can be used to mute transmitted phone line audio. If phone line audio is muted for a phone line, locally recorded audio from multimedia hardware will not be transmitted out the phone line.

The SetNoiseDiscriminationEnableState procedure allows user software to enable transmit noise discrimination. The noise discrimination enable/disable state is applied to all phone lines the telephony engine supports.

The SetNoiseThreshold procedure allows the application software to specify the current signal threshold that is used for all RTP transmitter DSP computations. The value set by this procedure is shared among all phone lines the telephony engine supports. The noise threshold specified in the call to this API procedure must be in the range of values as returned by the GetMinNoiseThreshold(UInt32%) and GetMaxNoiseThreshold(UInt32%) API procedures.

The SetNumByeRetransmissions procedure allows an application to specify the number of additional BYE SIP messages that will be re-transmitted to a call endpoint in the event that a valid "200 OK" or error SIP response is not detected for the first BYE request that is sent.

This API procedure should not be used unless your application is having problems terminating calls with other SIP devices, servers or gateways. By default, the VOIP Media Engine will transmit a single BYE request to terminate a call. It then waits to receive the BYE acknowledge from the far end (usually a successful SIP "200 OK" response or a SIP error response). If the BYE response is not received within the time-out value programmed by the SetCallTerminateTimeout(UInt32) API procedure, then the VOIP Media Engine will send an additional number of BYE request as specified by this API procedure.

The SetOutgoingLineOnly function allows you to specify that a specific phone line be reserved for out-bound calling only. If a phone line is configured for "out going calls only", the media engine will never attempt to assign an incoming phone call to the line. Useful for multi-line VOIP Media Engines. Most often used to simplify internal application call manipulation logic.

The SetPhoneDisplayName function allows you to change the "display name" of any phone line of the telephony engine. By default, the display name of each phone line is set when you call the StartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) procedure. For most applications, phone line display names never need to be changed. There are application instances however that required that for a "specific call", the display name of the phone line be changed.

For additional information, see the remarks section below.

The SetPhoneLineLoopBack procedure is called to enable the looping back of received phone line audio data back to the transmit path of the same phone line. In other words, all data received on the phone line will immediately be echoed back to the far end. Note: Phone line loop back does not affect the reception of audio data. Your application will still receive audio data as normal.

Phone line loopback is disabled by default.

The SetPhoneLineVolume API procedure is called by application software to change the volume of transmitted and received voice data. Controllable Volume gain is in the range of 0% to 400%.

The SetPhoneName function allows you to change the name of any phone line of the telephony engine. By default, the name of each phone line is set when you call the StartSipTelephony(VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS) procedure. For most applications, phone line names never need to be changed. There are application instances however that required that for a "specific call", the name of the phone line be changed.

The name you assign to phone lines of the telephony engine can contain any alphanumeric characters, (a-z, A-z or 0-9), and any of the following characters: dash (-), underscore (_), period (.), exclamation point (!), tilde (~) or asterisk (*). Also, the phone name must not contain any "white space" characters.

Each instance of the telephony engine is considered a single phone set each with individually named lines. The SIP protocol uses this name when calling other IP phones. The SIP endpoint on the far end of a call normally displays this name to the user when detecting an incoming call.

The SetReceivedUnsolicitedNotifyState API procedure can be called by application software to allow the media engine to receive and process unsolicited received NOTIFY messages. Unsolicited received NOTIFY messages are not associated with an event subscription. Unsolicited NOTIFY messages are sent to the media engine by far end SIP devices as determined by the far end SIP device. If you interface with another SIP device or server that will send your VOIP application NOTIFY SIP messages without you having to SUBSCRIBE to the NOTIFY events, then you will want to call this API procedure to enable unsolicited NOTIFY processing. For further information, see the SipEventNotifyReceived event.

The SetRegistationTimeOut procedure allows application software to change the registration timeout value specified in milliseconds. The registration timeout value is used by the media engine to detect registration timeouts. If the media engine attempts a registration to a server and does not receive a response within the set registration timeout value, a SipRegistrationTimeOut event will be sent to the application.

The SetReinviteTimeout function is associated with call hold operations. It allows an application to specify the number of milliseconds that will be used to determine if a "call hold" or "call off hold" operation has timed out.

The SetRfc2833DtmfDecoderEnableState API procedure is used to enable and disable RFC2833 DTMF decoding for the specified phone line. Application software can call this procedure any time.

The SetRFC2833DtmfEventTrigger API procedure is used to fine tune how the media engine handles incoming DTMF events. Generally speaking, application software should not call this API procedure unless directed by LanScape support.

The SetRfc2833DtmfPayloadType API procedure allows the application to set the RFC2833 DTMF payload type that is used when a call is negotiated using the SIP protocol. Normally the media type for RFC2833 DTMF defaults to payload type 101. This is the recommended payload value that should be used for the highest degree of "telephone-event" RFC2833 DTMF interoperability. However, the application can change this value if required.

The SetRingbackType function allows the VOIP application to control the generation of the outgoing call ring back tone. The media engine supports the ability to sound the outgoing call ring back tone immediately after the transmission of the first INVITE request for the call or not until the reception of a "180 Ringing" SIP message. By default, the media engine will sound the ring back tone for an outgoing call immediately after the first INVITE request is transmitted.

The SetSilenceDecay procedure allows the application software to specify the amount of time that audio data will continue to stream to the far end of a call after the transmit audio energy level has transition below the "noise" threshold. This value is specified in milliseconds.

The SetSipLogServer API procedure can be called to specify the network location of a SIP log server. Using a SIP log server will give you the ability to view transmitted and received SIP protocol messages as they are processed in real time by the VOIP Media Engine.

This capability is generally used during system debug cycles but can be used for whatever purpose your application requires. A nice feature of real time SIP message logging to a server is the ability to see your SIP transactions in real time. You no longer have to stop your VOIP application to view its log files. The SIP log server capability can be used at the same time as the built-in static SIP log capability of the VOIP Media Engine. For details associated with the static SIP log capability, please refer to the LogSipMessages and the pSipLogFileName members of the VoipMediaEngine..::.START_SIP_TELEPHONY_PARAMS class.

Application software can call this procedure as many times as required in order to configure more that one remote SIP log server.

The SetSpeechRecognitionCallback API procedure is used to register a callback procedure with the telephony engine for the purpose of accessing the locally recorded audio stream. The primary application is for speech recognition but the sampled audio data passed to the application can be used for whatever your requirements dictate.

The SetSpeexCodecParameters API procedure is used to set optional speex codec settings for each phone line. The VOIP Media Engine supports both 8kHz narrow band and 16kHz wide band speex encoding and decoding. All speex encoder/decoder modes are supported in addition to full support for the encoder complexity.

Your VOIP application can use both narrow band and wide band speex codecs at the same time (in addition to the other supported codecs) when initiating or receiving a call.

The SetUserAgentInfo API procedure can be used by application software to modify the default SIP "User-Agent:" header that gets transmitted with every SIP message. The user agent header that is present in transmitted SIP messages consists of three parts of information - a product name, a version string and a user defined comment.

The SetWanIpAddress function allows an application to specify a wide area network address (WAN) that will be used when communicating with other devices. Depending on your network infrastructure, this API procedure may have to be called by an application if the application resides on a private network and is behind one or more NAT routers and you intend to allow calls to be made to the global internet.

If your application has knowledge about its network infrastructure (NAT router placement and subnet configurations) this API procedure can be called prior to placing a phone call to ensure that the far end of the call will be able to communicate back to your application. If you are also deploying a LanScape proxy/registrar with your voice solution, you do not need to call this procedure.

If your application changes the Wan IP address of the media engine, your application will also receive the SipWanIpAddressChange event.

The SipTelephonyEnable function is used after an instance of the telephony engine is created and after all configuration API procedures have been executed. Calling SipTelephonyEnable allows the telephony engine to accept incoming SIP traffic. It also allows you to make out bound calls. You must call this API procedure in order to initiate or receive voice over IP phone calls.

The StartDtmfTone API procedure is used to initiate the generation (transmission) and local playback of DTMF signals. This API procedure controls both in-band and RFC2833 DTMF signal generation. To stop the playing of a DTMF signal, see the StopDtmfTone(Int32, VoipMediaEngine..::.DTMF_TONE, Boolean) API procedure.

The StartSipTelephony function allows you to start an instance of the telephony engine. Prior to calling this API procedure, you are required to call the InitializeMediaEngine(String, UInt32) API procedure to initialize the API. You must call the StartSipTelephony procedure to instantiate a telephony engine before attempting to use any of the other API procedures that perform telephony operations.

The StopDtmfTone API procedure is used to terminate a currently playing DTMF tone. To start a DTMF tone, see the StartDtmfTone(Int32, UInt32, VoipMediaEngine..::.DTMF_TONE, UInt32, Boolean, Boolean, Boolean) API procedure.

The StopSipTelephony function allows you to terminate all operations of the telephony engine. If any calls are active, they are properly terminated before the telephony engine performs its shut down. Once this procedure is called, no other telephony operations are possible using the media engine instance.

The TerminateCall procedure is called by application software to terminate (hang up) an active phone call.

The TransferLine procedure is used to transfer an active call to another destination location. It is similar in functionality to the TransferLineUri(String, Boolean, Int32) API procedure.

The call to be transferred can also be on hold prior to the transfer operation. Transfer operations are supported for the following scenarios:

Direct SIP to SIP transfers
Indirect SIP to SIP transfers via a SIP proxy
Direct SIP to PSTN transfers via a PSTN Gateway

Call transfers share similar characteristics with placing outgoing phone calls. For additional information regarding the UserNameOrPhoneNumber and DestinationAddress parameters, please see the MakeCall(String, String, UInt32, Int32, Boolean, UInt32) API procedure.

The TransferLineUri API procedure allows an application to transfer a currently active phone call to a new location as specified by a SIP URI. It is similar in functionality to the TransferLine(String, String, Int32, Int32) API procedure.

The TriggerRegistration procedure allows your telephony application to signal to the media engine that a registration cycle should be conducted immediately. Normally the media engine will handle all details associated with keeping your application properly registered with a registrar server and you will never need to call this procedure.

The UnInitializeInBandDtmfDecoder API procedure is used to uninitialize an in-band DTMF decoder for the specified phone line.

The UnInitializeMediaEngine function allows you to uninitialize the telephony engine API interface. You must call this function after your application is finished using the telephony API. Generally this API procedure is called just before your application terminates.

The UnInitializeRfc2833DtmfDecoder API procedure is used to terminate RFC2833 DTMF decoding capability on the specified phone line.

The UseBranchInViaHeader API procedure can be called by application software to enable or disable the use of the "branch" parameter in the top most Via header that is contained in media engine transmitted SIP messages.

When the media engine sends SIP protocol messages to other applications or devices, by default it will place the branch parameter in the outgoing SIP message.

The SIP branch parameter is used as a transaction identifier. Responses relating to a particular SIP request can be correlated to the original request because they will contain this same branch transaction identifier. SIP Branch parameters also allow proxies to match responses to forked requests.

The media engine adds the appropriate branch parameter to transmitted SIP messages by default. You should only call this API procedure if you absolutely know what you are doing and you want to override the default behavior.

The UseRportInViaHeader API procedure can be called by application software to enable or disable the use of the "rport" parameter in the top most Via header that is contained in media engine SIP messages.

When the media engine sends SIP protocol messages to other applications or devices, placing this parameter in the via header allows the far end server to send responses back to where the SIP message originated from regardless of network address translation or port translation issues. This special function exists in an effort to overcome connectivity issued related to network address translation and port translation used in routers and firewalls.

The return value that servers assign to the rport parameter is also used by the media engine to detect if port translation is being performed. If you disable the use of the rport parameter, automatic NAT detection capabilities of the media engine will not function.

When incoming request authentication is enabled, the media engine will send the SipIncomingAuthentication event to your application whenever a far end application or device responds to our challenge with authentication response data.

Along with the event, your application can access a VoipMediaEngine..::.CHALLENGE_AUTHENTICATION class instance which contains data specific to the challenge response the far end sent. If the Operation member of the VoipMediaEngine..::.CHALLENGE_AUTHENTICATION class is set to the value AUTHENTICATE_VERIFY_CREDENTIALS, then the challenge handle member of the VoipMediaEngine..::.CHALLENGE_AUTHENTICATION class is available to your application. Your application can use this handle to verify the challenge response by calling this API procedure.