Overview

The SIP Client API manages the multimedia sessions, subscribes to events, -and sends SIP messages. It also provides access to the basic services of the -SIP stack such as:

Sending and receiving -of SIP messages
Creating registrations
Forming and tearing -down dialogs initiated by INVITE, REFER and SUBSCRIBE requests

Architectural -relationships

The SIP Client API uses the client-server mechanism -to interact with the SIP stack. This means more than one client can use the -SIP stack at the same time. The calls to the SIP Client API are synchronous. -The SIP Client API implements a set of callback functions to pass the events -back to the application.

Capability information

The -following table describes the capabilities required to use the SIP Client -API and the conditions in which they are required:

- - - -Capability -Reason needed - - - - -

NetworkServices

to send or receive SIP messages

- - -

WriteDeviceData

to create an instance of the CSIP class

- - -

NetworkControl

Location

ReadDeviceData

to use the function CSIPConnection::SetOptL()

- - - -

Extending the API

SIP Client API cannot be extended.

SIP Client -API class structure

CSIP, MSIPObserver, CSIPConnection and MSIPConnectionObserver
Registration services
SIP dialog associations
Requests sent to, and received from, the network
SIP message related classes
Automatically refreshing a SIP request
Managing HTTP digest security settings

CSIP, MSIPObserver, -CSIPConnection and MSIPConnectionObserver

- -

An application creates a single instance of the CSIP class, -and implements the callback functions defined by MSIPObserver. -The CSIP uses the MSIPObserver functions. -The CSIP class asks the supported security mechanisms and -determines whether a CSIPConnection object exists for a -given IAP.

The CSIP object creates an instance -of CSIPConnection that allows you to send standalone SIP -requests and ask for the state of the network connection. Responses are received -through the MSIPConnectionObserver interface that defines -a set of callback functions that an application must implement.

An -application can have many CSIPConnection objects, but each -of them must have a different IAP.

Registration -services

- -

An existing CSIPConnection is required to create -an instance of CSIPRegistrationBinding. The CSIPRegistrationBinding class -provides services for registration, updating the registration, and deregistration. -This class also provides instructions to the SIP stack to automatically refresh -the registration, and to query and set the outbound proxy used by the registration.

SIP dialog -associations

- -

CSIPDialogAssocBase is the base class for SIP -dialog associations, such as CSIPInviteDialogAssoc, CSIPSubscribeDialogAssoc, CSIPReferDialogAssoc and CSIPNotifyDialogAssoc. The CSIPDialogAssocBase class -is used to obtain the associated SIP dialog, for the associated CSIPDialog instance, -and for sending a non-target Refresh request within the dialog.

Note: The -SIP Client API creates the CSIPDialog instance, it cannot -be created by the application.

If any of the CSIPInviteDialogAssoc, CSIPSubscribeDialogAssoc, CSIPReferDialogAssoc and CSIPNotifyDialogAssoc objects -are associated, they are bound to an existing CSIPDialog object, -or they can be used to create a new CSIPDialog object.

Note:

CSIPInviteDialogAssoc allows -an application to initiate a dialog and to send INVITE,,PRACK,,ACK, UPDATE, and BYE requests related to the dialog.
CSIPSubscribeDialogAssoc allows -an application to subscribe to different events by sending SUBSCRIBE and UNSUBSCRIBE -requests. It also orders the SIP stack to automatically refresh the SUBSCRIBE -request.
CSIPReferDialogAssoc allows -an application to define and send REFER requests.
CSIPNotifyDialogAssoc allows -an application to define and send NOTIFY requests.

Sent and received -network requests

- -

When a SIP request is sent to the network, the SIP Client API implementation -creates a CSIPClientTransaction object and returns it to -the application. A CSIPClientTransaction object represents -the SIP transaction and consists of the SIP request and the SIP response. -After receiving a response, the application gets CSIPResponseElements from -the CSIPClientTransaction object. Note: Some client -transactions can also be cancelled or refreshed.

