START_SIP_TELEPHONY

The START_SIP_TELEPHONY_PARAMS structure is used to specify startup conditions for the telephony engine. It has the following format:

typedef struct

{

unsigned char *pPersonalityMicrocode;

unsigned int NumPhoneLinesRequested;

LINE_MODE LineMode;

SIPCALLBACKPROC UserNotifyCallbackProc;

void *pUserDefinedData;

BYTE IpAddressOfThisHost[NUM_BYTES_IP_ADDRESS];

int SipPort;

int MaxSipMesageLength;

int SipUdpReceiveBufferSizeInBytes;

int SipUdpTransmitBufferSizeInBytes;

int MaxSipMessageReceiveFifoLength;
int MaxRtpPacketLength;

char *pPhoneName;

char *pPhoneDisplayName;

BOOL DtmfEnabled;

BOOL DtmfTonesPlayedLocally;

BOOL DtmfTonesTransmittedOutPhoneLines;

int DtmfLocalAudioPlaybackBuffering;

int DtmfPhoneLineAudioBuffering;

int DtmfIncomingPhoneLineEventBuffers;
BOOL CallConferenceEnabled;

BOOL FarEndCallTransferEnabled;

BOOL RandomlyAssignIncomingCallsToPhoneLines;

int MinLocalRtpPort;

int MaxLocalRtpPort;

BOOL UseSequentialRtpPorts;

int ZeroBasedAudioInDeviceId;

int ZeroBasedAudioOutDeviceId;

AUDIO_BANDWIDTH AudioRecordBandWidth;

AUDIO_BANDWIDTH AudioPlaybackBandWidth;

int PlaybackBufferingDefault;

int PlaybackBufferingDuringSounds;

int PhoneLinePlayoutBuffering;

int PhoneLineTransmitBuffering;

BOOL LogSipMessages;

char *pSipLogFileName;
BOOL EnableEventLogServers;

char *pEventLogServerList;

char *pEventLogServerPortList;

BOOL EnablePhoneLineRecording;

int PhoneLineRecordBuffering;
int MaxMixerLinebuffers;
BOOL SendLineInitializedEvents;

ULONG StartupFlags;

}START_SIP_TELEPHONY_PARAMS;

This is a pointer to your LanScape supplied personality/microcode information. Personality and microcode information is linked to your build using a supplied LanScape OBJ file image or the supplied C language source code module. For further information regarding how to use personality module information, see the section Using Personality Microcode Information.

This member allows you to specify the number of phone lines the telephony engine will create and manage. Your specific image of the telephony engine has been designed to support the maximum number of phone lines and options you purchased. If for some reason you only want to instantiate a subset of the total number of supported lines, this member gives you the ability to do so. Allowing the telephony engine to create only the required number of phone lines save system resources and host memory. Note: You will not be able to create more phone lines than what your license supports.

This member specifies the mode of each phone line. There is a single supported phone line mode available: SWITCH_LINE mode. For further details on this member, see LINE_MODE.

This is the address of the main callback procedure the telephony engine will execute when your application needs to be notified of telephony events.

This parameter can be assigned any value you desire. Its value is passed to your callback procedure specified in the previous member. Generally used to keep track of instance data.

The 4 byte IP address you want the telephony engine to use. Byte 3 is the most significant byte of the IP address, Byte 0 is the least significant byte of the IP address.

The UDP port number to be used by the telephony engine. Normally for SIP enabled applications, this value is set to port 5060. It can be any value you require.

Allows the application to specify the maximum SIP message size that can be processed. Any value 1500 bytes or larger is generally acceptable.

This value allows application software to specify the low level SIP UDP receive buffer size that is used by the media engine. Application software can increase this value in the event that SIP UDP packets are lost due to Windows UDP receive buffering limitations. Setting the proper receive buffer size will allow the media engine to process calls as fast as possible. Normally this value can be specified to be zero. In this case, the media engine will compute its value based on startup parameters and line density.

