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        : sipconnection.h
williamr@2: * Part of     : SIP Client
williamr@2: * Interface   : SDK API, SIP API
williamr@2: * Version     : 1.0
williamr@2: *
williamr@2: */
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #ifndef CSIPCONNECTION_H
williamr@2: #define CSIPCONNECTION_H
williamr@2: 
williamr@2: // INCLUDES
williamr@2: #include <e32base.h>
williamr@2: #include <in_sock.h>
williamr@2: 
williamr@2: // FORWARD DECLARATIONS
williamr@2: class CSIP;
williamr@2: class MSIPConnectionObserver;
williamr@2: class CSIPClientTransaction;
williamr@2: class MSIPRegistrationContext;
williamr@2: class CSIPRefresh;
williamr@2: class CSIPRequestElements;
williamr@2: class CSIPConnectionImplementation;
williamr@2: 
williamr@2: // CONSTANTS
williamr@2: 
williamr@2: // CLASS DECLARATION
williamr@2: 
williamr@2: /**
williamr@2: * @publishedAll
williamr@2: * @released
williamr@2: *
williamr@2: * Class for monitoring connection's state and sending SIP requests outside
williamr@2: * the dialog associations. Class must not be used
williamr@2: * - for sending requests to which received non-failure response creates a dialog
williamr@2: * - for sending requests that must be sent within SIP dialog
williamr@2: *  
williamr@2: * Note that the user can have only one instance of the class per same IAP-id.
williamr@2: */
williamr@2: class CSIPConnection : public CBase
williamr@2: 	{
williamr@2:     public:
williamr@2:         /** Connection states */
williamr@2:         enum TState 
williamr@2:             {
williamr@2:             /** Connection initializing */
williamr@2: 			EInit=1,
williamr@2: 			/** Connection active */
williamr@2: 			EActive,
williamr@2: 			/** Connection suspended */
williamr@2: 			ESuspended,
williamr@2: 			/** Connection is inactive */
williamr@2: 			EInactive,
williamr@2: 			/** Connection is permanently unavailable */
williamr@2: 			EUnavailable
williamr@2:             };
williamr@2: 
williamr@2:     public:  // Constructors and destructor
williamr@2: 
williamr@2: 	    /**
williamr@2:         * Two-phased constructor.
williamr@2: 		* @param aSip a handle to the SIP server
williamr@2: 		* @param aIapId IAP-id
williamr@2: 		* @param aObserver a observer for receiving asynchonous events on this
williamr@2:         *   connection
williamr@2:         * @return New object, ownership is transferred
williamr@2:         * @capability NetworkServices
williamr@2:         */
williamr@2: 		IMPORT_C static CSIPConnection*
williamr@2:             NewL(CSIP& aSIP,
williamr@2: 				 TUint32 aIapId,
williamr@2: 				 MSIPConnectionObserver& aObserver);
williamr@2: 
williamr@2: 	    /**
williamr@2:         * Two-phased constructor.
williamr@2: 		* Constructs an object and adds the pointer to the cleanup stack;
williamr@2: 		* @param aSip a handle to the SIP server
williamr@2: 		* @param aIapId IAP-id
williamr@2: 		* @param aObserver a observer for receiving asynchonous events on this
williamr@2:         *   connection
williamr@2:         * @return New object, ownership is transferred
williamr@2:         * @capability NetworkServices
williamr@2:         */
williamr@2: 		IMPORT_C static CSIPConnection*
williamr@2:             NewLC(CSIP& aSIP,
williamr@2: 				  TUint32 aIapId,
williamr@2: 				  MSIPConnectionObserver& aObserver);
williamr@2: 
williamr@2: 		/**
williamr@2: 		* Destructor
williamr@2:         * @capability NetworkServices
williamr@2: 		*/
williamr@2: 		IMPORT_C ~CSIPConnection();
williamr@2: 
williamr@2:     public: // New functions
williamr@2: 
williamr@2:         /**
williamr@2: 		* Gets current state of the connection        
williamr@2:         * @return current state of the connection
williamr@2:         */
williamr@2: 		IMPORT_C TState State() const;
williamr@2: 
williamr@2:         /**
williamr@2: 		* Creates SIP request and sends it to the given destination.
williamr@2: 		* The function must not be used with SIP requests that creates
williamr@2: 		* SIP dialog associations or must be sent within SIP dialog
williamr@2: 		* association.
williamr@2: 		* This provokes the Non-invite state machine.
williamr@2: 		* This function must be used if the user has created the
williamr@2: 		* registration binding.
williamr@2: 		* @pre State() == EActive.
williamr@2: 		* @pre aContext.IsContextActive() == ETrue
williamr@2: 		* @param aElements contains local and remote addresses,
williamr@2: 		*		 optional SIP message headers and body.
williamr@2: 		*        The ownership is transferred.
williamr@2: 		* @param aContext defines outbound proxy to be used. If the user
williamr@2: 		*        does not provide from-address it will be constucted using
williamr@2: 		*        user's AOR used during the registration.
williamr@2:         * @return SIP client transaction, ownership is transferred
williamr@2:         * @leave KErrArgument if aElements == 0
williamr@2:         * @leave KErrSIPInvalidRegistrationState if aContext.IsContextActive()
williamr@2:         *	== EFalse
williamr@2: 		* @capability NetworkServices
williamr@2:         */
williamr@2: 		IMPORT_C CSIPClientTransaction*
williamr@2:             SendRequestL(CSIPRequestElements* aElements,
williamr@2:                          const MSIPRegistrationContext& aContext);
williamr@2: 
williamr@2:         /**
williamr@2: 		* Creates SIP request and sends it to the given destination.
williamr@2: 		* The function must not be used with SIP requests that creates
williamr@2: 		* SIP dialog associations or must be sent within SIP dialog
williamr@2: 		* association.
williamr@2: 		* This provokes the Non-invite state machine.
williamr@2: 		* This function must be used if the user has created the
williamr@2: 		* registration binding.
williamr@2: 		* @pre State() == EActive.
williamr@2: 		* @pre aContext.IsContextActive() == ETrue
williamr@2: 		* @param aElements contains local and remote addresses,
williamr@2: 		*		 optional SIP message headers and body.
williamr@2: 		*        The ownership is transferred.
williamr@2: 		* @param aContext defines outbound proxy to be used. If the user
williamr@2: 		*        does not provide from-address it will 
williamr@2: 		*        be constucted using user's AOR used during the registration.
williamr@2: 		* @param aRefresh defines the refresh interval for this transaction.
williamr@2:         * @return SIP client transaction, ownership is transferred
williamr@2:         * @leave KErrArgument if aElements == 0
williamr@2:         * @leave KErrSIPInvalidRegistrationState if aContext.IsContextActive()
williamr@2:         *	== EFalse
williamr@2:         * @capability NetworkServices
williamr@2:         */
williamr@2: 		IMPORT_C CSIPClientTransaction*
williamr@2:             SendRequestL(CSIPRequestElements* aElements,                                        
williamr@2:                          const MSIPRegistrationContext& aContext,
williamr@2: 						 CSIPRefresh& aRefresh); 
williamr@2: 
williamr@2:         /**
williamr@2: 		* Creates SIP request and sends it to the given destination.
williamr@2: 		* The function must not be used with SIP requests that creates SIP
williamr@2: 		* dialog associations or must be sent within SIP dialog association.
williamr@2: 		* This invokes the Non-invite state machine.
williamr@2: 		* @pre State() == EActive.
williamr@2: 		* @pre aElements.FromHeader() != 0
williamr@2: 		* @param aElements contains local and remote addresses,
williamr@2: 		*		 optional SIP message headers and body.
williamr@2: 		*        The ownership is transferred.
williamr@2:         * @return SIP client transaction, ownership is transferred
williamr@2:         * @leave KErrArgument if aElements == 0 or if From-header is not
williamr@2:         *	present in aElements
williamr@2:         * @capability NetworkServices
williamr@2:         */
williamr@2: 		IMPORT_C CSIPClientTransaction*
williamr@2:             SendRequestL(CSIPRequestElements* aElements);
williamr@2: 
williamr@2:         /**
williamr@2: 		* Creates SIP request and sends it to the given destination.
williamr@2: 		* The function must not be used with SIP requests that creates SIP
williamr@2: 		* dialog associations or must be sent within SIP dialog association.
williamr@2: 		* This invokes the Non-invite state machine.
williamr@2: 		* @pre State() == EActive.
williamr@2: 		* @pre aElements.FromHeader() != 0
williamr@2: 		* @param aElements contains local and remote addresses,
williamr@2: 		*		 optional SIP message headers and body.
williamr@2: 		*        The ownership is transferred.
williamr@2: 		* @param aRefresh indicates that transaction will be refreshed
williamr@2:         * @return SIP client transaction, ownership is transferred
williamr@2:         * @leave KErrArgument if aElements == 0 or if From-header is not
williamr@2:         *	present in aElements
williamr@2:         * @capability NetworkServices
williamr@2:         */
williamr@2: 		IMPORT_C CSIPClientTransaction*
williamr@2:             SendRequestL(CSIPRequestElements* aElements,
williamr@2: 						 CSIPRefresh& aRefresh);
williamr@2: 
williamr@2: 		/**
williamr@2: 		* Creates SIP REGISTER request and sends it to the given destination.
williamr@2: 		* User must no define any Contact or Expires-headers
williamr@2: 		* in the provided elements.
williamr@2: 		* @pre State() == EActive
williamr@2:         * @pre aElements != 0
williamr@2:         * @pre aElements->Method().DesC().Length()==0
williamr@2: 		* @param aElements contains local and remote addresses, optional SIP
williamr@2:         *        message headers and body. User must not set any expires values
williamr@2:         *        to aElements. The ownership is transferred.
williamr@2:         * @return SIP REGISTER client transaction, ownership is transferred
williamr@2:         * @leave KErrArgument if aElements == 0 or if the request method has
williamr@2:         *	been defined in aElements
williamr@2:         * @capability NetworkServices
williamr@2:         */
williamr@2: 		IMPORT_C CSIPClientTransaction*
williamr@2:             FetchRegistrationsL(CSIPRequestElements* aElements);
williamr@2: 
williamr@2: 		/**
williamr@2: 		* Gets Iap-id used for this connection
williamr@2: 		* @return Iap-id
williamr@2: 		*/
williamr@2:         IMPORT_C TUint32 IapId() const;
williamr@2: 
williamr@2: 		/**
williamr@2:         * Gets SIP server handle
williamr@2:         * @return handle to SIP server, or 0-pointer if SIP server does not
williamr@2:         *	exist any more
williamr@2:         */        
williamr@2:         IMPORT_C CSIP* SIP();
williamr@2: 
williamr@2:         /**
williamr@2:         * Gets SIP server handle
williamr@2:         * @return handle to SIP server, or 0-pointer if SIP server does not
williamr@2:         *	exist any more
williamr@2:         */        
williamr@2:         IMPORT_C const CSIP* SIP() const;
williamr@2:       
williamr@2: 		/**
williamr@2: 		* Sets a RSocket option used for all the sockets used for sending 
williamr@2: 		* SIP requests and responses in this CSIPConnection.
williamr@2: 		* @pre State() == EActive
williamr@2: 		* @param aOptionName An integer constant which identifies an option.
williamr@2:         * @param aOptionLevel An integer constant which identifies 
williamr@2:         *        level of an option.
williamr@2:         * @param aOption Option value packaged in a descriptor.
williamr@2:         * @leave A system-wide error code
williamr@2:         * @capability NetworkControl
williamr@2:         * @capability NetworkServices
williamr@2:         * @capability Location
williamr@2:         * @capability ReadDeviceData
williamr@2:         * @capability WriteDeviceData        
williamr@2:         */        
williamr@2: 	    IMPORT_C void SetOptL(TUint aOptionName,
williamr@2: 	                      	  TUint aOptionLevel,
williamr@2: 	                      	  const TDesC8& aOption=KNullDesC8);
williamr@2: 
williamr@2: 		/**
williamr@2: 		* Sets a RSocket option used for all the sockets used for sending 
williamr@2: 		* SIP requests and responses in this CSIPConnection.
williamr@2: 		* @pre State() == EActive
williamr@2: 		* @param aOptionName An integer constant which identifies an option.
williamr@2:         * @param aOptionLevel An integer constant which identifies 
williamr@2:         *        level of an option.
williamr@2:         * @param aOption Option value as an integer.
williamr@2:         * @leave A system-wide error codes
williamr@2:         * @capability NetworkControl
williamr@2:         * @capability NetworkServices
williamr@2:         * @capability Location
williamr@2:         * @capability ReadDeviceData
williamr@2:         * @capability WriteDeviceData
williamr@2:         */ 	                         
williamr@2: 	    IMPORT_C void SetOptL(TUint aOptionName,
williamr@2: 	                          TUint aOptionLevel,
williamr@2: 	                          TInt aOption);
williamr@2: 
williamr@2:         /**
williamr@2:         * Gets the local IP address of this CSIPConnection 
williamr@2:         * that is used by the SIP implementation.
williamr@2:         * The user should re-new the call whenever the connection state changes
williamr@2:         * to the CSIPConnection::EActive in order to verify the correctness of
williamr@2:         * the previously retrieved local IP address. The local IP address might
williamr@2:         * be different as a result of the connection state change.
williamr@2:         * @pre State() == CSIPConnection::EActive
williamr@2:         * @param aAddr on return filled with local IP address
williamr@2:         * @leave a system-wide error code
williamr@2:         */ 	                         
williamr@2: 	    IMPORT_C void GetLocalAddrL(TInetAddr& aAddr) const;
williamr@2: 	    
williamr@4: 	    /**
williamr@4: 	    * Refreshes the connection.
williamr@4: 	    * This will retrieve the Bearer Monitor Instance if any, is available for this  CSIPConnection and issue a Connection Refresh Request to it.
williamr@4: 	    * The state of the Connection can be retrieved from State() to check if there is any change after Refreshing the connection.
williamr@4: 	    * @capability NetworkServices.
williamr@4: 	    */
williamr@2: 	    
williamr@4: 	    IMPORT_C void RefreshConnection() const;
williamr@4: 	  
williamr@4: 	    /**
williamr@4: 	    * Gets the connection error code
williamr@4: 	    * @param aError will be filled with the error code
williamr@4: 	    * @leave a system-wide error code
williamr@4: 	    * @capability NetworkServices. 
williamr@4: 	    */
williamr@4: 	    IMPORT_C void GetConnectionErrorL(TInt &aError) const;
williamr@2: 
williamr@2: 	public: // New functions, for internal use
williamr@2: 	
williamr@2: 		/**
williamr@2: 		* Returns the implementation instance.
williamr@2: 		*
williamr@2:  		* @return CSIPConnectionImplementation
williamr@2: 		*/
williamr@2: 		CSIPConnectionImplementation& Implementation();
williamr@2: 
williamr@2:     private: // Constructors
williamr@2:     
williamr@2:         CSIPConnection();
williamr@2: 
williamr@2:         void ConstructL(CSIP& aSIP,
williamr@2:                         TUint32 aIapId,
williamr@2:                         MSIPConnectionObserver& aObserver);
williamr@2: 
williamr@2: 	private: // Data
williamr@2: 	
williamr@2: 		CSIPConnectionImplementation* iImplementation;
williamr@2: 		        
williamr@2: 	private: // For testing purposes
williamr@4: #ifdef CPPUNIT_TEST	
williamr@4: 	    friend class CSIP_Test;
williamr@4:         friend class CSIPConnection_Test;
williamr@4:         friend class CSIPSubscribeDialogAssoc_Test;
williamr@4:         friend class CSIPInviteDialogAssoc_Test;
williamr@4:         friend class CSIPReferDialogAssoc_Test;
williamr@4:         friend class CSIPNotifyDialogAssoc_Test;
williamr@4:         friend class CSIPDialogTrying_Test;
williamr@4:         friend class CSIPRegistrationBinding_Test;
williamr@4: #endif
williamr@4: 		void __DbgTestInvariant() const;
williamr@4: 
williamr@2: 	};
williamr@2: 
williamr@2: #endif