williamr@2: /* williamr@2: * Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: williamr@2: * Name : sipsubscribedialogassoc.h williamr@2: * Part of : SIP Client williamr@2: * Interface : SDK API, SIP Client API williamr@2: * Version : 1.0 williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: williamr@2: #ifndef CSIPSUBSCRIBEDIALOGASSOC_H williamr@2: #define CSIPSUBSCRIBEDIALOGASSOC_H williamr@2: williamr@2: // INCLUDES williamr@2: #include "sipdialogassocbase.h" williamr@2: williamr@2: // CONSTANTS williamr@2: williamr@2: // FORWARD DECLARATIONS williamr@2: class CUri8; williamr@2: class CSIPToHeader; williamr@2: class CSIPFromHeader; williamr@2: class CSIPContactHeader; williamr@2: class CSIPEventHeader; williamr@2: class CSIPMessageElements; williamr@2: class MSIPRegistrationContext; williamr@2: class CSIPConnection; williamr@2: williamr@2: // CLASS DECLARATION williamr@2: williamr@2: /** williamr@2: * @publishedAll williamr@2: * @released williamr@2: * williamr@2: * Class for managing SIP SUBSCRIBE dialog associations. williamr@2: * It provides services for creating, using and terminating SIP SUBSCRIBE williamr@2: * dialog associations. The client can have multiple SUBSRIBE dialog williamr@2: * associations per same SIP dialog. williamr@2: * Implementation handles SUBSCRIBE on the dialog level defined by Call-Id, williamr@2: * local and remote tags; "Event" header semantics are client's responsibility williamr@2: * williamr@2: * @lib sipclient.lib williamr@2: */ williamr@2: class CSIPSubscribeDialogAssoc : public CSIPDialogAssocBase williamr@2: { williamr@2: public: // Constructors and destructor williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * Should be used if response to the SIP request to be sent williamr@2: * will create a SIP dialog association. williamr@2: * @pre aEvent != 0 williamr@2: * @param aDialog a dialog to be associated with williamr@2: * @param aEvent an event to subscribe to; the ownership is transferred williamr@2: * @return New object; the ownership is transferred williamr@2: * @leave KErrArgument if aEvent == 0 williamr@2: * @leave KErrSIPResourceNotAvailable if a required SIP Client API williamr@2: * object has been deleted williamr@2: */ williamr@2: IMPORT_C static CSIPSubscribeDialogAssoc* williamr@2: NewL(CSIPDialog& aDialog, williamr@2: CSIPEventHeader* aEvent); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * Must be used if response to the SIP request to be sent williamr@2: * will create a SIP dialog association. williamr@2: * @param aDialog a dialog to be associated with williamr@2: * @param aEvent an event to subscribe to; the ownership is transferred williamr@2: * @return New object, ownership is transferred williamr@2: * @leave KErrArgument if aEvent == 0 williamr@2: * @leave KErrSIPResourceNotAvailable if a required SIP Client API williamr@2: * object has been deleted williamr@2: */ williamr@2: IMPORT_C static CSIPSubscribeDialogAssoc* williamr@2: NewLC(CSIPDialog& aDialog, williamr@2: CSIPEventHeader* aEvent); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor williamr@2: * @pre aFrom != 0 williamr@2: * @pre aRemoteUri != 0 williamr@2: * @pre aEvent != 0 williamr@2: * The user of the class must not define tags in From-header and williamr@2: * To-header. williamr@2: * @param aConnection a SIP connection to be used with williamr@2: * dialog association williamr@2: * @param aFrom originator's address; the ownership is transfered williamr@2: * @param aRemoteUri a remote target URI that identifies a resource that williamr@2: * the request is addressed to. williamr@2: * @param aEvent an event to subscribe to; the ownership is transferred williamr@2: * @param aTo logical recipient's address; if not defined williamr@2: * the remote target uri will be used for To-header williamr@2: * construction; the ownership is transfered williamr@2: * @param aContact a contact to be used in dialog creation. Must be williamr@2: * given only if user intends to re-direct future requests; williamr@2: * the ownership is transfered williamr@2: * @return New object; the ownership is transferred. williamr@2: * @leave KErrArgument if aFrom == 0, aRemoteUri == 0 or aEvent == 0 williamr@2: * @leave KErrSIPResourceNotAvailable if a required SIP Client API williamr@2: * object has been deleted williamr@2: */ williamr@2: IMPORT_C static CSIPSubscribeDialogAssoc* williamr@2: NewL(CSIPConnection& aConnection, williamr@2: CSIPFromHeader* aFrom, williamr@2: CUri8* aRemoteUri, williamr@2: CSIPEventHeader* aEvent, williamr@2: CSIPToHeader* aTo=0, williamr@2: CSIPContactHeader* aContact=0); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor williamr@2: * @pre aFrom != 0 williamr@2: * @pre aRemoteUri != 0 williamr@2: * @pre aEvent != 0 williamr@2: * The user of the class must not define tags in From-header and williamr@2: * To-header. williamr@2: * @param aConnection a SIP connection to be used with williamr@2: * dialog association williamr@2: * @param aFrom originator's address; the ownership is transfered williamr@2: * @param aRemoteUri a remote target URI that identifies a resource that williamr@2: * the request is addressed to. williamr@2: * @param aEvent an event to subscribe to; the ownership is transferred williamr@2: * @param aTo logical recipient's address; if not defined williamr@2: * the remote target uri will be used for To-header williamr@2: * construction; the ownership is transfered williamr@2: * @param aContact a contact to be used in dialog creation. Must be williamr@2: * given only if user intends to re-direct future requests; williamr@2: * the ownership is transfered williamr@2: * @return New object; the ownership is transferred. williamr@2: * @leave KErrArgument if aFrom == 0, aRemoteUri == 0 or aEvent == 0 williamr@2: * @leave KErrSIPResourceNotAvailable if a required SIP Client API williamr@2: * object has been deleted williamr@2: */ williamr@2: IMPORT_C static CSIPSubscribeDialogAssoc* williamr@2: NewLC(CSIPConnection& aConnection, williamr@2: CSIPFromHeader* aFrom, williamr@2: CUri8* aRemoteUri, williamr@2: CSIPEventHeader* aEvent, williamr@2: CSIPToHeader* aTo =0, williamr@2: CSIPContactHeader* aContact=0); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor williamr@2: * @pre aRemoteUri != 0 williamr@2: * @pre aEvent != 0 williamr@2: * The user of the class must not define tags in From-header williamr@2: * and To-header. williamr@2: * @pre aContext.IsContextActive()==ETrue williamr@2: * @param aConnection a SIP connection to be used with williamr@2: * dialog association williamr@2: * @param aRemoteUri a remote target URI that identifies a resource that williamr@2: * the request is targeted to. williamr@2: * @param aContext used for selecting outbound williamr@2: * proxy and originator's address (AOR) and contact williamr@2: * @param aEvent an event to subscribe to; the ownership is transferred williamr@2: * @param aFrom originator's address. If not defined it will be williamr@2: * constructed using registration context (User's AOR); williamr@2: * the ownership is transfered williamr@2: * @param aTo logical recipient's address; if not defined williamr@2: * the remote target uri will be used for To-header williamr@2: * construction; the ownership is transfered williamr@2: * @param aContact a contact to be used in dialog creation. Must be williamr@2: * given only if user intends to re-direct future requests; williamr@2: * the ownership is transfered williamr@2: * @return New object; the ownership is transferred. williamr@2: * @leave KErrArgument if aRemoteUri == 0 or aEvent == 0 williamr@2: * @leave KErrSIPInvalidRegistrationState williamr@2: * if aContext.IsContextActive()==EFalse williamr@2: * @leave KErrSIPResourceNotAvailable if a required SIP Client API williamr@2: * object has been deleted williamr@2: */ williamr@2: IMPORT_C static CSIPSubscribeDialogAssoc* williamr@2: NewL(CSIPConnection& aConnection, williamr@2: CUri8* aRemoteUri, williamr@2: const MSIPRegistrationContext& aContext, williamr@2: CSIPEventHeader* aEvent, williamr@2: CSIPFromHeader* aFrom = 0, williamr@2: CSIPToHeader* aTo = 0, williamr@2: CSIPContactHeader* aContact = 0); williamr@2: williamr@2: /** williamr@2: * Two-phased constructor williamr@2: * @pre aRemoteUri != 0 williamr@2: * @pre aEvent != 0 williamr@2: * The user of the class must not define tags in From-header williamr@2: * and To-header. williamr@2: * @pre aContext.IsContextActive()==ETrue williamr@2: * @param aConnection a SIP connection to be used with williamr@2: * dialog association williamr@2: * @param aRemoteUri a remote target URI that identifies a resource that williamr@2: * the request is targeted to. williamr@2: * @param aContext used for selecting outbound williamr@2: * proxy and originator's address (AOR) and contact williamr@2: * @param aEvent an event to subscribe to; the ownership is transferred williamr@2: * @param aFrom originator's address. If not defined it will be williamr@2: * constructed using registration context (User's AOR); williamr@2: * the ownership is transfered williamr@2: * @param aTo logical recipient's address; if not defined williamr@2: * the remote target uri will be used for To-header williamr@2: * construction; the ownership is transfered williamr@2: * @param aContact a contact to be used in dialog creation. Must be williamr@2: * given only if user intends to re-direct future requests; williamr@2: * the ownership is transfered williamr@2: * @return New object; the ownership is transferred. williamr@2: * @leave KErrArgument if aRemoteUri == 0 or aEvent == 0 williamr@2: * @leave KErrSIPInvalidRegistrationState williamr@2: * if aContext.IsContextActive()==EFalse williamr@2: * @leave KErrSIPResourceNotAvailable if a required SIP Client API williamr@2: * object has been deleted williamr@2: */ williamr@2: IMPORT_C static CSIPSubscribeDialogAssoc* williamr@2: NewLC(CSIPConnection& aConnection, williamr@2: CUri8* aRemoteUri, williamr@2: const MSIPRegistrationContext& aContext, williamr@2: CSIPEventHeader* aEvent, williamr@2: CSIPFromHeader* aFrom = 0, williamr@2: CSIPToHeader* aTo = 0, williamr@2: CSIPContactHeader* aContact = 0); williamr@2: williamr@2: /** williamr@2: * Destructor williamr@2: */ williamr@2: IMPORT_C ~CSIPSubscribeDialogAssoc(); williamr@2: williamr@2: public: //New functions williamr@2: /** williamr@2: * Creates SUBSCRIBE and sends it to the remote target. williamr@2: * 101-199 or 2xx response to SUBSCRIBE will create a dialog association williamr@2: * in case of the first SUBSCRIBE request within this dialog. williamr@2: * Client must not provide Event-header in the optional message headers. williamr@2: * williamr@2: * @pre Dialog().Connection().State()==EActive williamr@2: * @pre Dialog().State()==CSIPDialog::EInit || williamr@2: * Dialog().State()==CSIPDialog::EConfirmed williamr@2: * @param aElements optional SIP message headers and body. Ownership is williamr@2: * transferred. williamr@2: * @param aRefresh if set the transaction will be refreshed at given williamr@2: * interval. Interval must be defined by including williamr@2: * Expires-header. Ownership is transferred. williamr@2: * @return SUBSCRIBE SIP transaction. Ownership is transferred. williamr@2: * @leave KErrSIPInvalidDialogState if Dialog().State() is incorrect williamr@2: * @capability NetworkServices williamr@2: */ williamr@2: IMPORT_C CSIPClientTransaction* williamr@2: SendSubscribeL(CSIPMessageElements* aElements=0, williamr@2: CSIPRefresh* aRefresh=0); williamr@2: williamr@2: /** williamr@2: * Updates the subscription. Note that update can be done when 2xx williamr@2: * response is received to the initial SUBSCRIBE or to update. williamr@2: * Client must not provide Event-header in the optional message headers. williamr@2: * @pre aElements != 0 williamr@2: * @pre Dialog().Connection().State()==EActive williamr@2: * Dialog().State()==CSIPDialog::EConfirmed williamr@2: * @param aElements contains user SIP headers and content; the ownership williamr@2: * is transferred williamr@2: * @return SUBSCRIBE SIP client transaction; the ownership is transferred williamr@2: * @leave KErrArgument if aElements == 0 or aElements contain williamr@2: * Event-header williamr@2: * @leave KErrSIPInvalidDialogState if Dialog().State() is incorrect williamr@2: * @capability NetworkServices williamr@2: */ williamr@2: IMPORT_C CSIPClientTransaction* UpdateL(CSIPMessageElements* aElements); williamr@2: williamr@2: /** williamr@2: * Creates (un)SUBSCRIBE and sends it to the remote target. williamr@2: * Possible associated refresh will be terminated as well. williamr@2: * Client must not provide Event-header in the optional message headers. williamr@2: * @pre Dialog().Connection().State()==EActive williamr@2: * @pre Dialog().State()==CSIPDialog::EConfirmed williamr@2: * @param aElements optional SIP message headers and body. Ownership is williamr@2: * transferred. williamr@2: * @return SUBSCRIBE SIP transaction. Ownership is transferred. williamr@2: * @leave KErrSIPInvalidDialogState if Dialog().State() is incorrect williamr@2: * @capability NetworkServices williamr@2: */ williamr@2: IMPORT_C CSIPClientTransaction* williamr@2: SendUnsubscribeL(CSIPMessageElements* aElements=0); williamr@2: williamr@2: /** williamr@2: * Gets associated refresh in case the user has requested williamr@2: * the refresh of the SIP subscription. williamr@2: * Note that refreshed SUBSCRIBE dialog association cannot be williamr@2: * terminated nor updated using the returned object. williamr@2: * @return Associated refresh or 0 pointer if the user has not requested williamr@2: * a refresh. Ownership is not transferred. williamr@2: */ williamr@2: IMPORT_C const CSIPRefresh* SIPRefresh() const; williamr@2: williamr@2: /** williamr@2: * Gets an event to which the subscription is done williamr@2: * @return an event williamr@2: */ williamr@2: IMPORT_C const CSIPEventHeader& Event() const; williamr@2: williamr@2: public: // New functions, for internal use williamr@2: williamr@2: /** williamr@2: * @internalComponent williamr@2: */ williamr@2: CSIPRefresh* FindRefresh(TUint32 aRefreshId); williamr@2: williamr@2: static CSIPSubscribeDialogAssoc* NewLC(CSIPConnection& aConnection, williamr@2: CUri8* aRemoteUri, williamr@2: CSIPEventHeader* aEvent, williamr@2: CSIPFromHeader* aFrom, williamr@2: CSIPToHeader* aTo, williamr@2: CSIPContactHeader* aContact, williamr@2: const MSIPRegistrationContext* aContext); williamr@2: williamr@2: void ConnectionLost(); williamr@2: williamr@2: CSIPClientTransaction* williamr@2: DoSendSubscribeL(CSIPMessageElements* aElements, williamr@2: CSIPRefresh* aRefresh, williamr@2: TBool aWithinDialog); williamr@2: williamr@2: CSIPClientTransaction* williamr@2: DoSendUnsubscribeL(CSIPMessageElements* aElements); williamr@2: williamr@2: /** williamr@2: * @internalComponent williamr@2: */ williamr@2: void DeletingRefresh(CSIPRefresh& aRefresh, TUint32 aRefreshId); williamr@2: williamr@2: private: // Constructors williamr@2: CSIPSubscribeDialogAssoc(); williamr@2: williamr@2: private: // Data williamr@2: //If the subscription is refreshed, this is the used CSIPRefresh williamr@2: //instance, otherwise this is NULL. CSIPSubscribeDialogAssoc owns this. williamr@2: CSIPRefresh* iRefresh; williamr@2: williamr@2: CSIPEventHeader* iEvent; williamr@2: williamr@2: private: // For testing purposes williamr@4: #ifdef CPPUNIT_TEST williamr@4: friend class CSIP_Test; williamr@4: friend class CSIPSubscribeDialogAssoc_Test; williamr@4: #endif williamr@2: }; williamr@2: williamr@2: #endif