Mercurial Mercurial > oss > API_REF > Public_API / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
epoc32/include/sipsubscribedialogassoc.h
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e 
--- 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
API_REF/Public_API