Class CSIPSubscribeDialogAssoc

class CSIPSubscribeDialogAssoc : public CSIPDialogAssocBase;

Description

Class for managing SIP SUBSCRIBE dialog associations. It provides services for creating, using and terminating SIP SUBSCRIBE dialog associations. The client can have multiple SUBSRIBE dialog associations per same SIP dialog. Implementation handles SUBSCRIBE on the dialog level defined by Call-Id, local and remote tags; "Event" header semantics are client's responsibility

sipclient.lib

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CSIPDialogAssocBase - Base class for SIP dialog associations

• CSIPSubscribeDialogAssoc - Class for managing SIP SUBSCRIBE dialog associations

Members

Defined in CSIPSubscribeDialogAssoc:
Event(), NewL(), NewL(), NewL(), NewLC(), NewLC(), NewLC(), SIPRefresh(), SendSubscribeL(), SendUnsubscribeL(), UpdateL(), ~CSIPSubscribeDialogAssoc()

Inherited from CBase:
Delete(), Extension_(), operator new()

Inherited from CSIPDialogAssocBase:
Dialog(), IsNonTargetRefreshRequest(), SendNonTargetRefreshRequestL(), Type()

static IMPORT_C CSIPSubscribeDialogAssoc *NewL(CSIPDialog &aDialog, CSIPEventHeader *aEvent);

Pre-Condition

aEvent != 0

Description

Two-phased constructor. Should be used if response to the SIP request to be sent will create a SIP dialog association.

Parameters

CSIPDialog &aDialog a dialog to be associated with CSIPEventHeader *aEvent an event to subscribe to; the ownership is transferred

Return value

CSIPSubscribeDialogAssoc * New object; the ownership is transferred

Leave codes

KErrArgument if aEvent == 0 KErrSIPResourceNotAvailable if a required SIP Client API object has been deleted

static IMPORT_C CSIPSubscribeDialogAssoc *NewLC(CSIPDialog &aDialog, CSIPEventHeader *aEvent);

Description

Two-phased constructor. Must be used if response to the SIP request to be sent will create a SIP dialog association.

Parameters

CSIPDialog &aDialog a dialog to be associated with CSIPEventHeader *aEvent an event to subscribe to; the ownership is transferred

Return value

CSIPSubscribeDialogAssoc * New object, ownership is transferred

Leave codes

KErrArgument if aEvent == 0 KErrSIPResourceNotAvailable if a required SIP Client API object has been deleted

static IMPORT_C CSIPSubscribeDialogAssoc *NewL(CSIPConnection &aConnection, CSIPFromHeader *aFrom, CUri8 *aRemoteUri, CSIPEventHeader *aEvent, CSIPToHeader *aTo=0, CSIPContactHeader *aContact=0);

Pre-Condition

aFrom != 0

aRemoteUri != 0

aEvent != 0 The user of the class must not define tags in From-header and To-header.

Description

Two-phased constructor

Parameters

CSIPConnection &aConnection a SIP connection to be used with dialog association CSIPFromHeader *aFrom originator's address; the ownership is transfered CUri8 *aRemoteUri a remote target URI that identifies a resource that the request is addressed to. CSIPEventHeader *aEvent an event to subscribe to; the ownership is transferred CSIPToHeader *aTo logical recipient's address; if not defined the remote target uri will be used for To-header construction; the ownership is transfered CSIPContactHeader *aContact a contact to be used in dialog creation. Must be given only if user intends to re-direct future requests; the ownership is transfered

Return value

CSIPSubscribeDialogAssoc * New object; the ownership is transferred.

Leave codes

KErrArgument if aFrom == 0, aRemoteUri == 0 or aEvent == 0 KErrSIPResourceNotAvailable if a required SIP Client API object has been deleted

static IMPORT_C CSIPSubscribeDialogAssoc *NewLC(CSIPConnection &aConnection, CSIPFromHeader *aFrom, CUri8 *aRemoteUri, CSIPEventHeader *aEvent, CSIPToHeader *aTo=0, CSIPContactHeader *aContact=0);

Pre-Condition

aFrom != 0

aRemoteUri != 0

aEvent != 0 The user of the class must not define tags in From-header and To-header.

Description

Two-phased constructor

Parameters

CSIPConnection &aConnection a SIP connection to be used with dialog association CSIPFromHeader *aFrom originator's address; the ownership is transfered CUri8 *aRemoteUri a remote target URI that identifies a resource that the request is addressed to. CSIPEventHeader *aEvent an event to subscribe to; the ownership is transferred CSIPToHeader *aTo logical recipient's address; if not defined the remote target uri will be used for To-header construction; the ownership is transfered CSIPContactHeader *aContact a contact to be used in dialog creation. Must be given only if user intends to re-direct future requests; the ownership is transfered

Return value

CSIPSubscribeDialogAssoc * New object; the ownership is transferred.

Leave codes

KErrArgument if aFrom == 0, aRemoteUri == 0 or aEvent == 0 KErrSIPResourceNotAvailable if a required SIP Client API object has been deleted

static IMPORT_C CSIPSubscribeDialogAssoc *NewL(CSIPConnection &aConnection, CUri8 *aRemoteUri, const MSIPRegistrationContext &aContext, CSIPEventHeader *aEvent, CSIPFromHeader *aFrom=0, CSIPToHeader *aTo=0, CSIPContactHeader *aContact=0);

Pre-Condition

aRemoteUri != 0

aEvent != 0 The user of the class must not define tags in From-header and To-header.

aContext.IsContextActive()==ETrue

Description

Two-phased constructor

Parameters