When a SIP request -is received from the network, it is passed to the application as a CSIPServerTransaction object. -The application gets CSIPRequestElements from the CSIPServerTransaction object. -A CSIPRequestElements object describes the kind of SIP request -received. After the application determines the type of response to send, it -uses the CSIPServerTransaction to send the responses.

CSIPTransactionBase is -the base class for CSIPClientTransaction and CSIPServerTransaction. -It provides the functions to obtain the current state of the transaction and -the transaction type. Some operations are only allowed when the transaction -is in a certain state. Note: The SIP Client API creates instances of CSIPClientTransaction and CSIPServerTransaction and they cannot be created by the application.

SIP -message related classes

- -

When a SIP request is sent to the network, the SIP Client API implementation -creates a CSIPClientTransaction object and returns it to -the application. A CSIPClientTransaction object represents -the SIP transaction and consists of the SIP request and the SIP response. -After receiving a response the application gets CSIPResponseElements from -the CSIPClientTransaction object. Note: Some client -transactions can be cancelled or refreshed.

When a SIP request is -received from the network, it is passed to the application as a CSIPServerTransaction object. -The application gets CSIPRequestElements from the CSIPServerTransaction object. -A CSIPRequestElements object describes the type of SIP request -received. After the application determines the type of response to send, it -uses the CSIPServerTransaction to send the responses.

CSIPTransactionBase is -the base class for CSIPClientTransaction and CSIPServerTransaction. -It provides functions to obtain the current state of the transaction and the -transaction type. Some operations are only allowed when the transaction is -in a certain state. Note: The SIP Client API creates instances of CSIPClientTransaction and CSIPServerTransaction and they cannot be created by the application.

Automatically -refreshing a SIP request

- -

The SIP stack automatically refreshes a SIP request using the CSIPRefresh object. REGISTER, SUBSCRIBE and a request outside the dialog are refreshed. After -sending a refresh request, the application queries the state of the refresh -from CSIPRefresh.

CSIPRefresh provides -functions for updating and terminating the refresh, for requests outside the -dialog. The CSIPRegistrationBinding and CSIPSubscribeDialogAssoc classes -are used to update and terminate a refreshed REGISTER or SUBSCRIBE.

Managing HTTP digest security -settings

- -

An application must create an instance of the CSIP class -to use CSIPHttpDigest. The CSIPHttpDigest class -manages HTTP digest security settings and contains only static functions.

Memory used

After -the CSIP and CSIPConnection objects -are created, most of the memory consumed is by CSIPMessageElements, CSIPRequestElements and CSIPResponseElements classes. CSIPTransactionBase holds the most recent SIP -response in a CSIPResponseElements object. When another -response is received, the previous CSIPResponseElements object -is deleted and a new one is created.

CSIPClientTransaction contains -a CSIPRequestElements object until the SIP request is transferred -to the server side of the SIP stack. CSIPServerTransaction contains -the SIP request as CSIPRequestElements. The application -owns the CSIPClientTransaction and CSIPServerTransaction objects. -When the transaction terminates, the application deletes these objects to -conserve memory.

A non-INVITE CSIPClientTransaction is -deleted when it has received a final response or when the ErrorOccured() callback -is called. A non-INVITE CSIPServerTransaction is -deleted after the application sends a final response.

The INVITE related -transactions are deleted if the ErrorOccured() callback function -is called. These transactions behave differently because of the presence of -an ACK.

When the application sends a 2xx response -to an INVITE related CSIPServerTransaction, -it enters the CSIPTransactionBase::ETerminated state and -it is deleted at this point. A new CSIPServerTransaction object -receives the ACK.

When the application sends an INVITE request -and the CSIPClientTransaction receives a 2xx response, the -transaction enters the CSIPTransactionBase::ETerminated state. -The associated CSIPClientTransaction must not be deleted -as it is required to send the ACK and also to receive the MSIPConnectionObserver::InviteCompleted() callback. -An INVITE related CSIPClientTransaction must -be deleted only after a MSIPConnectionObserver::InviteCompleted or MSIPConnectionObserver -::ErrorOccured event is received, or if the state of the associated CSIPConnection goes -to CSIPConnection::EInactive or CSIPConnection::EUnavailable.

+ + + + + +Overview +

