/*

 * 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 "Eclipse Public License v1.0"

 * which accompanies this distribution, and is available

 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:

 * Name        : sipconnection.h

 * Part of     : SIP Client

 * Interface   : SDK API, SIP API

 * Version     : 1.0

 *

 */

 #ifndef CSIPCONNECTION_H

 #define CSIPCONNECTION_H

 // INCLUDES

 #include <e32base.h>

 #include <in_sock.h>

 // FORWARD DECLARATIONS

 class CSIP;

 class MSIPConnectionObserver;

 class CSIPClientTransaction;

 class MSIPRegistrationContext;

 class CSIPRefresh;

 class CSIPRequestElements;

 class CSIPConnectionImplementation;

 // CONSTANTS

 // CLASS DECLARATION

 /**

 * @publishedAll

 * @released

 *

 * Class for monitoring connection's state and sending SIP requests outside

 * the dialog associations. Class must not be used

 * - for sending requests to which received non-failure response creates a dialog

 * - for sending requests that must be sent within SIP dialog

 *  

 * Note that the user can have only one instance of the class per same IAP-id.

 */

 class CSIPConnection : public CBase

 	{

     public:

         /** Connection states */

         enum TState 

             {

             /** Connection initializing */

 			EInit=1,

 			/** Connection active */

 			EActive,

 			/** Connection suspended */

 			ESuspended,

 			/** Connection is inactive */

 			EInactive,

 			/** Connection is permanently unavailable */

 			EUnavailable

             };

     public:  // Constructors and destructor

 	    /**

         * Two-phased constructor.

 		* @param aSip a handle to the SIP server

 		* @param aIapId IAP-id

 		* @param aObserver a observer for receiving asynchonous events on this

         *   connection

         * @return New object, ownership is transferred

         * @capability NetworkServices

         */

 		IMPORT_C static CSIPConnection*

             NewL(CSIP& aSIP,

 				 TUint32 aIapId,

 				 MSIPConnectionObserver& aObserver);

 	    /**

         * Two-phased constructor.

 		* Constructs an object and adds the pointer to the cleanup stack;

 		* @param aSip a handle to the SIP server

 		* @param aIapId IAP-id

 		* @param aObserver a observer for receiving asynchonous events on this

         *   connection

         * @return New object, ownership is transferred

         * @capability NetworkServices

         */

 		IMPORT_C static CSIPConnection*

             NewLC(CSIP& aSIP,

 				  TUint32 aIapId,

 				  MSIPConnectionObserver& aObserver);

 		/**

 		* Destructor

         * @capability NetworkServices

 		*/

 		IMPORT_C ~CSIPConnection();

     public: // New functions

         /**

 		* Gets current state of the connection        

         * @return current state of the connection

         */

 		IMPORT_C TState State() const;

         /**

 		* Creates SIP request and sends it to the given destination.

 		* The function must not be used with SIP requests that creates

 		* SIP dialog associations or must be sent within SIP dialog

 		* association.

 		* This provokes the Non-invite state machine.

 		* This function must be used if the user has created the

 		* registration binding.

 		* @pre State() == EActive.

 		* @pre aContext.IsContextActive() == ETrue

 		* @param aElements contains local and remote addresses,

 		*		 optional SIP message headers and body.

 		*        The ownership is transferred.

 		* @param aContext defines outbound proxy to be used. If the user

 		*        does not provide from-address it will be constucted using

 		*        user's AOR used during the registration.

         * @return SIP client transaction, ownership is transferred

         * @leave KErrArgument if aElements == 0

         * @leave KErrSIPInvalidRegistrationState if aContext.IsContextActive()

         *	== EFalse

 		* @capability NetworkServices

         */

 		IMPORT_C CSIPClientTransaction*

             SendRequestL(CSIPRequestElements* aElements,

                          const MSIPRegistrationContext& aContext);

         /**

 		* Creates SIP request and sends it to the given destination.

 		* The function must not be used with SIP requests that creates

 		* SIP dialog associations or must be sent within SIP dialog

 		* association.

 		* This provokes the Non-invite state machine.

 		* This function must be used if the user has created the

 		* registration binding.

 		* @pre State() == EActive.

 		* @pre aContext.IsContextActive() == ETrue

 		* @param aElements contains local and remote addresses,

 		*		 optional SIP message headers and body.

 		*        The ownership is transferred.

 		* @param aContext defines outbound proxy to be used. If the user

 		*        does not provide from-address it will 

 		*        be constucted using user's AOR used during the registration.

 		* @param aRefresh defines the refresh interval for this transaction.

         * @return SIP client transaction, ownership is transferred

         * @leave KErrArgument if aElements == 0

         * @leave KErrSIPInvalidRegistrationState if aContext.IsContextActive()

         *	== EFalse

         * @capability NetworkServices

         */

 		IMPORT_C CSIPClientTransaction*

             SendRequestL(CSIPRequestElements* aElements,                                        

                          const MSIPRegistrationContext& aContext,

 						 CSIPRefresh& aRefresh); 

         /**

 		* Creates SIP request and sends it to the given destination.

 		* The function must not be used with SIP requests that creates SIP

 		* dialog associations or must be sent within SIP dialog association.

 		* This invokes the Non-invite state machine.

 		* @pre State() == EActive.

 		* @pre aElements.FromHeader() != 0

 		* @param aElements contains local and remote addresses,

 		*		 optional SIP message headers and body.

 		*        The ownership is transferred.

         * @return SIP client transaction, ownership is transferred

         * @leave KErrArgument if aElements == 0 or if From-header is not

         *	present in aElements

         * @capability NetworkServices

         */

 		IMPORT_C CSIPClientTransaction*

             SendRequestL(CSIPRequestElements* aElements);

         /**

 		* Creates SIP request and sends it to the given destination.

 		* The function must not be used with SIP requests that creates SIP

 		* dialog associations or must be sent within SIP dialog association.

 		* This invokes the Non-invite state machine.

 		* @pre State() == EActive.

 		* @pre aElements.FromHeader() != 0

 		* @param aElements contains local and remote addresses,

 		*		 optional SIP message headers and body.

 		*        The ownership is transferred.

 		* @param aRefresh indicates that transaction will be refreshed

         * @return SIP client transaction, ownership is transferred

         * @leave KErrArgument if aElements == 0 or if From-header is not

         *	present in aElements

         * @capability NetworkServices

         */

 		IMPORT_C CSIPClientTransaction*

             SendRequestL(CSIPRequestElements* aElements,

 						 CSIPRefresh& aRefresh);

 		/**

 		* Creates SIP REGISTER request and sends it to the given destination.

 		* User must no define any Contact or Expires-headers

 		* in the provided elements.

 		* @pre State() == EActive

         * @pre aElements != 0

         * @pre aElements->Method().DesC().Length()==0

 		* @param aElements contains local and remote addresses, optional SIP

         *        message headers and body. User must not set any expires values

         *        to aElements. The ownership is transferred.

         * @return SIP REGISTER client transaction, ownership is transferred

         * @leave KErrArgument if aElements == 0 or if the request method has

         *	been defined in aElements

         * @capability NetworkServices

         */

 		IMPORT_C CSIPClientTransaction*

             FetchRegistrationsL(CSIPRequestElements* aElements);

 		/**

 		* Gets Iap-id used for this connection

 		* @return Iap-id

 		*/

         IMPORT_C TUint32 IapId() const;

 		/**

         * Gets SIP server handle

         * @return handle to SIP server, or 0-pointer if SIP server does not

         *	exist any more

         */        

         IMPORT_C CSIP* SIP();

         /**

         * Gets SIP server handle

         * @return handle to SIP server, or 0-pointer if SIP server does not

         *	exist any more

         */        

         IMPORT_C const CSIP* SIP() const;

 		/**

 		* Sets a RSocket option used for all the sockets used for sending 

 		* SIP requests and responses in this CSIPConnection.

 		* @pre State() == EActive

 		* @param aOptionName An integer constant which identifies an option.

         * @param aOptionLevel An integer constant which identifies 

         *        level of an option.

         * @param aOption Option value packaged in a descriptor.

         * @leave A system-wide error code

         * @capability NetworkControl

         * @capability NetworkServices

         * @capability Location

         * @capability ReadDeviceData

         * @capability WriteDeviceData        

         */        

 	    IMPORT_C void SetOptL(TUint aOptionName,

 	                      	  TUint aOptionLevel,

 	                      	  const TDesC8& aOption=KNullDesC8);

 		/**

 		* Sets a RSocket option used for all the sockets used for sending 

 		* SIP requests and responses in this CSIPConnection.

 		* @pre State() == EActive

 		* @param aOptionName An integer constant which identifies an option.

         * @param aOptionLevel An integer constant which identifies 

         *        level of an option.

         * @param aOption Option value as an integer.

         * @leave A system-wide error codes

         * @capability NetworkControl

         * @capability NetworkServices

         * @capability Location

         * @capability ReadDeviceData

         * @capability WriteDeviceData

         */ 	                         

 	    IMPORT_C void SetOptL(TUint aOptionName,

 	                          TUint aOptionLevel,

 	                          TInt aOption);

         /**

         * Gets the local IP address of this CSIPConnection 

         * that is used by the SIP implementation.

         * The user should re-new the call whenever the connection state changes

         * to the CSIPConnection::EActive in order to verify the correctness of

         * the previously retrieved local IP address. The local IP address might

         * be different as a result of the connection state change.

         * @pre State() == CSIPConnection::EActive

         * @param aAddr on return filled with local IP address

         * @leave a system-wide error code

         */ 	                         

 	    IMPORT_C void GetLocalAddrL(TInetAddr& aAddr) const;

 	    /**

 	    * Refreshes the connection.

 	    * This will retrieve the Bearer Monitor Instance if any, is available for this  CSIPConnection and issue a Connection Refresh Request to it.

 	    * The state of the Connection can be retrieved from State() to check if there is any change after Refreshing the connection.

 	    * @capability NetworkServices.

 	    */

 	    IMPORT_C void RefreshConnection() const;

 	    /**

 	    * Gets the connection error code

 	    * @param aError will be filled with the error code

 	    * @leave a system-wide error code

 	    * @capability NetworkServices. 

 	    */

 	    IMPORT_C void GetConnectionErrorL(TInt &aError) const;

 	public: // New functions, for internal use

 		/**

 		* Returns the implementation instance.

 		*

  		* @return CSIPConnectionImplementation

 		*/

 		CSIPConnectionImplementation& Implementation();

     private: // Constructors

         CSIPConnection();

         void ConstructL(CSIP& aSIP,

                         TUint32 aIapId,

                         MSIPConnectionObserver& aObserver);

 	private: // Data

 		CSIPConnectionImplementation* iImplementation;

 	private: // For testing purposes

 #ifdef CPPUNIT_TEST	

 	    friend class CSIP_Test;

         friend class CSIPConnection_Test;

         friend class CSIPSubscribeDialogAssoc_Test;

         friend class CSIPInviteDialogAssoc_Test;

         friend class CSIPReferDialogAssoc_Test;

         friend class CSIPNotifyDialogAssoc_Test;

         friend class CSIPDialogTrying_Test;

         friend class CSIPRegistrationBinding_Test;

 #endif

 		void __DbgTestInvariant() const;

 	};

 #endif