SetCallInstanceData

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.

TELEPHONY_RETURN_VALUE SetCallInstanceData(

SIPHANDLE hStateMachine,

int PhoneLine,

void *pUserCallInstanceData,

int UserCallInstanceLength

);

Parameters:

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

PhoneLine

[in] The zero based phone line to access.

pUserCallInstanceData

[in] A pointer to the application's call instance data. This data will be sent to the receiving end of the call.

UserCallInstanceLength

[in] The number of bytes in the call instance data.

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.
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.
SipInvalidHandle	An API procedure was passed an invalid handle. The telephony engine attempts to verify user specified telephony handles and returns this error when an invalid handle is detected.
SipBadPhoneLine	A telephony operation was specified using an invalid phone line. Phone lines are numbered starting from zero.
SipApiProcNotAllowed	Your application called this API procedure when it was not allowed. This API procedure can only be called during the processing of the SipOutgoingCallInitializing and SipOutgoingTransferInitializing events.