The SIP Client API manages the multimedia sessions, subscribes to events, +and sends SIP messages. It also provides access to the basic services of the +SIP stack such as:

Sending and receiving +of SIP messages
Creating registrations
Forming and tearing +down dialogs initiated by INVITE, REFER and SUBSCRIBE requests

Architectural +relationships

The SIP Client API uses the client-server mechanism +to interact with the SIP stack. This means more than one client can use the +SIP stack at the same time. The calls to the SIP Client API are synchronous. +The SIP Client API implements a set of callback functions to pass the events +back to the application.

Capability information

The +following table describes the capabilities required to use the SIP Client +API and the conditions in which they are required:

+ + + +Capability +Reason needed + + + + +

NetworkServices

to send or receive SIP messages

+ + +

WriteDeviceData

to create an instance of the CSIP class

+ + +

NetworkControl

Location

ReadDeviceData

to use the function CSIPConnection::SetOptL()

+ + + +

Extending the API

SIP Client API cannot be extended.

SIP Client +API class structure

CSIP, MSIPObserver, CSIPConnection and MSIPConnectionObserver
Registration services
SIP dialog associations
Requests sent to, and received from, the network
SIP message related classes
Automatically refreshing a SIP request
Managing HTTP digest security settings

CSIP, MSIPObserver, +CSIPConnection and MSIPConnectionObserver

+ +

An application creates a single instance of the CSIP class, +and implements the callback functions defined by MSIPObserver. +The CSIP uses the MSIPObserver functions. +The CSIP class asks the supported security mechanisms and +determines whether a CSIPConnection object exists for a +given IAP.

The CSIP object creates an instance +of CSIPConnection that allows you to send standalone SIP +requests and ask for the state of the network connection. Responses are received +through the MSIPConnectionObserver interface that defines +a set of callback functions that an application must implement.

An +application can have many CSIPConnection objects, but each +of them must have a different IAP.

Registration +services

+ +

An existing CSIPConnection is required to create +an instance of CSIPRegistrationBinding. The CSIPRegistrationBinding class +provides services for registration, updating the registration, and deregistration. +This class also provides instructions to the SIP stack to automatically refresh +the registration, and to query and set the outbound proxy used by the registration.

SIP dialog +associations

+ +

CSIPDialogAssocBase is the base class for SIP +dialog associations, such as CSIPInviteDialogAssoc, CSIPSubscribeDialogAssoc, CSIPReferDialogAssoc and CSIPNotifyDialogAssoc. The CSIPDialogAssocBase class +is used to obtain the associated SIP dialog, for the associated CSIPDialog instance, +and for sending a non-target Refresh request within the dialog.

Note: The +SIP Client API creates the CSIPDialog instance, it cannot +be created by the application.

If any of the CSIPInviteDialogAssoc, CSIPSubscribeDialogAssoc, CSIPReferDialogAssoc and CSIPNotifyDialogAssoc objects +are associated, they are bound to an existing CSIPDialog object, +or they can be used to create a new CSIPDialog object.

Note:

CSIPInviteDialogAssoc allows +an application to initiate a dialog and to send INVITE,,PRACK,,ACK, UPDATE, and BYE requests related to the dialog.
CSIPSubscribeDialogAssoc allows +an application to subscribe to different events by sending SUBSCRIBE and UNSUBSCRIBE +requests. It also orders the SIP stack to automatically refresh the SUBSCRIBE +request.
CSIPReferDialogAssoc allows +an application to define and send REFER requests.
CSIPNotifyDialogAssoc allows +an application to define and send NOTIFY requests.

Sent and received +network requests

+ +

When a SIP request is sent to the network, the SIP Client API implementation +creates a CSIPClientTransaction object and returns it to +the application. A CSIPClientTransaction object represents +the SIP transaction and consists of the SIP request and the SIP response. +After receiving a response, the application gets CSIPResponseElements from +the CSIPClientTransaction object. Note: Some client +transactions can also be cancelled or refreshed.

