interface .SIP

This API defines the SIP message stack.

Public Methods

[more]SLSIP_API SLresult SLSipInit(void *args)
Purpose: Global initialization of speech link API.
[more]SLSIP_API SLresult SLSipShutdown(void *args)
Purpose: Global shutdown of speech link.
[more]SLSIP_API SLresult SLSipGetProperty(const SLchar *propName, SLValue *value)
Purpose: Retrieve properties of the underlying SIP stack.
[more]SLSIP_API SLresult SLSipSetProperty(const SLchar *propName, SLValue *value)
Purpose: Set a property on the SIP stack.
[more]SLSIP_API SLresult SLSipAddCallback(SLSipEvent e, SLSipEventInfo *info)
Purpose: Set the event callback for the speech link API.
[more]SLSIP_API SLresult SLSipRemoveCallback(SLSipEvent e, SLSipEventInfo *info)
Purpose: Gets the current event callback structure for the speech link API.
[more]SLSIP_API SLchar SLSipErrorMsg(SLresult err)
Purpose: Get the error string for an error.
[more]SLSIP_API SLresult SLSipStart()
Purpose: Start the SIP event loop.
[more]SLSIP_API SLresult SLSipStop()
Purpose: Stops the SIP event loop.
[more]SLSIP_API SLresult SLSipCallInvite(SLCall** call, const SLchar *sipurl, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Invites the specified SIP URL.
[more]SLSIP_API SLresult SLSipCallDestroy(SLCall** call)
Purpose: Destroys the call and release any resource that are used by the call.
[more]SLSIP_API SLresult SLSipCallAccept(SLCall* call, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Accepts an incoming call.
[more]SLSIP_API SLresult SLSipCallReject(SLCall* call, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Rejects an incoming call.
[more]SLSIP_API SLresult SLSipCallAck(SLCall* call)
Purpose: Acknowledges the connection of the outgoing call.
[more]SLSIP_API SLresult SLSipCallTerminate(SLCall* call)
Purpose: Terminates the call (hang up).
[more]SLSIP_API SLresult SLSipCallReinvite(SLCall* call, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Sends a re-invite to the other party.
[more]SLSIP_API SLresult SLSipCallRespondToReinvite(SLCall *call, SLuint statusCode, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Send a SIP response to a reinvite.
[more]SLSIP_API SLresult SLSipCallAnswer(SLCall *call, SLuint statusCode, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Answer the initial INVITE message.
[more]SLSIP_API SLresult SLSipMessageGetHeader(SLSipMessage *message, const SLchar *header, void *value)
Purpose: Returns the value of a header.
[more]SLSIP_API SLSipResponse SLSipMessageAsResponse(SLSipMessage *message)
Interprets the SIP message as a SIP response.
[more]SLSIP_API SLSipRequest SLSipMessageAsRequest(SLSipMessage *message)
Interprets the SIP message as a SIP request.
[more]SLSIP_API SLresult SLSipMessageGetContentTypeAttributeValue(SLSipMessage *message, const SLchar *attribute, const SLchar **value)
Retrieves an atttribute of the content-type header of the message.
[more]SLSIP_API SLresult SLSipResponseGetStatusCode(SLSipResponse *response, SLuint* code)
Returns the status of a response.
[more]SLSIP_API SLresult SLSipResponseGetReasonPhrase(SLSipResponse *response, const SLchar** value)
Purpose: Return the SIP reason phrase for the response.
[more]SLSIP_API SLresult SLSipRequestGetMethod(SLSipRequest *request, const SLchar **method)
Purpose: Return the SIP method contained in the SIP request

Documentation

This API defines the SIP message stack. This API is responsible for low level SIP message marshalling, tying messages to call sessions, and handling IP based events.
oSLSIP_API SLresult SLSipInit(void *args)
Purpose: Global initialization of speech link API.

Create a speech link API and instantiate it.

Parameters:
args - An object containing data that is used to initialize the platform (implementation specific).
Returns:
SL_SUCCESS if the API initialized normally, a value smaller than SL_SUCCESS if API could not be initialized.

oSLSIP_API SLresult SLSipShutdown(void *args)
Purpose: Global shutdown of speech link.

Parameters:
args - An object containing data that is used to initialize the platform (implementation specific).
Returns:
SL_SUCCESS if the API shuts down normally, a value smaller than SL_SUCCESS if the API could not be shutdown.

oSLSIP_API SLresult SLSipGetProperty(const SLchar *propName, SLValue *value)
Purpose: Retrieve properties of the underlying SIP stack. For SIP port and timeout, the value must be a SLInteger*. For others, it should be a const SLchar**.

Parameters:
propName - NULL terminated string containing the name of the property
value - SLValue containing the property value. Will be allocated in the call.
Returns:
SL_SUCCESS if the property exists and could be fetched, a value smaller than SL_SUCCESS if the property could not be fetched.

oSLSIP_API SLresult SLSipSetProperty(const SLchar *propName, SLValue *value)
Purpose: Set a property on the SIP stack. For SIP port and timeout, the value must be a SLInteger*. For others, it should be a const SLchar**.

Parameters:
propName - NULL terminated string containing the name of the property
value - SLValue containing the property value to set.
Returns:
SL_SUCCESS if the property could be set, a value smaller than SL_SUCCESS if the property could not be set.

oSLSIP_API SLresult SLSipAddCallback(SLSipEvent e, SLSipEventInfo *info)
Purpose: Set the event callback for the speech link API.

Parameters:
e - in[x] The event to on which to add a callback
info - in[x] structure containing the callback information. The information is copied and the structure can be safely modified after the function returns.
Returns:
SL_SUCCESS if the callback could be set, a value smaller than SL_SUCCESS if the callback could not be set.

oSLSIP_API SLresult SLSipRemoveCallback(SLSipEvent e, SLSipEventInfo *info)
Purpose: Gets the current event callback structure for the speech link API.

Parameters:
e - in[x] The event on which to get the current event callback structure
info - out[x] structure where the information is to be stored. The structure must be allocated by the caller.
Returns:
SL_SUCCESS if the callback could be removed, a value smaller than SL_SUCCESS if there is an error.

oSLSIP_API SLchar SLSipErrorMsg(SLresult err)
Purpose: Get the error string for an error. The message returned is a reference to a static string and should not be modified by the caller.

Parameters:
err - The error code for which the string version is to be retrieved.
Returns:
A 0-terminated string representing the error.

oSLSIP_API SLresult SLSipStart()
Purpose: Start the SIP event loop.

The event loop is run in the current thread. This method normally only returns when another thread calls the SLSipStop() function.

Returns:
SL_SUCCESS if the event loop was successfully started and normally completed, less than SL_SUCCESS if the event loop could not be started or did not complete normally. Exact value can be inspected to determine the cause of the problem.

oSLSIP_API SLresult SLSipStop()
Purpose: Stops the SIP event loop.

This causes the SLSipStart() function to return with a return code of SL_SUCCESS.

Returns:
SL_SUCCESS if the event loop was successfully stopped, less than SL_SUCCESS if there is no event loop running or it could not be stopped.

oSLSIP_API SLresult SLSipCallInvite(SLCall** call, const SLchar *sipurl, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Invites the specified SIP URL.

Invites the specified SIP URL and returns a call object. SIP URL's must all start with sip: The call object must freed using the function SLSipCallDestroy when the call is terminated.

This will trigger the SL_INVITE event on the callee side.

Parameters:
call - out[x] The call object used to control call.
sipurl - in[x] The SIP URL of the callee.
bodyType - in[x] The mime-type of the user data body message.
body - in[x] The data block to be sent
bodyLength - in[x] The length of the body being sent in bytes
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure. Exact value can be inspected to determine cause of problem.

oSLSIP_API SLresult SLSipCallDestroy(SLCall** call)
Purpose: Destroys the call and release any resource that are used by the call.

Parameters:
call - inout[x] The call object to destroy. The value is reset to NULL.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure. Exact value can be inspected to determine cause of problem.

oSLSIP_API SLresult SLSipCallAccept(SLCall* call, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Accepts an incoming call.

The call is accepted by sending a 200/OK response. The calling party will have a SL_SUCCEEDED event triggered upon reception of the 200 response.

Parameters:
call - in[x] The call being accepted.
bodyType - in[x] The mime-type of the user data body message.
body - in[x] User specific data that is part of the response message.
bodyLength - in[x] The length of the body in bytes
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure. Exact value can be inspected to determine cause of problem.

oSLSIP_API SLresult SLSipCallReject(SLCall* call, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Rejects an incoming call.

This function is used when the callee does not wish to engage in a conversation with the caller. This function triggers the SL_TERMINATED event at the calling party.

Parameters:
call - in[x] The call being rejected.
bodyType - in[x] The mime-type of the user data body message.
body - in[x] User specific data that is part of the response message.
bodyLength - in[x] The length of the body in bytes
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure. Exact value can be inspected to determine cause of problem.

oSLSIP_API SLresult SLSipCallAck(SLCall* call)
Purpose: Acknowledges the connection of the outgoing call.

This function should be called as part of the handler for SL_SUCCEEDED events. This will trigger the SL_CONFIRMED event on the callee side.

Parameters:
call - in[x] The channel for which the call is acknowledged.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure. Exact value can be inspected to determine cause of problem.

oSLSIP_API SLresult SLSipCallTerminate(SLCall* call)
Purpose: Terminates the call (hang up). This method is called by either party wishing to terminate a call. This trigger the SL_TERMINATED event of the other party. Either a BYE or a CANCEL request is sent depending on the state of the call.

Parameters:
call - The channel on which the call is terminated.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure. Exact value can be inspected to determine cause of problem.

oSLSIP_API SLresult SLSipCallReinvite(SLCall* call, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Sends a re-invite to the other party. This method should only be called after the initial invite has been positively answered and acknowledged. This method is called by either party wishing to change parameter of the session. This trigger the SL_REINVITED event of the other party.

Parameters:
call - [in] the call for which the re-invite is to be sent.
bodyType - [in] the mime type of the body of the message.
body - [in] the body of the message.
bodyLength - [in] the number of bytes in the body.
Returns:
SL_SUCCESS if success, less than SL_SUCCESS if failure. Exact value can be inspected to determine cause of problem.

oSLSIP_API SLresult SLSipCallRespondToReinvite(SLCall *call, SLuint statusCode, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Send a SIP response to a reinvite.

Parameters:
call - [in] the call for which the re-invite is to be sent.
statusCode - [in] the SIP status code to send as part of the re-invite
bodyType - [in] the mime type of the body of the message.
body - [in] the body of the message.
bodyLength - [in] the number of bytes in the body.
Returns:
SL_SUCCESS if the re-invite succeeded, a value smaller than SL_SUCCESS if it failed.

oSLSIP_API SLresult SLSipCallAnswer(SLCall *call, SLuint statusCode, const SLchar *bodyType, const void *body, SLuint bodyLength)
Purpose: Answer the initial INVITE message. This is useful to send provisional response but is not limited to it: one could use this function instead of SLSipCallAccept or SLSipCallReject.

Parameters:
call - [in] the call for which the invite is to be sent.
statusCode - [in] the SIP status code to send in response to the invite.
bodyType - [in] the mime type of the body of the message.
body - [in] the body of the message.
bodyLength - [in] the number of bytes in the body.
Returns:
SL_SUCCESS if the invite response succeeded, a value smaller than SL_SUCCESS if it failed.

oSLSIP_API SLresult SLSipMessageGetHeader(SLSipMessage *message, const SLchar *header, void *value)
Purpose: Returns the value of a header. The value parameter must be a SLchar** except in the case where header is ContentLength, CSeq, or BodyLength, in which case it has to be a SLuint*

Parameters:
message - [in] The SIP message that was delivered.
header - [in] NULL terminated header parameter to extract
value - [out] Pointer to a place to store the result. For SLchar**, a pointer to a string belonging to the message is returned. This string should be copied by the caller if it is needed after the message goes out of scope.
Returns:
SL_SUCCESS if the parameter was retrieved and set, a value less than SL_SUCCESS on error.

oSLSIP_API SLSipResponse SLSipMessageAsResponse(SLSipMessage *message)
Interprets the SIP message as a SIP response.

Parameters:
message - The message to be interpreted as a SIP response.
Returns:
A non-null object if the message is a response, null if the message is a request.

oSLSIP_API SLSipRequest SLSipMessageAsRequest(SLSipMessage *message)
Interprets the SIP message as a SIP request.

Parameters:
message - The message to be interpreted as a SIP request.
Returns:
A non-null object if the message is a request, null if the message is a response.

oSLSIP_API SLresult SLSipMessageGetContentTypeAttributeValue(SLSipMessage *message, const SLchar *attribute, const SLchar **value)
Retrieves an atttribute of the content-type header of the message.

Parameters:
message - in[x] The message for which the content-type header is to be retrieved.
attribute - in[x] A null-terminated string containing the name of the attribute to retrieve.
value - out[x] A pointer to be set to the value of the attribute. The pointer points to a string whose lifetime is the same as the message (for the duration of the event handler).
Returns:
SL_SUCCESS if the attribute was retrieved and set, a value less than SL_SUCCESS on error.

oSLSIP_API SLresult SLSipResponseGetStatusCode(SLSipResponse *response, SLuint* code)
Returns the status of a response.

Parameters:
response - [in] The SIP response structure
code - [out] The response code in the response structure
Returns:
SL_SUCCESS if the response code was retrieved and set, a value less than SL_SUCCESS on error.

oSLSIP_API SLresult SLSipResponseGetReasonPhrase(SLSipResponse *response, const SLchar** value)
Purpose: Return the SIP reason phrase for the response.

Parameters:
response - [in] The SIP response structure
value - [out] string containing the reason phrase. The string should be copied if required after the response gets out of scope.
Returns:
SL_SUCCESS if the phrase was returned, a value smaller than SL_SUCCESS if the phrase could not be returned.

oSLSIP_API SLresult SLSipRequestGetMethod(SLSipRequest *request, const SLchar **method)
Purpose: Return the SIP method contained in the SIP request

Parameters:
request - [in] The SIP request structure
method - [out] pointer to a string containing the request method. The * string should be copied if required after the request is out of scope.
Returns:
SL_SUCCESS if the request method was retrieved, a value smaller than SL_SUCCESS if the object could not be created.

This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java

Copyright © 2000-2001 SpeechWorks International, Inc. 
This work may only be distributed under the terms of the SpeechWorks Open Document License v1.0