LanScape
Version Information - LanScape VOIP Media Engine™
“Allow your customers to do what they do best, communicate.” ™
VOIP
Media Engine - Release Notes1
(See
end of document for footnote information)
Version History:
v6.0.0.2
1)
Fixed an internal access violation on multi-core host machines. Depending on
execution timing, internal “audio de-bounce” logic handling may attempt to
delete a critical section object that had not been initialized.
v6.0.0.1
1)
Updates and corrections to the Software Developer's Reference and to the .NET
class reference.
2)
This version of the VOIP Media Engine contains an update that will allow it to
gracefully process 401 and/or 407 REGISTER request authentication challenges
that do not contain a “Call-Id:” SIP header in the challenge response.
This change is not a bug fix but an enhancement that will allow the media engine
to work with ill-behaving SIP registrars that do not place a Call-Id SIP header
in the authentication challenge responses.
v6.0.0.0
1)
Updates and corrections to the Software Developer's Reference.
2)
VOIP Media Engine versions v5.12.8.2 through v5.12.8.14 have not released to
the general public. These product versions were released to specific customers
as “engineering releases”. This latest version of the media engine incorporates
all changes, enhancements and bug fixes for the above specified versions.
3)
Final 2008 updates associated with allowing the media engine to fully scale on
multi-core host machines. Internal threading and memory allocation changes
implemented will allow the media engine to scale in a more linear fashion
relative to previous versions of the product. As higher density host machines
become available, LanScape will continue to improve on the multi-processor
performance and scalability of the media engine.
4)
Added a new wave file API procedure SetLoopRead().
The SetLoopRead() API procedure was added to the media
engine's wave file support. It allows continuous loop reading of sample block
data from wave files. The capability is useful for streaming wave file sample
block data to phone line transmit IVR channels in addition to other uses.
5)
Removed possible access violation in internal digital mixer subsystem.
The media engine incorporates digital mixing
functionality. This version of the media engine removes a possible NULL pointer
assignment that could cause an application access violation.
6)
Removed possible application crash when using Tx IVR outputs and when handling random incoming G729 and G711 calls.
Depending on the timing of how the application closed Tx IVR channels for phone lines and depending on the timing of how the media engine receives G729 and G711 based incoming calls, there existed a possibility that a new incoming G729 call may use the old G711 codec from a previous call on the same phone line. This situation would result in an access violation and application crash. This issue has been fixed.
7)
Added new API procedure GetRtpTransceiverStatistics().
The API procedure GetRtpTransceiverStatistics() was added
to the media engine to give a VOIP application a quick (low CPU overhead)
method of determining RTP transceiver activity. With this API procedure,
applications can determine total number of transmitted and received RTP media
packets in addition to RTP packet error counters. On such use for this API
procedure is to periodically read received RTP packet counters to determine if
a media session timeout has occurred.
8)
Parameter "PlaybackLocally" ignored when calling API procedure StartDtmfTone().
When commanding DTMF tone generation, the "PlaybackLocally" parameter was being ignored. This caused DTMF tones to always be played on the host's local multimedia hardware (if multimedia hardware support has been enabled). This bug has now been fixed.
9)
Added new API procedure SetUserAgentInfo().
The SetUserAgentInfo() API procedure was added to the
media engine to allow application software the ability to specify the
information that gets transmitted via the "User-Agent:" SIP header
value.
10)
Removed a possible application crash when terminating calls on phone lines that use iLBC 30Ms frame sizes.
Under certain situations and system loading, an access
violation could be experienced if an iLBC 30Ms frame size call is terminated
and the media engine is still in the process of transmitting RTP media data for
the call. This timing issue could cause an application crash in the form of an
access violation because an internal "block time converter" required
by the RTP transmit logic is no longer available. This issue has been fixed.
11)
Updated the media engine to better handle WWW and Proxy authentication challenges.
This version of the VOIP Media Engine has been updated to handle case differences in the "authentication type" Digest when being challenged by far end SIP devices and/or servers. Now when a far end SIP device or server challenges the media engine, any case is acceptable regarding the authentication type requested.
12)
Sample application can now be built using Visual Studio
2008.
13)
Trial license product images now allows up to 12 instances of the VOIP Media
Engine to run at the same time. Each instance of the media engine can support
up to 64 concurrent phone lines.
v5.12.8.14 (Final v5 product image)
1)
Updates and corrections to the Software Developer's Reference.
2)
Improve media engine sdp media attribute parsing.
Added additional tests to sdp media attribute parsing code
to remove possible access violations when parsing non conforming media
attributes.
3)
Added support for non existing media attributes in SDP for received INVITE
requests and 2xx responses.
The media engine now supports SIP devices that do not add "a=rtpmap" SDP media descriptors when initiating or receiving calls. Prior to this version, the media engine could not handle missing media descriptors for negotiated codec types. This version resolves this issue. In particular, the media engine is now able to interact with the "Sip Communicator" user agent (http://sip-communicator.org).
v5.12.8.13
1)
Updates and corrections to the Software Developer's Reference.
2)
Removed possible receive IVR access violation on multi-core hosts.
When terminating the media engine with one or more calls
that are active and while the VOIP application is receiving receive IVR phone
line streaming audio data, there was a possibility of generating an access violation
on multi-core host machines. This issue has been fixed.
3)
Allowed phone line receive volume setting to be applied to recorded and vu
meter audio levels.
Now when applications set the phone line receive audio
level using the SetPhoneLineVolume() API procedure, the receive audio levels
for recorded audio and received VU meter audio are also set. Prior versions of
the media engine did not alter the received recorded audio level or the
received vu meter level.
4)
REGISTER authentication challenge updates for improved SIP interoperability.
This version of the media engine contains updates that will allow for improved interoperability when registering with SIP registrar servers and other REGISTER endpoints.
This change directly affects the ability of the media engine to register with Sipfoundry's sipX v3.10.2 and higher PBX server platforms running on Linux.
When REGISTER cycles are challenged by the registrar server, the media engine will retry the REGISTER request with the computed required authentication credentials. The secondary REGISTER that is sent to the REGISTER server will maintain the same "From:" header tag value as the original REGISTER request. This will allow the REGISTER server to accept the request.
v5.12.8.12
1)
Updates and corrections to the Software Developer's Reference.
2)
The VOIP Media Engine may ignore new incoming calls having the same call ID as
a previous incoming call that was ignored or aborted.
If a previous incoming call was ignored using the
SipIncomingCallInitialized immediate event or aborted using the
AbortIncomingCall() API procedure, the media engine would ignore subsequent
incoming calls that have the same call ID. This issue has been fixed.
3)
Call hold request that receives a "408 Request Timeout" response may
terminate the call.
If the media engine performed a call hold request of a call and the far end or SIP proxy returned a "408 Request Timeout" response, the media engine could terminate the call instead of simply allowing the call hold re-INVITE to time out. This issue has been fixed.
v5.12.8.11
1)
Internal call history update for ignored incoming calls.
The media engine internally maintains a short term call history in order to process incoming SIP messages properly. Under some deployments, it was reported that if the user's VOIP application terminated or ignored incoming SIP calls via the media engine, the far end device may immediately retry the call using the same call ID but with a different "From:" header tag. The internal call history was basing its logic only on call ID and would therefore not map new calls for a previously retried call prior to having the internal call history updated. This particular code change allows for improved SIP interoperability with the customers IP based PBX.
v5.12.8.10
1)
Updates and corrections to the Software Developer's Reference.
2)
Re-invite record route header parse bug.
Fixed a bug associated with detecting the route host from Record-Route headers that are parsed from INVITE "200 OK" responses. Without this fix, re-invites may be sent to the wrong destination IP address when using record route headers.
3)
Conference session ID bug fix.
The media engine contained a bug that would allow it to logically wire phone
lines into conference sessions that did not have the same conference session
IDs as set by the SetConferenceGroupIds() API procedure. This issue has been
fixed.
4)
UDP receive and transmit buffer size modifications to allow executing under Linux operating systems using Wine.
Updated how the media engine applies UDP receive and
transmit buffer sizes so that the media engine can execute under Linux using
Wine v1.1.3 and higher. Wine is the Windows emulation layer. For more
information, see http://www.winehq.org.
v5.12.8.9
1)
Updates and corrections to the Software Developer's Reference.
2)
Fixed Access Violation in RTP transmitter logic.
Fixed an uninitialized pointer in RTP transmitter logic that could cause an
access violation if internal DTMF is disabled but supported (enabled) by
license files and when the app filters transmitted RTP packets.
v5.12.8.8
1)
Updates and corrections to the Software Developer's Reference.
2)
This version of the VOIP Media Engine contains software updates that address choppy/broken multimedia audio playback issues.
Depending on the underlying multimedia hardware and drivers installed in Windows Vista hosts machines, it was possible that the media engine would play back telephony sounds and streaming phone line audio in a discontinuous manner (i.e. choppy or broken audio playback). This issue was also detected on some Windows XP Pro machines as well.
This latest version has the ability to handle non periodic sample block multimedia playback and handle non "real time" behavior of multimedia audio hardware and drivers. It contains additional logic to time scale audio playback streams to remove discontinuous audio playback.
Also addressed in this release is the ability to overcome
issues associated with multimedia hardware record and playback rates that are
not the same for the same sampling frequency.
v5.12.8.7
1)
Updates and corrections to the Software Developer's Reference.
2)
Removed possible access violation when transmitting final ACK responses for outgoing SIP INVITE requests.
This version of the media engine removes a possible access
violation that was associated with transmitting final ACK responses to outgoing
INVITE requests. It was possible for the media engine to improperly compute an
internal address location if INVITE responses in the range of 400 to 699
arrived after the media engine decided that the call leg had already been
properly terminated. If the media engine received additional “late” INVITE
responses for a past call, an access violation could occur. This issue has been
fixed.
v5.12.8.6
1)
Updates and corrections to the Software Developer's Reference.
2)
Fixed a bug in Ms (millisecond) accurate absolute SIP log
time stamps.
A bug has been fixed that was associated with Ms accurate absolute SIP log time
stamps. It was possible, due to a rounding error that absolute time stamps
could have a value of 0 to 1000 Ms instead of 0 to 999 Ms. This issue has been
fixed.
3)
Multi-core conferencing deadlock issue fixed.
This version of the media engine includes a fix that will
remove a possible deadlock situation when running the media engine on
multi-core host hardware platforms and when quickly transitioning phone line
"into" and "out of" conference mode.
4)
Multi-core conferencing optimizations.
The media engine now includes logic optimizations that
will allow individual phone lines to transition to and from conference mode
much faster and with less CPU overhead. This will improve overall call handling
throughput.
v5.12.8.5
1)
Updates and corrections to the Software Developer's Reference.
2)
Improved the time stamp resolution of individual phone
line SIP logging to files.
The media engine has the ability to log SIP messages to log files on a per
phone line basis. Log file time stamp resolution now has +/-1 Ms logging accuracy
and SIP logs now contain absolute time stamps in addition to relative time
stamps.
3)
Changed the way the media engine's CSeq SIP header value is computed during INVITE requests in order to improve Asterisk SIP interoperability.
This version of the media engine contains an update that
ensures the uniqueness of CSeq header values in all transmitted INVITE
requests. Doing so will ensure that Asterisk servers will not ignore secondary
INVITE requests that are very quickly received due to "407 Proxy Authentication
Required" challenges.
v5.12.8.4
1)
Updates and corrections to the Software Developer's Reference.
2)
Added the ability to mute received and transmitted phone line audio on a per phone line basis.
Added the ability to mute the playback of received phone line audio on a per phone line basis. By default, all received phone line audio is played back to local multimedia hardware if multimedia hardware support has been enabled in the media engine. The new SetMuteReceivedPhoneLineAudio () API procedure now allows application software to selectively mute the playback of phone line received audio. Application software can also call the GetMuteReceivedPhoneLineAudio () API procedure to query the state of phone line received audio playback.
Phone line transmitted audio can also be muted on a per phone line basis. The SetMuteTransmitPhoneLineAudio() and GetMuteTransmitPhoneLineAudio() API procedures have been added to support this capability.
Muting transmit or received audio does not alter the state
of SIP phone calls and does not generate SIP requests or responses.
3)
Fixed access violation when conferencing is turned OFF.
Under certain execution situations, an unhandled access violation could be
thrown by the operating system when call conferencing is turned OFF. This bug
has been fixed.
4)
Added new startup error return value:
SipRtpTxMixerThreadStartError.
Added the new media engine startup error return value
SipRtpTxMixerThreadStartError. This new return value was added so that phone
line transmit mixer start errors would be reported accurately and not fall
under a previous “catch-all” error code return value.
5)
Fixed incoming call RTP port assignment errors when executing on multi core CPU platforms.
This version of the media engine contains a bug fix that is associated with RTP port assignments for incoming calls.
Under certain situation when processing a large number of
incoming calls and when running the media engine on a multi core host (i.e. a
multi-processor host), RTP port assignment logic could assign the same RTP port
to two different incoming concurrent calls. This would result in one of the
calls generating the SipSocketBindError event during internal RTP call setup
which would make one of the calls fail. This bug has been fixed.
6)
Faster call setup and initializations.
This version of the media engine incorporates RTP transceiver changes that
greatly reduce call setup times. With these current changes, it is possible
that 2000 milliseconds (2 seconds) can be removed from each call setup. This
greatly improves call setup times for high line density deployments.
7)
VOIP Media Engine now passes release 1 and release 2 of the PROTOS SIP Test Suite.
This version of the media engine has been updated to pass
Release 1 and 2 of the PROTOS test suite.
8)
Fixed access violation when local audio is ON and conferencing is OFF.
This version of the media engine fixes an access violation
that may occur when local multimedia audio is enabled and multi-line
conferencing capability is turned OFF.
v5.12.8.3
1)
Updates and corrections to the Software Developer's Reference.
2)
The following two registration global events have been
renamed to improve naming consistency:
Old Event Names:
SipRegistrationIntervalError
SipRegistrationTimeOut
New Event Names:
SipRegisterIntervalError
SipRegisterTimeOut
3)
The following global event notifications have been added to the media engine to
allow VOIP applications to monitor registration cycles when the media engine
un-registers with SIP registrars:
SipUnRegisterTrying
SipUnRegisterSuccess
SipUnRegisterTimeOut
SipUnRegisterErrorBadCredentials
SipUnRegisterError
SipUnRegisterNetworkError
SipUnRegisterAuthorizationError
4)
This version of the media engine supports the IsUserNameRegistered() API procedure.
This new API procedure allows VOIP applications to query the registration
status of phone line user names (extensions) as they are registered with an
optionally configured SIP registrar server.
5)
Removed possible access violation when calling GetIncomingCallInfo() API
procedure.
If an incoming call was answered and then terminated by the far end very
quickly, the application could call the GetIncomingCallInfo() API procedure and
possibly generate an access violation. This issue has been resolved.
6)
Removed possible access violation when calling GetActiveCallInfo() API
procedure.
If an incoming call was answered and then terminated by the far end very
quickly, the application could call the GetActiveCallInfo() API procedure and
possibly generate an access violation. This issue has been resolved.
7)
Removed possible deadlock situation in RTP receivers when under heavy load.
If the media engine is very heavily loaded and incoming calls are received and
then quickly terminated (terminated in 1 second or less), and if the media
engine runs out of phone lines for the total number of INVITE requests pending,
there was a possibility of deadlocking the RTP receiver for a phone line. This
issue has been fixed.
8)
Incoming subscription bug that caused memory to be reclaimed twice.
If the VOIP Media Engine received a SIP SUBSCRIBE request and the VOIP
application dose not want to accept the incoming request, the media engine
would process the SUBSCRIBE request as normal. However, an internal data
structure was being freed twice. This bug has been removed in order to improve
operating system stability.
9)
200 OK SIP responses to SUBSCRIBE requests did not contain a "To:"
header tag.
If the media engine has been instructed to accept a SUBSCRIBE request by the
VOIP application, the “200 OK” SIP response that gets transmitted did not
contain a Tag parameter in the “To:” header field. This bug has been fixed.
10)
Renamed the GetNumberOfActiveCalls() API procedure to
GetNumberOfCallsInProgress()
The GetNumberOfActiveCalls() API procedure has been renamed to
GetNumberOfCallsInProgress(). This has been done to better describe true
nature of the API procedure.
11)
Updated the media engine’s ability to detect RTP media conflicts using the
SipReceivedRtpMediaConflict event
The media engine has the ability to detect received RTP media from different IP
addresses than what is negotiated in the SIP protocol. The media engine has
been updated to support both session and media level IP detection from request
and response SDP.
12)
Phone call conference deadlock issue.
Fixed a deadlock issue that was associated with placing phone lines into
conference mode. It was possible for the media engine to experience a deadlock
situation under the following scenario:
1)
An application worker thread detects an incoming phone call and goes off hook to answer the call.
2)
The application then calls the ConferenceLine() API procedure to place the phone line into a conference session during the processing of the SipInCall state.
3)
At the same time the internal ConferenceLine() API logic is executing, the far end of the call terminates the call. If the execution of the internal conferencing logic and the call terminate logic are "just right", one of two situations could occur. Either internal call thread logic would start to deadlock or the application thread that called the ConferenceLine() API procedure could deadlock. The internal condition that caused the deadlock to occur was associated with two sections of internal logic waiting on the same completion event.
This dead lock issue has now been resolved.
13)
Conference events more closely mirror the behavior of call hold events when
terminating calls.
Prior versions of the media engine would send to the application the
SipInConferenceOff and SipInCall events when a call is terminated and the phone
line was in a conference session. For example, the following events would be
sent to an application for a phone line that is initially “in a call” and has
been added to a conference session and has been terminated either by hanging up
the call or honoring a received BYE request:
SipInCall
SipInConferenceOn
SipInConference
SipByeReceived
SipSendByeAck
SipInConferenceOff
SipInCall
SipCallComplete
SipOnHook
Some developers found that receiving a second SipInCall event as the result of transitioning the call out of conference mode was too confusing.
In order for conferencing event to be more symmetrical relative to Hold/UnHold events, the final SipInConferenceOff and SipInCall events have been removed when a phone line experiences the above scenario. Now, when a call terminates that is in an active conference session, the following events will be sent to the application:
SipInCall
SipInConferenceOn
SipInConference
SipByeReceived
SipSendByeAck
SipCallComplete
SipOnHook
This makes conferencing event behavior identical to call hold event behavior.
14)
Added a new API that allows applications to filter specific events from remote
event logs.
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.
15)
Resolved media engine indefinitely hanging upon termination when lines are in
“Busy Out” state.
If any phone line is placed into the busy out state and the media engine is
terminated, the media engine will not shut down properly and appear to hang
forever. This issue has been fixed.
16)
Added the SetCallCancelTimeout() API procedure.
The SetCallCancelTimeout() API procedure has been added to allow applications
to control how long the media engine will wait for outgoing call CANCEL
responses from the far end of the call. Prior to this release, the media engine
used a hard coded timeout value.
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 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 timeout as set by the API procedure, the responses will be ignored.
17)
Fixed SIP log time stamp error.
The relative time stamps for the first transmitted and received SIP log entries
were incorrect. This issue has been fixed.
18)
Added absolute time stamp to all SIP log output.
All SIP log generated data now includes absolute time stamp information accurate to within +/-1Ms of when the Sip packets were received or transmitted. This will help when debugging SIP inter-op related issues.
v5.12.8.2
1)
Various updated and correction to the Software Developer's reference.
2)
DTMF generator and decoder updates.
Enhanced the DTMF decoder support in the media engine in an effort to allow
customers to manipulate decoder characteristics. This release also includes
support for the v6 media engine fully integrated in-band and RFC2833 DTMF
support soon to be released. The primary benefits resulting from these changes
are that customers will not have to request special DTMF decoder tuning tables
from LanScape support. The other primary advantage is using the fully
integrated DTMF support greatly simplifies VOIP application development.
The following new API procedures have been added:
Stand-alone in-band DTMF detection:
BOOL VOIP_API DtmfDecoderSetSignalThreshold(HDTMFDECODER hDtmfDecoder, double DtmfDecoderSignalThresholdDb);
BOOL VOIP_API DtmfDecoderGetSignalThreshold(HDTMFDECODER hDtmfDecoder, double *pDtmfDetectSignalThresholdDb);
BOOL VOIP_API DtmfDecoderSetTwist(HDTMFDECODER hDtmfDecoder, double ForwardTwistDb, double ReverseTwistDb);
BOOL VOIP_API DtmfDecoderGetTwist(HDTMFDECODER hDtmfDecoder, double *pForwardTwistDb, double *pReverseTwistDb);
void VOIP_API DtmfDecoderSetMinimumDigitOnTime(HDTMFDECODER hDtmfDecoder, DWORD MinimumDigitOnTimeMs);
DWORD VOIP_API DtmfDecoderGetMinimumDigitOnTime(HDTMFDECODER hDtmfDecoder);
Internal (fully integrated) in-band and RFC2833 DTMF detection:
TELEPHONY_RETURN_VALUE VOIP_API SetInBandDtmfSignalThreshold(
SIPHANDLE hStateMachine,
int PhoneLine,
double DtmfDecoderSignalThresholdDb
);
TELEPHONY_RETURN_VALUE VOIP_API GetInBandDtmfSignalThreshold(
SIPHANDLE hStateMachine,
int PhoneLine,
double *pDtmfDetectSignalThresholdDb
);
TELEPHONY_RETURN_VALUE VOIP_API SetInBandDtmfTwist(
SIPHANDLE hStateMachine,
int PhoneLine,
double ForwardTwistDb,
double ReverseTwistDb
);
TELEPHONY_RETURN_VALUE VOIP_API GetInBandDtmfTwist(
SIPHANDLE hStateMachine,
int PhoneLine,
double *pForwardTwistDb,
double *pReverseTwistDb
);
TELEPHONY_RETURN_VALUE VOIP_API SetInBandMinimumDigitOnTime(
SIPHANDLE hStateMachine,
int PhoneLine,
DWORD MinimumDigitOnTimeMs
);
TELEPHONY_RETURN_VALUE VOIP_API GetInBandMinimumDigitOnTime(
SIPHANDLE hStateMachine,
int PhoneLine,
DWORD *pMinimumDigitOnTimeMs
);
3)
Added the following three new members to the DTMF_DETECT_DATA and
DTMF_EVENT_DATA structures. These values allow the VOIP application to obtain
detected in-band DTMF frequency power values in addition to average noise
power.
double Freq1MagDb;
double Freq2MagDb;
double AverageNoiseMagDb;
v5.12.8.1
1)
Some upcoming changes associated with the v6 media engine software are present
in the SipTelephoneApi.h API header file. Make sure your VOIP application
builds do not define the SUPPORT_INTEGRATED_DTMF macro when building your VOIP
solution.
2)
Various updates and improvements to the Software
Developer's Reference.
3)
Added new API proc LogPhoneLineSipMessages() to support
SIP logs for individual phone lines.
4)
Added the media engine return value SipConferenceNotEnabled value. This value
gets returned by the ConferenceLine() and SetConferenceGroupIds() API
procedures when the API procedures are called and conferencing is not enabled.
5)
The following stand alone DTMF generator API procedures have been renamed in
order to remove API name clashing with upcoming future media engine
capabilities. We fully regret this inconvenience. The new API procedure name
changes are as follows:
Old Names/prototypes:
BOOL VOIP_API StartDtmfTone(HDTMFGENERATOR hDtmfGenerator, DTMF_TONE DtmfTone, DWORD DurationMs);
void VOIP_API WaitForToneCompletion(HDTMFGENERATOR hDtmfGenerator);
BOOL VOIP_API StopDtmfTone(HDTMFGENERATOR hDtmfGenerator);
BOOL VOIP_API SetDtmfAmplitude(HDTMFGENERATOR hDtmfGenerator, int Amplitude);
New Names/prototype:
BOOL VOIP_API StartDtmfGeneratorTone(HDTMFGENERATOR hDtmfGenerator, DTMF_TONE DtmfTone, DWORD DurationMs);
void VOIP_API WaitForDtmfGeneratorToneCompletion(HDTMFGENERATOR hDtmfGenerator);
BOOL VOIP_API StopDtmfGeneratorTone(HDTMFGENERATOR hDtmfGenerator);
BOOL VOIP_API SetDtmfGeneratorAmplitude(HDTMFGENERATOR hDtmfGenerator, int Amplitude);
6)
API procedures that are associated with outgoing call sounds have been renamed
in order to remove API name clashing with upcoming future media engine
capabilities and to improve naming consistency. We fully regret this
inconvenience. The new API procedure name changes are as follows:
Old Names/prototypes:
TELEPHONY_RETURN_VALUE VOIP_API EnableDtmfDigits(SIPHANDLE hStateMachine, BOOL EnableState);
TELEPHONY_RETURN_VALUE VOIP_API EnableBusySignal(SIPHANDLE hStateMachine, BOOL EnableState);
TELEPHONY_RETURN_VALUE VOIP_API EnableErrorSignal(SIPHANDLE hStateMachine, BOOL EnableState);
New Names/prototypes:
TELEPHONY_RETURN_VALUE VOIP_API EnableOutgoingDtmfDigits(SIPHANDLE hStateMachine, BOOL EnableState);
TELEPHONY_RETURN_VALUE VOIP_API EnableOutgoingBusySignal(SIPHANDLE hStateMachine, BOOL EnableState);
TELEPHONY_RETURN_VALUE VOIP_API EnableOutgoingErrorSignal(SIPHANDLE hStateMachine, BOOL EnableState);
7)
Jitter compensation RTP packet bug:
If jitter compensation for a phone line is enabled, it was possible that not
all received RTP media packets would be sent to an application's receive IVR
callback procedure while the jitter comp algorithm is engaged. The number of
missed packets is equal to the specified API jitter comp time in milliseconds
divided by the RTP payload time per packet.
Also if phone line loop back echo is enabled, it was also possible that not all RTP packets would be looped back for retransmission out the phone line.
This issue has now been fixed. Now regardless of the
internal state of phone line receive jitter compensation, all RTP packets will
be forwarded to the application's receive IVR callback procedure and all RTP
packets will be echoed out the phone line if required.
8)
Multiple line registrations using 3CX PBX.
A bug was fixed in the media engine that was associated
with performing multiple line registrations to the 3CX PBX. The media engine
would experience a parse error when receiving proxy authentication challenges
from the 3CX PBX. This bug would not allow multiple lines of the media engine
to be registered at the same time with the PBX. This issue has been fixed.
9)
Support “annexb” SDP format tag for G729 based codecs:
The media engine now supports the SDP format descriptor
“annexb=yes” and “annexb=no” that is used when initiating or receiving VOIP
calls. This helps to improve interoperability with SIP/RTP/VOIP equipment from
other vendors and completely removes G729/G729A and G729B codec clashing when
call endpoints do not default to using the same G729 codec type.
10)
Allow dynamically changing the SIP "Display name" for phone lines:
This version of the media engine supports a new API
procedure called SetPhoneDisplayName(). Application software can use this
procedure to dynamically change the display name for any phone line prior to
making outgoing calls. Note that prior to this release, the media engine
already allowed dynamically changing the phone line “user name”/”extension”
using the SetPhoneName() API procedure.
11)
Playback delay build up when using Tx IVR outputs.
When playing back sample block data to phone line transmit IVR outputs, the actual time to play all application supplied samples would be proportionately longer (approximately 0.2% longer) than the total time of the sample data.
The longer the continuous playback of sample data to Tx IVR outputs, the more accumulated playback delay would be introduced. This did not affect the sonic quality of the Tx IVR data but caused application developers to worry that their Tx IVR playback data would somehow be altered in pitch or frequency content.
This version of the media engine incorporates changes to
internal digital mixers that will completely remove all previously noticed
playback delay build up when using any of the Tx IVR outputs.
12)
The Sequence and TimeStamp values in raw received RTP headers are no longer
automatically converted from network byte order (big endian) to native (little
endian).
13)
Phone line internal transmit mixer fix:
If a phone call is initiated and then quickly terminated
immediately after entering in “in call” state, it was possible for the phone
line’s internal transmit mixer logic to not enter the blocking state. Even
though no voice data would be mixed, the internal thread logic could still
execute every 20Ms even though the previous phone call was terminated. This bug
simply caused additional unnecessary loading on the host CPU and no other side
effect. This bug has now been fixed thus improving overall VOIP application
performance and CPU utilization.
14)
Added the parameter pTotalNumSampleBytes to the OpenWaveFile() API proc so app
code can determine how many total sample bytes are in the wave file.
TELEPHONY_RETURN_VALUE VOIP_API OpenWaveFile(
SIPHANDLE hStateMachine,
char *pWaveFileName,
int BytesPerWaveBuffer,
HWAVEFILE *pWaveFileHandle,
int *pBytesPerSample,
DWORD *pTotalNumSampleBytes
);
15)
Opening Microsoft 8kHz 4 bit ADPCM wave files caused heap corruption:
If a VOIP application would try to open a Microsoft 8kHz 4
bit ADPCM wave file using the built in media engine wave file support, the
global heap could get corrupted. This issue has been fixed.
16)
Updated the media engine to allow "200 OK" responses to include
RFC2833 DTMF "telephone-event" format specifiers in support of DTMF
digits 0-16. Previous versions of the media engine had the
"telephone-event" format specifier in transmitted INVITE requests but
not in "200 OK" responses. The following SIP messages show what is
now generated by the media engine (see items in RED).
INVITE sip:333@ps SIP/2.0
Via: SIP/2.0/UDP 192.168.1.2:5066;rport;branch=z9hG4bK05b54c2b
From: "Test Phone" <sip:333@ps>;tag=5b4fe04;x-UaId=xxxxx-yyyy-zzzzzz
To: <sip:333@ps>
Contact: <sip:333@192.168.1.2:5066>;x-inst="VGVzdCBDYWxsIERhdGEgZnJvbSB0aGUgVlBob25lIGFwcC4="
Call-Id: 5a46dcac-7593-46e7-8076-94d27eae327a-00003bd0@192.168.1.2
CSeq: 11889747 INVITE
Max-Forwards: 70
Organization: 2456E5FD-DC94-417D-BDF7-55A654EFB9E5
Proxy-Authorization: Digest algorithm=md5,nonce="32db76a9f4b0836dcf462639562a7c07",opaque="92db7091bcf042e0d9572a6a5163f62b",realm="ps",response="676969f2456f751ae7c69cb10c34541f",uri="sip:333@ps",username="guest"
x-CustomHeader-Extension-333: "This is a modified transmitted SIP message."
x-PhoneLine: 0
Content-Length: 221
User-Agent: LanScape VOIP Media Engine/5.12.8.1 (www.LanScapeCorp.com)
Allow: INVITE, ACK, OPTIONS, BYE, CANCEL, SUBSCRIBE, NOTIFY
Content-Type: application/sdp
v=0
o=333 95745296 95745296 IN IP4 192.168.1.2
s=LanScape
c=IN IP4 192.168.1.2
t=0 0
m=audio 20006 RTP/AVP 0 101
a=rtpmap:0 PCMU/8000/1
a=rtpmap:101 telephone-event/8000/1
a=sendrecv
a=ptime:20
a=fmtp:101 0-16
SIP/2.0 200 OK
Via: SIP/2.0/UDP 192.168.1.2:5060;received=192.168.1.2;branch=z9hG4bKf733fcbce1f31aae7f5b20d85cce4947a.0
Via: SIP/2.0/UDP 192.168.1.2:5066;received=192.168.1.2;rport=5066;branch=z9hG4bK05b54c2b
Record-Route: <sip:192.168.1.2>
From: "Test Phone" <sip:333@ps>;tag=5b4fe04;x-UaId=xxxxx-yyyy-zzzzzz
To: <sip:333@ps>;tag=5b50dde
Call-Id: 5a46dcac-7593-46e7-8076-94d27eae327a-00003bd0@192.168.1.2
CSeq: 11889747 INVITE
Contact: <sip:333@192.168.1.2:5066>
Allow: INVITE, ACK, OPTIONS, BYE, CANCEL, SUBSCRIBE, NOTIFY
User-Agent: LanScape VOIP Media Engine/5.12.8.1 (www.LanScapeCorp.com)
x-CustomHeader-Extension-333: "This is a modified transmitted SIP message."
x-PhoneLine: 1
Content-Length: 230
Content-Type: application/sdp
v=0
o=LanScape 2147483647 2147483647 IN IP4 192.168.1.2
s=LanScape
c=IN IP4 192.168.1.2
t=0 0
m=audio 20000 RTP/AVP 0 101
a=rtpmap:0 PCMU/8000/1
a=rtpmap:101 telephone-event/8000/1
a=sendrecv
a=ptime:20
a=fmtp:101 0-16
v5.12.8.0
1)
This image contains a fix for applications receiving multiple
SipReceivedRtpMediaConflict events. Due to a coding error, applications were
receiving this event for each received RTP packet that was in violation of the
call’s negotiated SIP endpoint parameters. With this update, applications will
only receive a single SipReceivedRtpMediaConflict event during a call.
2)
Added support for multiple remote SIP and event log
servers. This way real time SIP and event information can be sent to more than
one SIP or event log server.
3)
Fixed a possible dead lock situation when hammering on the
subscription API. It was possible for the TriggerSubscription() API procedure
to take longer than normal to return if many subscription requests (greater
than 10) were triggered at the same time and simultaneously from different
threads.
4)
The Sequence and TimeStamp values in raw received RTP headers are now converted
from network byte order (big endian) to native (little endian). This helps the
app and minimizes confusion when viewing raw RTP payloads.
v5.12.0.0 through v5.12.7.x
Notes:
Product revisions in this range consisted of product enhancement, changes and
bug fixes in addition to customer requested custom development. All changes to
the product from revisions v5.12.0.1 through v5.12.7.X have been merged back
into the current main product branch and are now part of the base product.
Version history for these revisions will be lumped together. As of the final
v5.12.7.X product image, LanScape will begin to publish all standard product revision
changes with proper version descriptions as they occur in order to better
support developers and customers wishing to upgrade to newer product versions.
New Features and
Capabilities:
1)
Added new API procedure GetRtpTransceiverStatistics().
The API procedure GetRtpTransceiverStatistics() was added to the media engine
to give a VOIP application a quick (low CPU overhead) method of determining RTP
transceiver activity. With this API procedure, applications can determine total
number of transmitted and received RTP media packets in addition to RTP packet
error counters. On such use for this API procedure is to periodically read
received RTP packet counters to determine if a media session timeout has
occurred.
2)
Changed the way the media engine’s CSeq SIP header value is computed during
INVITE requests in order to improve Asterisk SIP interoperability.
This version of the media engine contains an update that ensures the uniqueness
of CSeq header values in all transmitted INVITE requests. Doing so will ensure
that Asterisk servers will not ignore secondary INVITE requests that are very
quickly received due to “407 Proxy Authentication Required” challenges.
3)
Allow the application to query registered user names (extensions).
This version of the media engine supports the IsUserNameRegistered() API
procedure. This new API procedure allows VOIP applications to query the
registration status of phone line user names (extensions) as they are
registered with an optionally configured SIP registrar server.
4)
Complete integrated support for both in-band and RFC2833 DTMF generation and
decoding.
This version of the VOIP Media Engine contains complete and fully integrated
support for both in-band and RFC2833 DTMF generation and decoding. VOIP
applications can chose to use no DTMF or any combination of in-band and/or
RFC2833 DTMF on a per phone line basis. All aspects of this powerful DTMF
behavior can be controlled via the API.
Using RFC2833 based DTMF in your VOIP applications will ensure the best possible DTMF interoperability and performance as compared to using in-band DTM techniques.
In application instanced that demand support for in-band DTMF detection and generation, the media engine allows the VOIP app huge control over in-band DTMF signaling characteristics. VOIP applications can specify and control DTMF signal thresholds, forward and reverse twist and specify minimum digit ON time for improved talk off and noise immunity.
With this new enhanced capability, supporting either
in-band or out-of-band RFC2833 DTMF generation and decoding in a VOIP
application is incredibly simple and "rock solid".
5)
Allow dynamically changing the SIP "Display name" for phone lines.
This version of the media engine supports a new API procedure called SetPhoneDisplayName(). Application software can use this procedure to dynamically change the display name for any phone line prior to making outgoing calls. Note that prior to this release, the media engine already allowed dynamically changing the phone line “user name”/”extension” using the SetPhoneName() API procedure.
6)
Internal threading changes.
This version of the VOIP Media Engine has been updated to incorporate an updated internal multi-threading model. Thread logic has been simplified and many critical sections and serialization paths have been removed.
What this means is that your VOIP applications will be
able to process many more VOIP calls per second as compared to previous
versions of the product using the same identical hardware platform.
7)
New Multi-session conference call capabilities.
The VOIP Media Engine™ now supports simple and complex multi-session call conferencing capabilities. In the simplest case, the media engine can be used in its default state to conference all lines into the same single default conference call group. In more complex conference call scenarios, the VOIP application has the ability to define whatever conferencing relationships exist between all phone lines. There are no limitations regarding the conferencing relationship between individual phone lines or between separate logical conference groups. In fact, separate logical conference groups may overlap if your application requires this capability.
The conferencing capability of the VOIP Media Engine™ centers around the concept of call conference IDs. Call Conference IDs are the same thing as conference session IDs. A conference session is simply a logical grouping of two or more phone lines that fully share media with one another - full duplex.
The conferencing relationships between individual phone
lines are completely controlled by your VOIP application by assigning logical
conference session IDs to phone lines. Phone lines that share similar call
conference IDs will be logically "wired together" internally inside
the media engine when the phone line is placed into the conference state using
the ConferenceLine API procedure. Conference session IDs are assigned to
individual phone lines using the SetConferenceGroupIds API procedure.
Conference IDs can be assigned to any phone line anytime as long as the phone
line is not already in a conference session.
8)
Allow multiple SIP log and event log servers to be configured.
Multiple remote SIP log and event log servers can now be configured.
If you need to send real time SIP log information to more than one remote SIP log server, application software can call the SetSipLogServer() API procedure any number of times to specify one or more SIP log servers.
If you need to send real time media engine event log
information to more than one remote event log server, application software can
call the SetEventLogServer() API procedure any number of times to specify one
or more event log servers. The media engine start-up parameters also support
configuring multiple event log servers.
9)
"Make Call" APIs now detect "line already in use" state
earlier.
This version of the media engine includes updates to all of the "make call" API procedures. These updates allow VOIP applications to “early detect” if another application thread is already in the process of making a call on the outgoing phone line. This helps to simplify application development and reduce unnecessary thread blocking for synchronous call operations.
10)
Improved call processing throughput - New faster call processing for server
applications.
This release of the media engine now supports faster call processing as compared to previous versions of the product. This new capability is focused at high line count VOIP server applications (greater than 128 lines) that need to process call as fast as possible.
What this means is this: As your application boots the media engine, the media engine will allocate all required phone line threads, events and memory resources at boot time instead of creating the needed resources “on demand” every time a call is started. When all call thread, memory and operating system resources are pre-allocated, calls are processed much faster.
11)
Improved network transmit capabilities.
This version of the VOIP Media Engine has improved network transmit capabilities that effect both SIP session and RTP media UDP transmissions. In summary, these changes allow the VOIP Media Engine to handle large call volumes more efficiently and large SUBSCRIBE/NOTIFY operations without having to report interim errors to the application.
The benefits of these changes are as follows:
SIP transactions:
When the host system is heavily loaded and the VOIP Media Engine is managing large call volumes (For example: 64 to 512 or greater concurrent lines active), SIP protocol packets that need to be sent will be retried automatically when the host system starts to run out of operating system internal network transmit buffers. Prior to these changes, the VOIP Media Engine would return error status or error events back to the VOIP application. This would be detected by the application as failed outgoing calls, failed subscribe or notify operations or possibly failed registration cycles. The primary advantage however is that incoming and outgoing call handling capability and robustness is greatly enhanced due to these network programming changes.
RTP media transmissions:
Similarly to the changes above that effect SIP
transmissions, RTP media transmissions benefit from the same internal changes.
What this means is that RTP jitter and delays will be reduced or completely
diminished as the result of heavy system loading when transmitting RTP media
payloads to the far end of the call.
12)
Improved startup and termination characteristics for high volume server
applications.
This release of the media engine has improved startup and termination behavior. The changes allow for quicker startup and termination when being used by high volume server applications that may experience incoming call hammering (due to large call volumes).
13)
Added new immediate event and structure to help resolve RTP NAT media issues.
The SipReceivedRtpMediaConflict immediate event has been added. The purpose of this event is to allow VOIP server applications to detect and instruct the media engine on how to handle a specific class of RTP NAT media issues.
If you are developing a server based VOIP application (PSTN gateway, IVR server, etc) using the media engine, this capability may be of interest to you. The media engine will send this event to application software any time it is detected that media is not coming from a call endpoint based on negotiated SIP media IP addresses and port values.
Application software can process this event and instruct the media engine on how media should be exchanged thus overriding negotiated SIP media setup for calls.
When application software receives this event, it also
gets the address of the new RECEIVED_RTP_MEDIA_CONFLICT structure. Application
software can then inspect this structure to obtain additional information
relating to the media conflict.
14)
Added support for call state recording.
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 following new API procedures have been added to support this capability:
SetCallStateRecording()
GetNumRecordedCallStates()
GetRecordedCallStates()
ClearRecordedCallStates()
15)
Added a new API that allows applications to filter specific events from remote
event logs.
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.
16)
Added additional members to the ACTIVE_CALL_INFO structure.
Added raw INVITE and 2xx response SIP messages to the ACTIVE_CALL_INFO structure. This gives application software additional information associated with call setup.
17)
Added new immediate event to allow application to assign phone line to incoming
calls.
The new SipIncomingCallAssignPhoneLine immediate event has been added to the media engine. Application software can process this event in order to force the media engine to assign the incoming call to a specific available phone line as determined by the application. Useful when developing conference call servers where conference session IDs are set up and fixed for each line. This event also allows application software to terminate the incoming call immediately similarly like the legacy SipIncomingCallInitialized event.
This new event type also defines the new ASSIGN_INCOMING_PHONE_LINE data structure. When application software processes this event, it will also gain access to this new call data structure.
18)
Removed restrictions on API procedures relative to when they can be called by
application software.
This version of the media engine has been updated to remove restrictions on API procedures relative to when they can be called by application software. This reduces the possibility of application dead locking. It also allows developers additional freedom when calling API procedures from directly within the media engine main event callback handler (thread).
19)
Added Call ID string to phone line call information structures.
In an effort to allow application programmers the ability
to better correlate SIP messages to specific phone lines, the SIP Call ID has
been added to the following call related structures: SIP_INCOMING_CALL_INFO,
SIP_OUTGOING_CALL_INFO and SIP_ACTIVE_CALL_INFO.
20)
Media Engine now supports negotiated G729/G729A RTP media larger than 20Ms.
The VOIP Media Engine now handles G729/G729A RTP media packets larger than 20Ms. The actual size of the G729/G729A media packets is now negotiated at SIP call setup time. The media engine will always default to using 20Ms G729 RTP block sizes when initiating outbound calls. If the destination endpoint changes the default packet time (i.e. the “ptime=” value in the session sdp), the media engine will adapt to the new packet time as required. G729/G729A RTP packets can now be 20Ms or any other greater value. Negotiated resolution is one byte of sample data which is 1Ms for 8kHz G729/G729A codecs.
21)
Added 2 new Phone line events.
Added the following 2 new phone line events: SipMemoryError and SipThreadCreationError.
These events can be sent to application software if the media engine detects memory or internal thread start errors while processing outgoing or incoming phone calls.
22)
Minimizing virtual memory requirements.
A new section entitled "Minimizing virtual memory requirements" has been added to the VOIP Media Engine Software Developer's Reference.
This new section describes simple methods developers can
use to drastically lower the virtual memory requirements of the media engine
and the VOIP application. This information is important for developers who are
using phone line densities 128 lines or greater and who are developing server
based VOIP applications. This is a "must read" for all VOIP
developers.
23)
Improved low virtual memory performance.
The media engine has been improved to better handle low virtual memory situations. The ability to handle and recover from low memory or exhausted memory situations is an on going effort. This product version handles many more internal low memory situations which could otherwise cause access violations.
24)
Greatly improved call processing throughput when not using audio out multimedia
hardware.
Call processing throughput for incoming and outgoing calls has greatly been improved.
When application software disables multimedia audio output usage, the media engine no longer performs unnecessary checks and attempts to generate local audio telephony sounds such as outgoing phone ring, incoming phone ring, far end error or busy, etc.
Theses new enhancements allow the media engine to remove noticeable incoming and outgoing call processing delays that would lower overall call processing throughput. Previous to this release, applications may notice call processing delay mostly when answering incoming phone calls. The delay would occur between the reception of “180 Ringing” provisional responses and immediately before going off hook to answer the incoming call. Secondarily, outgoing calls would experience a slight call processing delay at the point where the media engine notifies the application using the SipStartOutgoingRing event. All VOIP applications will now be able to process a greater number of calls per minute due to these recent changes.
25)
Applications can now directly transmit generic UDP packet data via the media
engine.
The media engine now allows applications to directly send generic UDP data or
application defined SIP packets using the UDP server port of the media engine.
This is useful if applications want to send application specific data to a
remote log server or if applications want to create and transmit their own SIP
messages.
For further information see the SendUdpDatagram() and
SendUdpDatagramUsingSipPort() API procedures in the VOIP Media Engine
Developer’s Reference.
26)
Inter-op tested with the latest version of Asterisk PBX (v1.4.21.2).
This latest version of the VOIP Media Engine has been
inter-op tested with the latest version of Asterisk PBX v1.4.22.1. Subtle but
important updates have been performed on the media engine to ensure optimal
performance with Asterisk.
27)
Added new return error codes to StartSipTelephony() and ReStartSipTelephony()
API procedures.
Added the SipUdpRxBufferSizeError and
SipUdpTxBufferSizeError return values to StartSipTelephony() and
ReStartSipTelephony() API procedures. These two additional error return values
will inform application software of possible SIP UDP buffer sizing errors when
the media engine is started or restarted.
28)
Application created DTMF generators and decoders are now cleaned up by the
media engine.
If your VOIP application media engine DTMF generators
and/or decoders, the media engine will now make sure the resources used by
these elements are recovered when the media engine terminates or restarts.
Improved handle validation has also been improved.
29)
Improved interoperability associated with SDP ptime value and 30Ms iLBC only
calls.
For calls being initiated by the media engine that use 30Ms iLBC frame sizes and only have a single codec selected, the SDP ptime parameter was always being set to 20. It now gets set to 30. This has been done to improve interoperability with some devices that use the ptime SDP value instead of using the required iLBC mode parameter in the media attribute for the call.
Note that if mixing 20Ms and 30Ms codec types in a SIP
INVITE (i.e. having multiple codecs selected), the ptime value will be set to
20Ms even if a 30Ms iLBC codec is being offered as a possible media type in the
INVITE.
30)
New interoperability - Cisco-SIPGateway/IOS-12.x.
This latest version of the LanScape VOIP Media Engine has now been tested to interoperate with Cisco SIP VOIP Gateways (IOS-12.x). For further information, see the following URL:
http://www.cisco.com/en/US/products/ps6831/products_data_sheet0900aecd804110a2.html
31)
New interoperability - Cisco/Linksys SPA3102 PSTN gateway.
This latest version of the LanScape VOIP Media Engine has now been tested to interoperate with Linksys SPA3102 SIP VOIP Gateways.
32)
New interoperability - ENTICE VoIP Gateway.
This latest version of the LanScape VOIP Media Engine has now been tested to interoperate with ENTICE SIP VoIP Gateways.
33)
New interoperability - 3CX PBX.
This latest version of the LanScape VOIP Media Engine has now