This value allows application software to specify the low level SIP UDP transmit buffer size that is used by the media engine. Setting the proper transmit buffer size will allow the media engine to process calls as fast as possible. Normally this value can be specified to be zero. In this case, the media engine will compute its value based on startup parameters and line density.

This value allows application software to specify the maximum number of SIP messages that the media engine will hold in its receive fifo queue. If the media engine receive fifo is filled, application software will sent the global notification event NewSipSessionReceiveOverrun. In this case, the fifo depth should be increased or the media engine application should be hosted on a faster server machine.

This value will allow application programs to specify the maximum number of bytes that can be transmitted and received in any RTP UDP data packet. This byte count includes RTP header and media payload data. Primarily used when application software encodes transmitted RTP data and as the result of the encoding process, generates RTP UDP packets that are larger than normal RTP media packets.

In addition: If an application encodes/decodes RTP media packets, the value specified by this parameter determines the maximum RTP buffer size of the RTP packets that are sent to the application.

Under normal situations, application software should set this value to zero. In this case, the media engine will determine the appropriate RTP media buffer requirements.

Each instance of the telephony engine is considered a single phone set. SIP 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. This name is also used if you allow the telephony engine to register with a SIP proxy server or a registrar server. In the case of SIP proxy and registrar servers, this is the name of your telephony engine in the domain of the SIP proxy or registrar server. The name you assign to 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.

An alternative name for the phone. Used for SIP display name purposes. This value is generally set to the same value as the pPhoneName member. The display name string you assign to the telephony engine can contain any of the following ASCII character code values: (0x20 - 0x21), (0x23 - 0x3B), 0x3D, (0x3F - 0x5B), (0x5D - 0x7E).

This value must be set to non zero if the VOIP application wants to enable internal in-band or RFC2833 DTMF generation and detection.

If this value is set to a non zero value, DTMF tones will be able to be played back on local multimedia hardware (if enabled) whenever the VOIP application turns a DTMF digit ON. Note that this parameter allows the media engine to configure itself to support this capability. The application can at any time determine if DTMF tones get played back locally when the DTMF tone is started using the StartDtmfTone API procedure.

DtmfTonesTransmittedOutPhoneLines

If this value is set to a non zero value, DTMF tones will be able to be sent out the phone lines when the application starts a DTMF tone. The 8kHz DTMF tone information is taken from the internal DTMF generator and digitally mixed with phone line transmitted RTP media. Note that this parameter allows the media engine to configure itself to support this capability. The application can at any time determine if DTMF tones get played out any individual phone line when the DTMF tone is started using the StartDtmfTone API procedure.

DtmfLocalAudioPlaybackBuffering

Specifies the internal audio buffering depth of DTMF sample blocks (from the internal DTMF generator) as they are sent to local multimedia hardware for local playback. This value is generally set to 2 to imply "double buffering". If your host computer is slow or you experience broken DTMF local audio playback, you may have to increase this value.

DtmfPhoneLineAudioBuffering

Specifies the audio buffering depth of DTMF sample blocks (from the internal DTMF generator) as they are sent to all enabled phone lines. This value is generally set to 2 to imply "double buffering". If your host computer is slow or you experience broken DTMF audio at the far end of the call, you may have to increase this value.

DtmfIncomingPhoneLineEventBuffers

When incoming in-band or RFC2833 DTMF events are detected by the media engine's RTP receivers, the DTMF events are "minimally" processed and placed into an internal FIFO queue for full deferred processing. This alleviates RTP receivers from possibly introducing latency in the incoming media path. This startup parameter controls the incoming FIFO depth on a per phone line basis. If your VOIP application is under heavy load, the media engine will send your application the SipPhoneLineIncomingDtmfEventOverflow event if it runs out of FIFO event space in the processing queue. In this case, you should either execute your application on a faster host computer or try increasing the value of this parameter. The internal default value is 5, which is also the minimum allowed value.

Allows application software to specify the enable state of conference calling. If your application does not require conference call capability, you should disable conference call support by setting this member to zero. Doing so will reduce the memory requirements of your VOIP application. Note:If you are not licensed to use conference calling, this member is ignored.

