1 /*

     2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Name          : sipclient.h

    16 * Part of       : SIPClient

    17 * Version       : SIP/5.0 

    18 *

    19 */

    20 

    21 

    22 

    23 

    24 /**

    25  @internalComponent

    26 */

    27 

    28 #ifndef CSIPCLIENT_H

    29 #define CSIPCLIENT_H

    30 

    31 #include "sipclientserver.h"

    32 #include <e32base.h>

    33 #include <badesca.h>

    34 #include "_sipcodecdefs.h"

    35 

    36 class MSIPClientObserver;

    37 class MSIPHttpDigestChallengeObserver;

    38 class MSIPHttpDigestChallengeObserver2;

    39 class CSIPClientConnection;

    40 class RSIP;

    41 class CSIPClientReceiver;

    42 

    43 

    44 /**

    45  * @brief Class for connecting to SIP server and for managing SIP transactions.

    46  * 

    47  * @class CSIPClient sipclient.h "sipclient.h"

    48  *

    49  * This class is used to communicate with the SIP server

    50  * Class provides functions for sending and receiving 

    51  * SIP requests and SIP responses.

    52  * This class also provides functions for creating and destroying SIP dialogs,

    53  * sending and receiving SIP requests and responses within SIP dialogs,

    54  * canceling the SIP requests.

    55  *

    56  * This class can only be created once by an application (a singleton class)

    57  *

    58  * If the preconditions or postconditions are not met the 

    59  * function call will result in panics. 

    60  * 

    61  * For SIP specific error codes @see TError

    62  */

    63 

    64 class CSIPClient : public CBase

    65 	{

    66 public:

    67 

    68 	/** SIP specific errors */

    69 	enum TError

    70 		{		

    71 		/** Non-existing request Id provided */

    72 		ENonExistingRequestId = 10,

    73 		/** Non-existing dialog Id provided */

    74 		ENonExistingDialogId,

    75 		/** Non-existing refresh Id provided */

    76 		ENonExistingRefreshId,

    77 		/** Non-existing registration Id provided */

    78 		ENonExistingRegistrationId

    79 		};

    80 

    81 	/**

    82 	 * Constructs an object; leaves on failure.

    83 	 *

    84 	 * @param aUid an unique id that identifies an application

    85 	 * @param aSIPObserver a sip observer. 

    86      *        This callback is used for passing 

    87      *        SIP requests and internal errors to application.

    88 	 * @returns new instance, the ownership is transferred

    89 	 */

    90 	static CSIPClient* NewL (const TUid& aUid,

    91 		                     MSIPClientObserver& aSIPObserver);

    92 

    93 	/**

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

    95 	 *

    96 	 * @param aUid an unique id that identifies an application

    97 	 * @param aSIPObserver a sip observer. 

    98      *        This callback is used for passing 

    99      *        SIP requests and internal errors to application.

   100 	 * @returns new instance, the ownership is transferred

   101 	 */

   102 	static CSIPClient* NewLC (const TUid& aUid,

   103 		                      MSIPClientObserver& aSIPObserver);

   104 

   105 	/**

   106 	 * Destructor

   107 	 */

   108 

   109 	~CSIPClient ();

   110 

   111     /**

   112      * Gets the names of all the supported security mechanisms

   113 	 * @returns Supported SIP security mechanisms names (e.g. digest)

   114      *          The ownership is transferred.

   115 	 */

   116     CDesC8Array* SupportedSecurityMechanismsL() const;

   117     

   118 	/**

   119 	 * Gets negotiated security mechanism with the next hop

   120 	 * on the signaling path.

   121 	 * @param aHop the next hop's FQDN or numeric IP address

   122 	 * @return negotiated security mechanism or zero-pointer in case no

   123 	 *		  security mechanism was negotiated with the next hop;

   124 	 *		  the ownership is transferred

   125 	 */

   126 	HBufC8* NegotiatedSecurityMechanismL(const TDesC8& aHop);    

   127 

   128     /**

   129      * Checks if the signalling compression (SigComp) is supported.

   130      * Leaves on failure with a system wide error code.

   131      * @returns ETrue if supported, EFalse otherwise

   132      */

   133     TBool IsSigCompSupportedL() const;

   134 

   135 	/**

   136      * Checks if the user has a connection created for given IAP-id

   137      * @param aIapId IAP-id

   138      * @returns a connection or 0-pointer if connection does not exist

   139      */

   140 	CSIPClientConnection* Connection (TUint32 aIapId) const;

   141 

   142     /*

   143      * By default the SIP built-in security mechanisms are enabled.

   144      * @param aEnabled if set to EFalse the build-in SIP security handling 

   145      *        mechanism is disabled.

   146      */

   147     void SetSecurityHandlingL(TBool aEnabled);

   148 

   149 	/**

   150 	 * Sets the observer to listen for the possible received challenges.

   151 	 * @param aObserver an observer for the received challenges.

   152 	 * @returns KErrNone if the observer was set successfully.

   153 	 *          KErrNoMemory if out of memory.

   154 	 */

   155     TInt SetHttpDigestObserver(MSIPHttpDigestChallengeObserver& aObserver);

   156 	

   157 	/**

   158 	 * Sets the observer to listen for the possible received challenges.

   159 	 * @param aObserver an observer for the received challenges.

   160 	 * @returns KErrNone if the observer was set successfully.

   161 	 *          KErrNoMemory if out of memory.

   162 	 */

   163     TInt SetHttpDigestObserver(MSIPHttpDigestChallengeObserver2& aObserver);	

   164 

   165 	/**

   166 	 * Removes the observer that listens for the possible received challenges.

   167 	 */	

   168 	void RemoveHttpDigestObserver();

   169 	

   170     /**

   171 	 * Sets credentials for a realm.

   172 	 * @param aRequestId request id if needed, otherwise zero

   173 	 * @param aRefreshId refresh id if needed, otherwise zero

   174 	 * @param aRealm servers's realm

   175 	 * @param aUsername user's name

   176 	 * @param aPasswd user's password for the given server's realm

   177 	 * @param aOutboundProxy an outbound proxy (FQDN or IP address)

   178 	 *        Must be set to KNullDesC8 if not used.	 

   179 	 * @leave KErrNoMemory if out of memory

   180 	 */

   181     void SetCredentialsL(TUint32 aRequestId,

   182                          TUint32 aRefreshId,

   183                          const TDesC8& aRealm,

   184 			             const TDesC8& aUsername,

   185 			             const TDesC8& aPasswd,

   186 			             const TDesC8& aOutboundProxy);

   187 			            

   188     /**

   189 	 * Removes all set credentials for the realm 

   190 	 * @param aRealm servers's realm. 

   191 	 *        If set to KNullDesC8 clears all the credentials for

   192 	 *        this CSIPClient.

   193 	 * @return KErrNone if no error; KErrNoMemory if out of memory; 

   194 	 *         KErrNotFound if the given realm was not found

   195      */

   196 	TInt RemoveCredentials(const TDesC8& aRealm);                          

   197 		

   198     /**

   199      * Ignores the challenge for the realm. 

   200      * As a result the error will be generated to the original request.

   201 	 * @param aRequestId request id if needed, otherwise zero

   202 	 * @param aRefreshId refresh id if needed, otherwise zero      

   203 	 * @param aRealm a realm for which the challenge was ignored

   204 	 * @returns KErrNone if no error; KErrNoMemory if out of memory;

   205 	 *          KErrNotFound if the given realm was not found

   206 	 */

   207     TInt IgnoreChallenge(TUint32 aRequestId,

   208                          TUint32 aRefreshId,

   209                          const TDesC8& aRealm);	

   210 

   211 

   212 public: // For SIP Client's internal use

   213 

   214     void AddL (CSIPClientConnection* aConnection);

   215     TInt Remove (const CSIPClientConnection* aConnection);

   216     RSIP& SIP ();

   217 

   218 private:

   219 

   220 	CSIPClient ();

   221 	void ConstructL (const TUid& aUid, MSIPClientObserver& aObserver);

   222     TInt FindIndex (TUint32 aIapId) const;

   223     TInt SendHttpDigestObserverTypeToServer(

   224         const TSipHttpDigestObserverType& aObserverType); 

   225 

   226 private: // Data

   227     

   228     RPointerArray<CSIPClientConnection> iConnections;

   229     RSIP* iSip;

   230 	CSIPClientReceiver* iReceiver;

   231 

   232 private: // For testing purposes

   233 

   234     UNIT_TEST(CSIPClientTest)

   235 	};

   236 

   237 #endif // CSIPCLIENT_H

   238 

   239 // End of File