CSIPConnection &aConnection a SIP connection to be used with dialog association CUri8 *aRemoteUri a remote target URI that identifies a resource that the request is targeted to. const MSIPRegistrationContext &aContext used for selecting outbound proxy and originator's address (AOR) and contact CSIPEventHeader *aEvent an event to subscribe to; the ownership is transferred CSIPFromHeader *aFrom originator's address. If not defined it will be constructed using registration context (User's AOR); the ownership is transfered CSIPToHeader *aTo logical recipient's address; if not defined the remote target uri will be used for To-header construction; the ownership is transfered CSIPContactHeader *aContact a contact to be used in dialog creation. Must be given only if user intends to re-direct future requests; the ownership is transfered

Return value

CSIPSubscribeDialogAssoc * New object; the ownership is transferred.

Leave codes

KErrArgument if aRemoteUri == 0 or aEvent == 0 KErrSIPInvalidRegistrationState if aContext.IsContextActive()==EFalse KErrSIPResourceNotAvailable if a required SIP Client API object has been deleted

static IMPORT_C CSIPSubscribeDialogAssoc *NewLC(CSIPConnection &aConnection, CUri8 *aRemoteUri, const MSIPRegistrationContext &aContext, CSIPEventHeader *aEvent, CSIPFromHeader *aFrom=0, CSIPToHeader *aTo=0, CSIPContactHeader *aContact=0);

Pre-Condition

aRemoteUri != 0

aEvent != 0 The user of the class must not define tags in From-header and To-header.

aContext.IsContextActive()==ETrue

Description

Two-phased constructor

Parameters

CSIPConnection &aConnection a SIP connection to be used with dialog association CUri8 *aRemoteUri a remote target URI that identifies a resource that the request is targeted to. const MSIPRegistrationContext &aContext used for selecting outbound proxy and originator's address (AOR) and contact CSIPEventHeader *aEvent an event to subscribe to; the ownership is transferred CSIPFromHeader *aFrom originator's address. If not defined it will be constructed using registration context (User's AOR); the ownership is transfered CSIPToHeader *aTo logical recipient's address; if not defined the remote target uri will be used for To-header construction; the ownership is transfered CSIPContactHeader *aContact a contact to be used in dialog creation. Must be given only if user intends to re-direct future requests; the ownership is transfered

Return value

CSIPSubscribeDialogAssoc * New object; the ownership is transferred.

Leave codes

KErrArgument if aRemoteUri == 0 or aEvent == 0 KErrSIPInvalidRegistrationState if aContext.IsContextActive()==EFalse KErrSIPResourceNotAvailable if a required SIP Client API object has been deleted

IMPORT_C ~CSIPSubscribeDialogAssoc();

Description

Destructor

Capability:

NetworkServices

IMPORT_C CSIPClientTransaction *SendSubscribeL(CSIPMessageElements *aElements=0, CSIPRefresh *aRefresh=0);

Pre-Condition

Dialog().Connection().State()==EActive

Dialog().State()==CSIPDialogEInit || Dialog().State()==CSIPDialog::EConfirmed

Description

Creates SUBSCRIBE and sends it to the remote target. 101-199 or 2xx response to SUBSCRIBE will create a dialog association in case of the first SUBSCRIBE request within this dialog. Client must not provide Event-header in the optional message headers.

Parameters

CSIPMessageElements *aElements optional SIP message headers and body. Ownership is transferred. CSIPRefresh *aRefresh if set the transaction will be refreshed at given interval. Interval must be defined by including Expires-header. Ownership is transferred.

Return value

CSIPClientTransaction * SUBSCRIBE SIP transaction. Ownership is transferred.

Leave codes

KErrSIPInvalidDialogState if Dialog().State() is incorrect

Capability:

NetworkServices

IMPORT_C CSIPClientTransaction *UpdateL(CSIPMessageElements *aElements);

Pre-Condition

aElements != 0

Dialog().Connection().State()==EActive Dialog().State()==CSIPDialog::EConfirmed

Description

Updates the subscription. Note that update can be done when 2xx response is received to the initial SUBSCRIBE or to update. Client must not provide Event-header in the optional message headers.

Parameters

CSIPMessageElements *aElements contains user SIP headers and content; the ownership is transferred

Return value

CSIPClientTransaction * SUBSCRIBE SIP client transaction; the ownership is transferred

Leave codes

KErrArgument if aElements == 0 or aElements contain Event-header KErrSIPInvalidDialogState if Dialog().State() is incorrect

Capability:

NetworkServices

IMPORT_C CSIPClientTransaction *SendUnsubscribeL(CSIPMessageElements *aElements=0);

Pre-Condition

Dialog().Connection().State()==EActive

Dialog().State()==CSIPDialog::EConfirmed

Description

Creates (un)SUBSCRIBE and sends it to the remote target. Possible associated refresh will be terminated as well. Client must not provide Event-header in the optional message headers.

Parameters

CSIPMessageElements *aElements optional SIP message headers and body. Ownership is transferred.

Return value

CSIPClientTransaction * SUBSCRIBE SIP transaction. Ownership is transferred.

Leave codes

KErrSIPInvalidDialogState if Dialog().State() is incorrect

IMPORT_C const CSIPRefresh *SIPRefresh() const;

Description

Gets associated refresh in case the user has requested the refresh of the SIP subscription. Note that refreshed SUBSCRIBE dialog association cannot be terminated nor updated using the returned object.

Return value

const CSIPRefresh * Associated refresh or 0 pointer if the user has not requested a refresh. Ownership is not transferred.

IMPORT_C const CSIPEventHeader &Event() const;

Description

Gets an event to which the subscription is done

Return value

const CSIPEventHeader & an event