Allows application software to specify the enable state of far end initiated call transfers. For some applications, it is required that far end initiated call transfers do not take place. Most applications that are developed to be unattended and function as an IVR call point will want to disable far end call transfers.

Setting this startup value to non zero (TRUE) will allow the media engine to randomly assign incoming phone calls to any available phone line that is already not in use. If you are developing a server based VOIP application, you should set this value to non zero. Doing so will yields slightly better call handling performance and throughput. For all other application such as soft phones or non server based VOIP application, you can set this value to zero (FALSE).

The minimum UDP port number the telephony engine’s internal RTP stack will use. This value must be an even number. Normally set to 8000. The telephony engine will use ports in the range of MinLocalRtpPort through (MaxLocalRtpPort-1) during normal operation. For further information, see the description for MaxLocalRtpPort immediately following this description.

The maximum UDP port number that specifies the end of the usable UDP port range for the internal RTP stack. The telephony engine will use ports in the range of MinLocalRtpPort through (MaxLocalRtpPort-1) during normal operation. This value must be an even number and must minimally be set to a value of (MinLocalRtpPort + (2 * Number of supported phone lines)).

Note: Each phone line that is instantiated by the telephony engine requires that two UDP ports be reserved. The first port is used to stream telephony audio data (the event port) and the second is reserved for future RTCP purposes (the odd port). Currently no media or control information passes through the odd port.

Allows application software to specify the use of sequential RTP media ports or random RTP media ports. The use of sequential RTP media ports can be useful when debugging VOIP applications. Alternatively, using random RTP media ports may improve security. If this value is set to a non zero (TRUE) value, the media engine will use RTP ports sequentially for outgoing and incoming calls. If set to zero (FALSE), the media engine will use RTP ports randomly.

The zero based ID of the multimedia audio input and output device the telephony engine will use for audio record and playback operations. The device IDs specified here are the same device IDs as reported by the Windows multimedia APIs.

You can use the following telephony API procedures to interrogate your system in order to see what multimedia hardware is installed:

If you specify the value of SIP_USE_PREFERED_AUDIO_DEVICE for these parameters, the telephony engine will use the preferred audio input and output devices as specified by your system's multimedia settings.

If you specify the value of SIP_AUDIO_DEVICE_NOT_USED for these parameters, the telephony engine will disable its internal audio device support and will not manage audio input or output devices on the system.

Specifies the internal rate and format to use for internal audio record operations. Currently the only value supported is AUDIO_BW_PCM_22K.

Specifies the internal rate and format to use for internal audio playback operations. Currently the only value supported is AUDIO_BW_PCM_22K.

Specifies the default internal playback buffering that will be used with audio data before final playback. This default buffering does not include buffering that is applied to internally generated telephony sounds or audio outputs. Normally, double buffering is what is required for most applications. In this case, this value should be set to 2.

Depending on the operating system you are deploying to and the speed of the host hardware, a value greater than 2 might have to be specified to obtain smooth unbroken audio results. If you are specifying values greater than 2 for this parameter, you should use a faster host machine. Increasing the value of this parameter will increase playback delays. You can specify values in the range of 2 to 64 inclusive.

Specifies the internal playback buffering that will be used for internal telephony sounds and the audio output interface. Normally, double buffering is what is required for most applications. In this case, this value should be set to 2.

Depending on the operating system you are deploying to and the speed of the host hardware, a value greater than 2 might have to be specified to obtain smooth unbroken audio results. If you find yourself specifying values greater than 2 for this parameter, you should use a faster host machine. Increasing the value of this parameter will increase playback delays for internal telephony generated sounds and the audio outputs. You can specify values in the range of 2 to 64 inclusive.

This value allows you to control the time scaled play out of streaming audio from your multimedia record hardware to each individual phone line. This value allows the application to specify the audio adaptive "play out" buffering depth that will be used when the media engine sends locally recorded audio to each individual phone line. If your application does not configure the media engine to use locally recorded audio from your multimedia hardware, this value is ignored.

