diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/sipsubscribedialogassoc.h --- a/epoc32/include/sipsubscribedialogassoc.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/sipsubscribedialogassoc.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,354 @@ -sipsubscribedialogassoc.h +/* +* Copyright (c) 2005-2009 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +* which accompanies this distribution, and is available +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +* +* Initial Contributors: +* Nokia Corporation - initial contribution. +* +* Contributors: +* +* Description: +* Name : sipsubscribedialogassoc.h +* Part of : SIP Client +* Interface : SDK API, SIP Client API +* Version : 1.0 +* +*/ + + + +#ifndef CSIPSUBSCRIBEDIALOGASSOC_H +#define CSIPSUBSCRIBEDIALOGASSOC_H + +// INCLUDES +#include "sipdialogassocbase.h" + +// CONSTANTS + +// FORWARD DECLARATIONS +class CUri8; +class CSIPToHeader; +class CSIPFromHeader; +class CSIPContactHeader; +class CSIPEventHeader; +class CSIPMessageElements; +class MSIPRegistrationContext; +class CSIPConnection; + +// CLASS DECLARATION + +/** +* @publishedAll +* @released +* +* 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 +* +* @lib sipclient.lib +*/ +class CSIPSubscribeDialogAssoc : public CSIPDialogAssocBase + { + public: // Constructors and destructor + /** + * Two-phased constructor. + * Should be used if response to the SIP request to be sent + * will create a SIP dialog association. + * @pre aEvent != 0 + * @param aDialog a dialog to be associated with + * @param aEvent an event to subscribe to; the ownership is transferred + * @return New object; the ownership is transferred + * @leave KErrArgument if aEvent == 0 + * @leave KErrSIPResourceNotAvailable if a required SIP Client API + * object has been deleted + */ + IMPORT_C static CSIPSubscribeDialogAssoc* + NewL(CSIPDialog& aDialog, + CSIPEventHeader* aEvent); + + /** + * Two-phased constructor. + * Must be used if response to the SIP request to be sent + * will create a SIP dialog association. + * @param aDialog a dialog to be associated with + * @param aEvent an event to subscribe to; the ownership is transferred + * @return New object, ownership is transferred + * @leave KErrArgument if aEvent == 0 + * @leave KErrSIPResourceNotAvailable if a required SIP Client API + * object has been deleted + */ + IMPORT_C static CSIPSubscribeDialogAssoc* + NewLC(CSIPDialog& aDialog, + CSIPEventHeader* aEvent); + + /** + * Two-phased constructor + * @pre aFrom != 0 + * @pre aRemoteUri != 0 + * @pre aEvent != 0 + * The user of the class must not define tags in From-header and + * To-header. + * @param aConnection a SIP connection to be used with + * dialog association + * @param aFrom originator's address; the ownership is transfered + * @param aRemoteUri a remote target URI that identifies a resource that + * the request is addressed to. + * @param aEvent an event to subscribe to; the ownership is transferred + * @param aTo logical recipient's address; if not defined + * the remote target uri will be used for To-header + * construction; the ownership is transfered + * @param 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 New object; the ownership is transferred. + * @leave KErrArgument if aFrom == 0, aRemoteUri == 0 or aEvent == 0 + * @leave KErrSIPResourceNotAvailable if a required SIP Client API + * object has been deleted + */ + IMPORT_C static CSIPSubscribeDialogAssoc* + NewL(CSIPConnection& aConnection, + CSIPFromHeader* aFrom, + CUri8* aRemoteUri, + CSIPEventHeader* aEvent, + CSIPToHeader* aTo=0, + CSIPContactHeader* aContact=0); + + /** + * Two-phased constructor + * @pre aFrom != 0 + * @pre aRemoteUri != 0 + * @pre aEvent != 0 + * The user of the class must not define tags in From-header and + * To-header. + * @param aConnection a SIP connection to be used with + * dialog association + * @param aFrom originator's address; the ownership is transfered + * @param aRemoteUri a remote target URI that identifies a resource that + * the request is addressed to. + * @param aEvent an event to subscribe to; the ownership is transferred + * @param aTo logical recipient's address; if not defined + * the remote target uri will be used for To-header + * construction; the ownership is transfered + * @param 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 New object; the ownership is transferred. + * @leave KErrArgument if aFrom == 0, aRemoteUri == 0 or aEvent == 0 + * @leave KErrSIPResourceNotAvailable if a required SIP Client API + * object has been deleted + */ + IMPORT_C static CSIPSubscribeDialogAssoc* + NewLC(CSIPConnection& aConnection, + CSIPFromHeader* aFrom, + CUri8* aRemoteUri, + CSIPEventHeader* aEvent, + CSIPToHeader* aTo =0, + CSIPContactHeader* aContact=0); + + /** + * Two-phased constructor + * @pre aRemoteUri != 0 + * @pre aEvent != 0 + * The user of the class must not define tags in From-header + * and To-header. + * @pre aContext.IsContextActive()==ETrue + * @param aConnection a SIP connection to be used with + * dialog association + * @param aRemoteUri a remote target URI that identifies a resource that + * the request is targeted to. + * @param aContext used for selecting outbound + * proxy and originator's address (AOR) and contact + * @param aEvent an event to subscribe to; the ownership is transferred + * @param aFrom originator's address. If not defined it will be + * constructed using registration context (User's AOR); + * the ownership is transfered + * @param aTo logical recipient's address; if not defined + * the remote target uri will be used for To-header + * construction; the ownership is transfered + * @param 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 New object; the ownership is transferred. + * @leave KErrArgument if aRemoteUri == 0 or aEvent == 0 + * @leave KErrSIPInvalidRegistrationState + * if aContext.IsContextActive()==EFalse + * @leave KErrSIPResourceNotAvailable if a required SIP Client API + * object has been deleted + */ + IMPORT_C static CSIPSubscribeDialogAssoc* + NewL(CSIPConnection& aConnection, + CUri8* aRemoteUri, + const MSIPRegistrationContext& aContext, + CSIPEventHeader* aEvent, + CSIPFromHeader* aFrom = 0, + CSIPToHeader* aTo = 0, + CSIPContactHeader* aContact = 0); + + /** + * Two-phased constructor + * @pre aRemoteUri != 0 + * @pre aEvent != 0 + * The user of the class must not define tags in From-header + * and To-header. + * @pre aContext.IsContextActive()==ETrue + * @param aConnection a SIP connection to be used with + * dialog association + * @param aRemoteUri a remote target URI that identifies a resource that + * the request is targeted to. + * @param aContext used for selecting outbound + * proxy and originator's address (AOR) and contact + * @param aEvent an event to subscribe to; the ownership is transferred + * @param aFrom originator's address. If not defined it will be + * constructed using registration context (User's AOR); + * the ownership is transfered + * @param aTo logical recipient's address; if not defined + * the remote target uri will be used for To-header + * construction; the ownership is transfered + * @param 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 New object; the ownership is transferred. + * @leave KErrArgument if aRemoteUri == 0 or aEvent == 0 + * @leave KErrSIPInvalidRegistrationState + * if aContext.IsContextActive()==EFalse + * @leave KErrSIPResourceNotAvailable if a required SIP Client API + * object has been deleted + */ + IMPORT_C static CSIPSubscribeDialogAssoc* + NewLC(CSIPConnection& aConnection, + CUri8* aRemoteUri, + const MSIPRegistrationContext& aContext, + CSIPEventHeader* aEvent, + CSIPFromHeader* aFrom = 0, + CSIPToHeader* aTo = 0, + CSIPContactHeader* aContact = 0); + + /** + * Destructor + */ + IMPORT_C ~CSIPSubscribeDialogAssoc(); + + public: //New functions + /** + * 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. + * + * @pre Dialog().Connection().State()==EActive + * @pre Dialog().State()==CSIPDialog::EInit || + * Dialog().State()==CSIPDialog::EConfirmed + * @param aElements optional SIP message headers and body. Ownership is + * transferred. + * @param aRefresh if set the transaction will be refreshed at given + * interval. Interval must be defined by including + * Expires-header. Ownership is transferred. + * @return SUBSCRIBE SIP transaction. Ownership is transferred. + * @leave KErrSIPInvalidDialogState if Dialog().State() is incorrect + * @capability NetworkServices + */ + IMPORT_C CSIPClientTransaction* + SendSubscribeL(CSIPMessageElements* aElements=0, + CSIPRefresh* aRefresh=0); + + /** + * 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. + * @pre aElements != 0 + * @pre Dialog().Connection().State()==EActive + * Dialog().State()==CSIPDialog::EConfirmed + * @param aElements contains user SIP headers and content; the ownership + * is transferred + * @return SUBSCRIBE SIP client transaction; the ownership is transferred + * @leave KErrArgument if aElements == 0 or aElements contain + * Event-header + * @leave KErrSIPInvalidDialogState if Dialog().State() is incorrect + * @capability NetworkServices + */ + IMPORT_C CSIPClientTransaction* UpdateL(CSIPMessageElements* aElements); + + /** + * 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. + * @pre Dialog().Connection().State()==EActive + * @pre Dialog().State()==CSIPDialog::EConfirmed + * @param aElements optional SIP message headers and body. Ownership is + * transferred. + * @return SUBSCRIBE SIP transaction. Ownership is transferred. + * @leave KErrSIPInvalidDialogState if Dialog().State() is incorrect + * @capability NetworkServices + */ + IMPORT_C CSIPClientTransaction* + SendUnsubscribeL(CSIPMessageElements* aElements=0); + + /** + * 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 Associated refresh or 0 pointer if the user has not requested + * a refresh. Ownership is not transferred. + */ + IMPORT_C const CSIPRefresh* SIPRefresh() const; + + /** + * Gets an event to which the subscription is done + * @return an event + */ + IMPORT_C const CSIPEventHeader& Event() const; + + public: // New functions, for internal use + + /** + * @internalComponent + */ + CSIPRefresh* FindRefresh(TUint32 aRefreshId); + + static CSIPSubscribeDialogAssoc* NewLC(CSIPConnection& aConnection, + CUri8* aRemoteUri, + CSIPEventHeader* aEvent, + CSIPFromHeader* aFrom, + CSIPToHeader* aTo, + CSIPContactHeader* aContact, + const MSIPRegistrationContext* aContext); + + void ConnectionLost(); + + CSIPClientTransaction* + DoSendSubscribeL(CSIPMessageElements* aElements, + CSIPRefresh* aRefresh, + TBool aWithinDialog); + + CSIPClientTransaction* + DoSendUnsubscribeL(CSIPMessageElements* aElements); + + /** + * @internalComponent + */ + void DeletingRefresh(CSIPRefresh& aRefresh, TUint32 aRefreshId); + + private: // Constructors + CSIPSubscribeDialogAssoc(); + + private: // Data + //If the subscription is refreshed, this is the used CSIPRefresh + //instance, otherwise this is NULL. CSIPSubscribeDialogAssoc owns this. + CSIPRefresh* iRefresh; + + CSIPEventHeader* iEvent; + + private: // For testing purposes + UNIT_TEST(CSIP_Test) + UNIT_TEST(CSIPSubscribeDialogAssoc_Test) + }; + +#endif