When a SIP request +is received from the network, it is passed to the application as a CSIPServerTransaction object. +The application gets CSIPRequestElements from the CSIPServerTransaction object. +A CSIPRequestElements object describes the kind of SIP request +received. After the application determines the type of response to send, it +uses the CSIPServerTransaction to send the responses.

CSIPTransactionBase is +the base class for CSIPClientTransaction and CSIPServerTransaction. +It provides the functions to obtain the current state of the transaction and +the transaction type. Some operations are only allowed when the transaction +is in a certain state. Note: The SIP Client API creates instances of CSIPClientTransaction and CSIPServerTransaction and they cannot be created by the application.

SIP +message related classes

+ +

When a SIP request is sent to the network, the SIP Client API implementation +creates a CSIPClientTransaction object and returns it to +the application. A CSIPClientTransaction object represents +the SIP transaction and consists of the SIP request and the SIP response. +After receiving a response the application gets CSIPResponseElements from +the CSIPClientTransaction object. Note: Some client +transactions can be cancelled or refreshed.

When a SIP request is +received from the network, it is passed to the application as a CSIPServerTransaction object. +The application gets CSIPRequestElements from the CSIPServerTransaction object. +A CSIPRequestElements object describes the type of SIP request +received. After the application determines the type of response to send, it +uses the CSIPServerTransaction to send the responses.

CSIPTransactionBase is +the base class for CSIPClientTransaction and CSIPServerTransaction. +It provides functions to obtain the current state of the transaction and the +transaction type. Some operations are only allowed when the transaction is +in a certain state. Note: The SIP Client API creates instances of CSIPClientTransaction and CSIPServerTransaction and they cannot be created by the application.

Automatically +refreshing a SIP request

+ +

The SIP stack automatically refreshes a SIP request using the CSIPRefresh object. REGISTER, SUBSCRIBE and a request outside the dialog are refreshed. After +sending a refresh request, the application queries the state of the refresh +from CSIPRefresh.

CSIPRefresh provides +functions for updating and terminating the refresh, for requests outside the +dialog. The CSIPRegistrationBinding and CSIPSubscribeDialogAssoc classes +are used to update and terminate a refreshed REGISTER or SUBSCRIBE.

Managing HTTP digest security +settings

+ +

An application must create an instance of the CSIP class +to use CSIPHttpDigest. The CSIPHttpDigest class +manages HTTP digest security settings and contains only static functions.

Memory used

After +the CSIP and CSIPConnection objects +are created, most of the memory consumed is by CSIPMessageElements, CSIPRequestElements and CSIPResponseElements classes. CSIPTransactionBase holds the most recent SIP +response in a CSIPResponseElements object. When another +response is received, the previous CSIPResponseElements object +is deleted and a new one is created.

CSIPClientTransaction contains +a CSIPRequestElements object until the SIP request is transferred +to the server side of the SIP stack. CSIPServerTransaction contains +the SIP request as CSIPRequestElements. The application +owns the CSIPClientTransaction and CSIPServerTransaction objects. +When the transaction terminates, the application deletes these objects to +conserve memory.

A non-INVITE CSIPClientTransaction is +deleted when it has received a final response or when the ErrorOccured() callback +is called. A non-INVITE CSIPServerTransaction is +deleted after the application sends a final response.

The INVITE related +transactions are deleted if the ErrorOccured() callback function +is called. These transactions behave differently because of the presence of +an ACK.

When the application sends a 2xx response +to an INVITE related CSIPServerTransaction, +it enters the CSIPTransactionBase::ETerminated state and +it is deleted at this point. A new CSIPServerTransaction object +receives the ACK.

When the application sends an INVITE request +and the CSIPClientTransaction receives a 2xx response, the +transaction enters the CSIPTransactionBase::ETerminated state. +The associated CSIPClientTransaction must not be deleted +as it is required to send the ACK and also to receive the MSIPConnectionObserver::InviteCompleted() callback. +An INVITE related CSIPClientTransaction must +be deleted only after a MSIPConnectionObserver::InviteCompleted or MSIPConnectionObserver +::ErrorOccured event is received, or if the state of the associated CSIPConnection goes +to CSIPConnection::EInactive or CSIPConnection::EUnavailable.

\ No newline at end of file