Under normal situations, this value can be set to 1 or 2. The lower the value, the less phone line transmit latency will be achieved. Setting this value higher will slightly increase audio transmit latency but will ensure continuous streaming transmit phone line audio. If for some reason you experience broken or "choppy" phone line transmit audio in your VOIP calls, increase this value until the transmit audio is clear and continuous. For multimedia record hardware and driver combinations that exhibit non real time timing characteristics, you may have to increase this parameter value to 4 or higher. Doing so will allow the media engine to properly compensate adaptively for the non real time nature of your selected record hardware/driver installation.

Specifies the internal phone line transmit buffering depth that will be used for all audio data that is transmitted via the RTP protocol. Normally, double buffering is what is required for most applications. In this case, this value should be set to 2. Increasing the value of this parameter will act to increase audio transmit delays. You can specify values in the range of 2 to 64 inclusive.

Specifies that the application software wants to log all SIP message transactions. To enable SIP message logging, set this member to TRUE. If SIP message logging is enabled, member pSipLogFileName must also be specified. A SIP message log file will be created when the telephony engine is instantiated. The SIP message log will be closed when the telephony engine terminates. If a previous SIP message log file exists from a previous logging session, it will be overwritten. SIP logging capability is used for debug purposes. Normally, applications should not be logging SIP transactions unless you are debugging session connectivity problems. All SIP messages that are received or transmitted will be logged. If you want to generate SIP log files for specific phone lines, see the LogPhoneLineSipMessages API procedure.

As an alternative to static log file generation, consider using the LanScape supplied SIP log server utility (SipLogD.exe) and call the SetSipLogServer API procedure in your application source code. If you use the SIP log server utility, you will not have to continually restart your application to view SIP message logs.

Specifies the path name of the SIP message log the telephony engine will create. This file name can be specified as a relative or absolute path.

The media engine has the ability to send "man readable" event messages to one or more event log servers. You can use the supplied event log server (EventLogD.exe) application to receive and view real time events that are sent to your application software. This capability is very useful for understanding the event mechanism of the media engine.

If you do not enable event logging using this parameter, you can still use event logging later in your application. For more information regarding event logging, see the SetEventLogServer API procedure. If you do not enable event logging before instantiating the media engine, you will not see certain startup event that are sent to application software.

Specifies the IP address or host name of one or more event log servers. This parameter is a pointer to a null terminated ASCII string that contains comma delimited host names or IP addresses of the remote event log servers.

Specifies the UDP ports of one or more event log servers. This parameter is a pointer to a null terminated ASCII string that contains comma delimited ports of the remote event log servers. The order of the ports is the same as the order of the hosts as specified by the pEventLogServerList parameter.

If your application needs to record phone calls from any of the media engine's phone lines, you must enable this setting. Call recording using the media engine is simple and requires no application assistance other than starting and stopping the recording process. For complete details associated with phone call recording, see the StartPhoneLineRecording API procedure.

Specifies the audio buffering depth of recorded phone line audio. For most application, you should set this value to zero.

Specifies the max signal buffering that occurs internally in the media engine. Each mixer line buffer represents 20Ms of audio sample data. The internal default value for this parameter is 64. If you do not want to change the default value when the media engine is initialized, then specify a value of zero.

This parameter affects the max buffering depth for all internally handled audio sample blocks during digital mixing operations. Reducing this value will save memory but at the cost of possible interrupted or "choppy" audio. This value also has the effect of capping the maximum received voice delay that a phone line will experience.

This value will allow application programs to enable or disable the ability of the media engine to send phone line initialize events to the application during startup. If enabled, the media engine will send the SipLineInitialized PHONE_LINE_NOTIFICATION event to the application for each phone line created by the media engine. Large line applications generally use this to drive a GUI progress display when the VOIP application starts.

Specifies optional startup and terminate setting of the telephony engine. The following flags can be ORed together to specify the startup flags value: