/*

* 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