1 /*

     2 * Copyright (c) 2002-2005 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 *     Interface for WV access services

    16 *

    17 */

    18 

    19 

    20 #ifndef IMPS_ACCESS_CLIENT_H

    21 #define IMPS_ACCESS_CLIENT_H

    22 

    23 // INCLUDES

    24 #include <e32base.h>

    25 #include <badesca.h>

    26 #include <bamdesca.h>

    27 #include "impsconst.h"

    28 #include "impsclient.h"

    29 

    30 // CONSTANTS

    31 

    32 // FORWARD DECLARATIONS

    33 class MImpsAccessHandler2;

    34 class CImpsAccessCommand2;

    35 

    36 

    37 // CLASS DECLARATION

    38 

    39 /**

    40 *  RImpsAccessClient2 API

    41 *

    42 *  Applications use Access service via RImpsAccessClient2 class. 

    43 *  First, they need to connect to the server by calling RegisterL()

    44 *  member function. Immediately after that an error handler

    45 *  must be registered by RegisterErrorObserverL.   

    46 *  

    47 *  When everything is done, call Unregister() to end

    48 *  the session.

    49 *

    50 *  A user of this API must be aware that raising/releasing

    51 *  the PDP context may affect the response times of called functions.

    52 *

    53 *  One client-server session can have only one CSP session.

    54 *

    55 *  Observer methods:

    56 *  -----------------------

    57 *  Client can be notified when a certain type of message is received 

    58 *  from the remote server.

    59 *  Client has to be connected in the server in order to get notify events.

    60 *  If the client is disconnected by server by calling Unregister(), 

    61 *  all notify requests and possible incoming events are cancelled. 

    62 *

    63 *  Notify events are session-specific, i.e. if you have several 

    64 *  ImpsAccessClients connected to the server, each has its own notify 

    65 *  requests. 

    66 *

    67 *  In order to use notify services, you need to implement 

    68 *  MImpsAccessHandler2 and give a pointer to your class in RegisterL.

    69 *  Observer method doesn't need to do anything else than your application 

    70 *  needs it to do.

    71 *

    72 * 

    73 *  Addressing:

    74 *  -----------

    75 *  WV CSP specification defines characters that must be escaped if they

    76 *  occur within the User-ID, Resource or Domain portions of a Wireless Village

    77 *  address. WV engine does NOT escape those characters on behalf of user 

    78 *  application. WV CSP also denies usage of certain characters in UserID

    79 *  totally.

    80 *

    81 */ 

    82 

    83 

    84 class RImpsAccessClient2 : public RImpsClient2

    85     {

    86 

    87     public: // Constructors and destructor

    88 

    89         /**

    90         * C++ default constructor.

    91         */      

    92         IMPORT_C RImpsAccessClient2();

    93 

    94     public: // New functions        

    95 

    96         // INITILIZATION AND CONNECT

    97 

    98        /**

    99         * Registers the listener object for Access events and connects to

   100         * the Symbian OS Server.

   101         * Leaves with KImpsErrorAlreadyInUse if the client 

   102         * has already registered.

   103         * @param aEngine WV Engine server instance

   104         * @param aObserver The observer.

   105         * @param aPriority Observer priority. Refer to CActive priority.

   106         */

   107         IMPORT_C void RegisterL( RImpsEng& aEngine,

   108                                  MImpsAccessHandler2* aObserver,

   109                                  TInt aPriority = CActive::EPriorityStandard );

   110 

   111         /**

   112         * Unregisters the listener object and disconnects from the server.

   113         */

   114         IMPORT_C void Unregister();

   115 

   116         /**

   117         * Get number of Symbian OS sessions connected to the server

   118         * @param aCspId Identifier for the session.

   119         * @return number of sessions 

   120         */

   121         IMPORT_C TInt NumberOfSessionsL( TImpsCspIdentifier& aCspId );

   122 

   123 

   124         // ACCESS SERVICES

   125 

   126         /**

   127         * Login to Service Access Point (SAP).

   128         * MImpsAccessHandler2 handles successful server response.

   129         * Errors are handled by MImpsErrorHandler2:

   130         *   KImpsErrorAP if access point cannot be accessed

   131         *   KImpsErrorShuttingDown if authoritative session stop is ongoing.

   132         *   .

   133         * Leaves with KErrArgument if maximum lengths of

   134         * parameters are exceeded.

   135         * Leaves with KErrNotReady if login cancellation

   136         * is still in progress.

   137         * The CSP session id is stored in the engine, and it is not

   138         * visible in this API.

   139         * If there is ongoing login to the same CSP session leaves with

   140         * KErrNotReady.

   141         * @param aCspId contains SAP URI and userId. Note that a 

   142         *                       strict match will be used when compared to 

   143         *                       existing sessions. 

   144         * @param aPsw password  

   145         * @param aClientId client id used to log in server.

   146         *        The client-id having prefix '+' or number is considered 

   147         *        as MSISDN number (E.164), 

   148         *        otherwise it is handled as URL.

   149         *        This MAY be used for CIR addressing if SAP is not able to

   150         *        detect MSISDN number in other way

   151         * @param aAP CommDb id for access point

   152         * @param aKey1 privateKey1 or NULL

   153         * @param aKey2 privateKey2 or NULL

   154         * @return operation-id (positive) 

   155         */

   156         IMPORT_C TInt LoginL( TImpsCspIdentifier aCspId,

   157                               const TDesC& aPsw,

   158                               const TDesC& aClientId,

   159                               TUint32 aAP,

   160                               const TDesC* aKey1 = NULL,

   161                               const TDesC* aKey2 = NULL );

   162 

   163                               

   164         /**

   165         * Login to Service Access Point (SAP) using reactive authorization.

   166         * MImpsAccessHandler2 handles successful server response.

   167         * Errors are handled by MImpsErrorHandler2:

   168         *   KImpsErrorAP if access point cannot be accessed

   169         *   KImpsErrorShuttingDown if authoritative session stop is ongoing.

   170         *   .

   171         * Leaves with KErrArgument if maximum lengths of

   172         * parameters are exceeded.

   173         * Leaves with KErrNotReady if login cancellation

   174         * is still in progress.

   175         * The CSP session id is stored in the engine, and it is not

   176         * visible in this API.

   177         * If there is ongoing login to the same CSP session leaves with

   178         * KErrNotReady.

   179         * @param aCspId contains SAP URI and userId. Note that a 

   180         *                       strict match will be used when compared to 

   181         *                       existing sessions. 

   182         * @param aPsw password  

   183         * @param aClientId client id used to log in server.

   184         *        The client-id having prefix '+' or number is considered 

   185         *        as MSISDN number (E.164), 

   186         *        otherwise it is handled as URL.

   187         *        This MAY be used for CIR addressing if SAP is not able to

   188         *        detect MSISDN number in other way

   189         * @param aAP CommDb id for access point

   190         * @param aKey1 privateKey1 or NULL

   191         * @param aKey2 privateKey2 or NULL

   192         * @return operation-id (positive) 

   193         */

   194         IMPORT_C TInt ReactiveLoginL( TImpsCspIdentifier aCspId,

   195                               const TDesC& aPsw,

   196                               const TDesC& aClientId,

   197                               TUint32 aAP,

   198                               const TDesC* aKey1 = NULL,

   199                               const TDesC* aKey2 = NULL );                             

   200 

   201         /**

   202         * Logout the client session.

   203         * MImpsAccessHandler2 handles successful server response.

   204         * Errors are handled by MImpsErrorHandler2

   205         *        KImpsErrorNotLogged if was not logged in.

   206         *        KImpsErrorShuttingDown if authoritative session stop is ongoing.

   207         *        Note: Error messages are not sent for all pending regular 

   208         *        requests in case of a CSP session logout (either a terminal 

   209         *        or a SAP initiated logout). After the status has changed to 

   210         *        NOT_LOGGED, the pending regular requests are ignored and the 

   211         *        corresponding observer methods are never called. Therefore 

   212         *        it is highly recommendable that one client instance of the 

   213         *        application registers a status observer to detect the 

   214         *        NOT_LOGGED status.

   215         * @return operation-id (positive) 

   216         */

   217         IMPORT_C TInt LogoutL( );

   218 

   219         /**

   220         * Cancel the ongoing login

   221         * Causes a logout request to the WV server.

   222         * MImpsAccessHandler2 handles successful server response.

   223         * Errors are handled by MImpsErrorHandler2

   224         *   KImpsErrorNotLogged if is not tried to log in.

   225         *   KImpsErrorShuttingDown if authoritative session stop is ongoing.

   226         * Leaves with KErrArgument if there is no ongoing login 

   227         * If the login is completed in

   228         * engine, the request cannot be canceled, leaves with KErrNotFound.

   229         * In this kind of situations handleLogin or handleError will be called.

   230         * @param aCancelOpId, operation-id of the login call to be cancelled.

   231         */

   232         IMPORT_C void CancelLoginL( TInt aCancelOpId );

   233 

   234         /**

   235         * Authorative session stop

   236         * Closes all CSP sessions at once

   237         * 

   238         * After this method has been called, WVEngine calls         

   239         * HandleStatusChangeL(EImps_SHUTTING_DOWN).The client should then call

   240         * Unregister() immediately. When all clients are disconnected, WVEngine 

   241         * goes down. All method calls except Unregister()

   242         * and Close() during the shutdown will cause KImpsErrorShuttingDown 

   243         * Note: If there are any pending requests the WVEngine DOES NOT

   244         * complete the requests.  

   245         */

   246         IMPORT_C void CloseCspSessionsL( );

   247 

   248         /**

   249         * Pointer to the observer handler

   250         * @return handler

   251         */

   252         MImpsAccessHandler2* Handler();

   253 

   254         /**

   255         * Get stored operation id

   256         * @return opId

   257         */

   258         TInt LoginOpId();

   259 

   260         /**

   261         * Is the login cancelled

   262         * @return boolean

   263         */

   264         TBool LoginCancelled();

   265 

   266         /**

   267         * Login cancel handled

   268         */

   269         void CancelHandled();

   270         

   271     private:

   272 

   273        /**

   274         * Registers the listener object for Access events and connects to

   275         * the Symbian OS Server.

   276         * @param aEngine WV Engine server instance

   277         * @param aHandler the observer

   278         * @return general error code

   279         */

   280         TInt DoRegister( 

   281             RImpsEng& aEngine,

   282             CImpsHandler2* aHandler );

   283 

   284 

   285     private: // data

   286 

   287         CImpsAccessCommand2*             iCommand;

   288         MImpsAccessHandler2*             iHandlerCallBack;

   289         // Local copies of data to enable internally asyncronous request

   290         TPtrC8                           iSAP; 

   291         TInt							 iLoginOpId;

   292         TBool							 iLoginCancelled;

   293        

   294     private: // friend classes

   295         friend class CImpsAccessCommand2;

   296     

   297     };

   298 

   299 // CLASS DECLARATION

   300 

   301 /**

   302 * MImpsAccessHandler2

   303 *

   304 * Abstract interface for handling the notify events from the server.

   305 * User derives his class from this and implements the methods below.

   306 */

   307 

   308 class MImpsAccessHandler2

   309     {

   310 

   311     public: // New functions

   312 

   313     /**

   314     * Observer method for Login event.

   315     * Login may be initiated by other application.

   316     * @param aId operation id received in LoginL. If this is 0, then the

   317     *        login was initated by other application or SAP.

   318     * @param aCspId CSP session identifier

   319     */

   320     virtual void HandleLoginL( TInt aId,

   321                                TImpsCspIdentifier& aCspId )  = 0;

   322 

   323     /**

   324     * Observer method for Logout event.

   325     * @param aId operation id received in LogoutL. If this is 0, then the

   326     *        logout was initated by other application or caused by a serious 

   327     *        network error. SAP initiated logouts are identfied with -1.

   328     * @param aCspId CSP session identifier

   329     */

   330     virtual void HandleLogoutL( TInt aId,

   331                                 TImpsCspIdentifier& aCspId )  = 0;

   332 

   333     /**

   334     * Observer method for CancelLogin event.

   335     * @param aCancelledOpId operation id of the cancelled login.

   336     * @param aCspId CSP session identifier

   337     */

   338     virtual void HandleLoginCancelL( TInt aCancelledOpId,

   339                                      TImpsCspIdentifier& aCspId )  = 0;

   340 

   341 

   342     /**

   343     * Obsolete, NOT IN USE

   344     * @param aId operation id 

   345     * @param aNbr number of sessions 

   346     * @param aCspId CSP session identifier

   347     * 

   348     */

   349     virtual void HandleNbrSessionsL( TInt aId,

   350                                      TInt aNbr,

   351                                      TImpsCspIdentifier& aCspId )  = 0;

   352 

   353     };

   354 

   355 

   356 #endif