StartSipTelephony

 

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 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.

 

 

TELEPHONY_RETURN_VALUE StartSipTelephony(

START_SIP_TELEPHONY_PARAMS *pStartupParams,

SIPHANDLE *pStateMachineHandle

);

 

 

Parameters:

 

pStartupParams

[in] A pointer to the configuration parameters of type START_SIP_TELEPHONY_PARAMS.

 

pStateMachineHandle

[in] A pointer to a memory location that will receive the new handle to the telephony engine.

 

 

Return Value:

 

If the function succeeds, the return value will be SipSuccess.

 

If the function fails, the return value will be one of the following values as specified by the TELEPHONY_RETURN_VALUE data type.

 

 

 

Value

Description

SipCallFailure

This is a generic "catch all" API error. If an error condition is not specified by any other API error value, this error will be returned.

 

SipMediaEngineNotInitialized

Before attempting any telephony operation, the LanScape VOIP Media Engine™ must be initialized using the InitializeMediaEngine API procedure. This error is generated when you attempt to instantiate the telephony engine prior to calling the InitializeMediaEngine API procedure. You will also get this error if you call the UnInitializeMediaEngine API procedure more than once.

 

SipBadParameter

For API procedures that receive pointers from user software, this error indicates that a NULL pointer condition was detected. Make sure all pointers your software passes to the telephony API are valid.

 

SipThreadCreationError

Indicates a critical thread creation error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the operating system can not create additional threads of execution. Close all other non essential applications.

 

SipBandwidthError

If application software has instantiated the telephony engine where the telephony engine will manage the audio capture and/or playback of audio data, this error indicates that an improper audio capture and/or playback sample rate was specified when the StartSipTelephony API procedure was called. This error will also occur if the multi media hardware on the host machine is not configured properly or does not exist. For further information see START_SIP_TELEPHONY_PARAMS.

 

SipBadNumberOfPhoneLines

An attempt was made to start the telephony engine using the StartSipTelephony API procedure. The number of phone lines that were requested is in excess of what your version of the telephony engine supports. Instantiate the telephony engine using the proper number of phone lines.

 

SipInvalidInstance

Application software attempted to create additional instances of the telephony engine. Your version of the telephony engine does not support this capability.

 

SipMemoryError

Indicates a critical internal memory error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application.

 

SipNetworkInitializeError

Indicates a critical internal network initialization error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. For host systems running Microsoft Windows operating systems, you must have Windows socket 2 support properly installed. Close all other unnecessary network applications to reduce the loading on the host machine's network layer.

 

SipStartRtpPortError

When the telephony engine is instantiated using the StartSipTelephony API procedure, application software must specify proper values for RTP UDP ports. A single port can be specified or a range of ports can be specified. There are two members in the START_SIP_TELEPHONY_PARAMS that are passed to the telephony engine that specify the RTP port information. The first port number in the specified range must be an even port number. An example of an even number port would be port 8000.

 

SipRtpAndSipPortOverlapError

If the telephony engine is to be instantiated multiple times in a single application (many telephony engine instances at the same time), this error indicates that there is a SIP and/or RTP port overlap error between instances. If your application creates more than one telephony engine, make sure each uses a unique SIP port. For example: If you create two instances of the telephony engine, the first instance could use port 5060 and the second instance could use port 5062). Also make sure that the RTP port ranges for each telephony engine do not overlap.

 

SipEventError

Indicates a critical internal error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the operating system can not create additional event handles. Close all other non essential applications.

 

SipAudioOutFailure

An error was detected when the telephony engine attempted to initialize the audio playback subsystem. Make sure your multimedia hardware on your host machine is installed and configured properly. Also, if your audio output hardware allows only a single output channel to be opened at any one time, make sure that no other application is using your audio output device.

 

SipAudioInFailure

An error was detected when the telephony engine attempted to initialize the audio capture subsystem. Make sure your multimedia hardware on your host machine is installed and configured properly. Also, if your audio input hardware allows only a single input channel to be opened at any one time, make sure that no other application is using your audio input device.

 

SipRtpReceiverEventError

Indicates a critical internal error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the operating system can not create additional event handles. Close all other non essential applications.

 

SipRtpReceiverThreadStartFailure

Indicates a critical thread creation error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the operating system can not create additional threads of execution. Close all other non essential applications.

 

SipPlaybackMixerThreadStartError

Indicates a critical thread creation error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the operating system can not create additional threads of execution. Close all other non essential applications.

 

SipSocketOpenError

Indicates a critical internal socket error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the telephony engine could not open a required network socket. Close all other non essential applications.

 

SipSocketBindError

Indicates a critical internal socket error within the telephony engine. User application software should not continue if this error is detected. Make sure the host machine is configured properly and is adequate for the intended application. This error indicates the telephony engine could not perform a bind operation on the a required network socket.

 

You must make sure the IP address you specified when instantiating the telephony engine is correct for your host machine. It is also possible that another application has performed a socket bind operation on a socket required by the telephony engine. In this case, close all other non essential applications that access the network

 

SipBadPhoneName

An attempt was made to start the telephony engine using the StartSipTelephony API procedure. The specified phone name was invalid. This error will be returned if the pointer to the phone name is a NULL pointer.

 

SipBadDisplayName

 

An attempt was made to start the telephony engine using the StartSipTelephony API procedure. The specified phone display name was invalid. This error will be returned if the pointer to the phone display name is a NULL pointer.
 

SipUdpRxBufferSizeError

Low level SIP UDP receive buffers could not be resized. you may have to specify a smaller value for the SipUdpReceiveBufferSizeInBytes startup parameter.
 

SipUdpTxBufferSizeError

Low level SIP UDP transmit buffers could not be resized. you may have to specify a smaller value for the SipUdpTransmitBufferSizeInBytes startup parameter.