1 /*

     2 * Copyright (c) 2006 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:   Declaration of RCatalogsClientServerClientSession

    15 *

    16 */

    17 

    18 

    19 #ifndef R_CATALOGS_CLIENT_SERVER_CLIENT_SESSION_H

    20 #define R_CATALOGS_CLIENT_SERVER_CLIENT_SESSION_H

    21 

    22 #include <e32std.h>

    23 

    24 #include "catalogsclientserver.h"

    25 #include "catalogsserverdefines.h"

    26 

    27 class CCatalogsClientServerAsyncTask;

    28 

    29 

    30 /**

    31  *  A class implementing MCatalogsClientServer interface

    32  *

    33  *  This class offers message sending services for clients

    34  *

    35  *  @lib ?library

    36  *  @since S60 ?S60_version *** for example, S60 v3.0

    37  */

    38 class RCatalogsClientServerClientSession : public RSessionBase,

    39                                            public MCatalogsClientServer

    40     {

    41 

    42 public:

    43 

    44     /**

    45      * Constructor

    46      */

    47     RCatalogsClientServerClientSession();

    48 

    49     /**

    50      * Connect to the server and create a session. If connection

    51      * cannot be made, tries for a few more times. There is also a

    52      * sleep between the tries which halts the current thread.

    53      * 

    54      * @since S60 ?S60_version

    55      * @param aClientUid A uid identifying the client.

    56      * @return System wide error code.

    57      */

    58     TInt Connect( TUid aClientUid );

    59 

    60     /**

    61      * Disconnect the connection to the server

    62      * Notice: If there are pending tasks when this function

    63      *         is called they will not get completed. Try to

    64      *         complete the tasks before a call to this function.

    65      */

    66     void Disconnect();

    67 

    68     /**

    69      * Tells the server to create a new provider. The

    70      * function is executed asynchronously.

    71      *

    72      * @since S60 ?S60_version

    73      * @param aUid Uid of the provider that should be created.

    74      *             (integer containing a hexadecimal number)

    75      * @param aStatus A request status which indicates the 

    76      *          completion status of the asynchronous call

    77      * @param aHandle a reference to an integer that holds

    78      *              the provider message handle after the

    79      *              asynchronous function call completes

    80      *              (i.e. used to return the handle.) 

    81      * @param aOptions Provider options

    82      * 

    83      */

    84     void CreateProvider( TInt aUid,

    85                          TRequestStatus& aStatus,

    86                          TInt& aHandle,

    87                          TUint32 aOptions );

    88 

    89     /**

    90      * Sends a normal asynchronous message to server-side.

    91      *

    92      * @since S60 ?S60_version

    93      * @param aMessageType Internal messagetype used in

    94      *                     ClientServer.

    95      * @param aArgs Parameters for message encased in TIpcArgs.

    96      * @param aStatus A request status which indicates the 

    97      *                completion status of the asynchronous call

    98      * 

    99      */    

   100     void SendAsync( TCatalogsServerFunction aMessageType,

   101                     const TIpcArgs& aArgs,

   102                     TRequestStatus& aStatus );

   103 

   104     /**

   105      * Sends a synchronous message to server-side.

   106      *

   107      * @since S60 ?S60_version

   108      * @param aMessageType Internal messagetype used in

   109      *                     ClientServer.

   110      * @param aArgs Parameters for message encased in TIpcArgs.

   111      * @return Symbian error code

   112      * 

   113      */

   114     TInt SendSync( TCatalogsServerFunction aMessageType,

   115                    const TIpcArgs& aArgs );                    

   116                     

   117     /**

   118      * Informs that session side task has been completed

   119      * and that it can be removed.

   120      *

   121      * @since S60 ?S60_version

   122      * @param aCompletedTask Task that has been completed.

   123      * 

   124      */     

   125     void TaskCompleted( CCatalogsClientServerAsyncTask* aCompletedTask );

   126 

   127     /**

   128      * Deletes incomplete message from the server side by

   129      * sending a synchronous delete-message.

   130      *

   131      * @since S60 ?S60_version

   132      * @param aHandle Handle to incomplete message.

   133      */    

   134     TInt DeleteIncompleteMessage( TInt aHandle );    

   135         

   136     /**

   137      * Get the version number of the server.

   138      * 

   139      * @return The version number.

   140      */

   141     TVersion Version() const;

   142     

   143 

   144 // from base class MCatalogsClientServer

   145 

   146     /**

   147      * From MCatalogsClientServer

   148      * @see MCatalogsClientServer

   149      *

   150      * Function to send a synchronous message.

   151      *

   152      * @since S60 ?S60_version

   153      * @param aFunction Integer for receiver usage.

   154      * @param aInput Input data that should be sent.

   155      * @param aOutput Descriptor for data returning purpose.

   156      * @param aHandle An integer that identifies receiver.

   157      * @return System wide error code. 

   158      */

   159     TInt SendSync( TInt aFunction,

   160                    const TDesC8& aInput,

   161                    TDes8& aOutput,

   162                    TInt aHandle );

   163 

   164     /**

   165      * From MCatalogsClientServer

   166      * @see MCatalogsClientServer

   167      *

   168      * Function to send a synchronous message.

   169      *

   170      * @since S60 ?S60_version

   171      * @param aFunction Integer for receiver usage.

   172      * @param aInput Input data that should be sent.

   173      * @param aOutput Descriptor for data returning purpose.

   174      * @param aHandle An integer that identifies receiver.

   175      * @return System wide error code. 

   176      */

   177     TInt SendSync( TInt aFunction,

   178                    const TDesC16& aInput,

   179                    TDes16& aOutput,

   180                    TInt aHandle );

   181 

   182     /**

   183      * From MCatalogsClientServer

   184      * @see MCatalogsClientServer

   185      *

   186      * Function to send a synchronous message.

   187      *

   188      * @since S60 ?S60_version

   189      * @param aFunction Integer for receiver usage.

   190      * @param aInput Input data that should be sent.

   191      * @param aOutputInt Integer for data returning purpose.

   192      * @param aHandle An integer that identifies receiver.

   193      * @return System wide error code. 

   194      */

   195     TInt SendSync( TInt aFunction,

   196                    const TDesC16& aInput,

   197                    TInt& aOutputInt,

   198                    TInt aHandle );

   199 

   200     /**

   201      * From MCatalogsClientServer

   202      * @see MCatalogsClientServer

   203      *

   204      * Function to send a synchronous message.

   205      *

   206      * @since S60 ?S60_version

   207      * @param aFunction Integer for receiver usage.

   208      * @param aInput Input data that should be sent.

   209      * @param aOutputInt Integer for data returning purpose.

   210      * @param aHandle An integer that identifies receiver.

   211      * @return System wide error code. 

   212      */

   213     TInt SendSync( TInt aFunction,

   214                    const TDesC8& aInput,

   215                    TInt& aOutputInt,

   216                    TInt aHandle );

   217 

   218     /**

   219      * From MCatalogsClientServer

   220      * @see MCatalogsClientServer

   221      *

   222      * Function to send asynchronous message to a receiver on the

   223      * the server-side so that ClientServer allocates needed

   224      * buffer for return message.

   225      *

   226      * @since S60 ?S60_version

   227      * @param aFunction Integer for receiver usage.

   228      * @param aInput Input data that should be sent.

   229      * @param aOutput Reference to descriptor pointer which is used to

   230      *                return a pointer to allocated return buffer.

   231      * @param aHandle An integer that identifies receiver. 

   232      * @param aLength Expected length of the return message.

   233      * @return KErrNone if successful, otherwise an error code

   234      */

   235     TInt SendSyncAlloc( TInt aFunction,

   236                         const TDesC8& aInput,

   237                         HBufC8*& aOutput,

   238                         TInt aHandle,

   239                         TInt aLength );

   240 

   241     /**

   242      * From MCatalogsClientServer

   243      * @see MCatalogsClientServer

   244      *

   245      * Function to send asynchronous message to a receiver on the

   246      * the server-side so that ClientServer allocates needed

   247      * buffer for return message.

   248      *

   249      * @since S60 ?S60_version

   250      * @param aFunction Integer for receiver usage.

   251      * @param aInput Input data that should be sent.

   252      * @param aOutput Reference to descriptor pointer which is used to

   253      *                return a pointer to allocated return buffer.

   254      * @param aHandle An integer that identifies receiver. 

   255      * @param aLength Expected length of the return message.

   256      * @return KErrNone if successful, otherwise an error code

   257      */

   258     TInt SendSyncAlloc( TInt aFunction,

   259                         const TDesC16& aInput,

   260                         HBufC16*& aOutput,

   261                         TInt aHandle,

   262                         TInt aLength );

   263 

   264 

   265     /**

   266      * Sends a file open message to a server side object. The server side object

   267      * should return an open RFile handle

   268      *

   269      * @since S60 ?S60_version

   270      * @param aFunction the opcode specifying the requested service

   271      * @param aInput input data to be sent

   272      *                

   273      * @param aHandle a handle that is used to specify the receiving

   274      *                  object on the server side

   275      * @return An open file handle

   276      */

   277     RFile SendSyncFileOpenL( TInt aFunction,

   278                              const TDesC8& aInput,                           

   279                              TInt aHandle );    

   280                         

   281     

   282     /**

   283      * From MCatalogsClientServer

   284      * @see MCatalogsClientServer

   285      *

   286      * Function to send basic asynchronous message to a

   287      * receiver on the server-side.

   288      *

   289      * @since S60 ?S60_version

   290      * @param aFunction Integer for receiver usage.

   291      * @param aInput Input data that should be sent.

   292      * @param aOutput Descriptor for data returning purpose.

   293      * @param aHandle An integer that identifies receiver. 

   294      * @param aStatus A request status which indicates the 

   295      *                completion status of the asynchronous call.

   296      */

   297     void SendAsync( TInt aFunction,

   298                     const TDesC8& aInput,

   299                     TDes8& aOutput,

   300                     TInt aHandle,

   301                     TRequestStatus& aStatus );

   302 

   303     

   304     /**

   305      * From MCatalogsClientServer

   306      * @see MCatalogsClientServer

   307      *

   308      * Function to send asynchronous message to a receiver on the

   309      * the server-side so that ClientServer allocates needed

   310      * buffer for return message.

   311      *

   312      * @since S60 ?S60_version

   313      * @param aFunction Integer for receiver usage.

   314      * @param aInput Input data that should be sent.

   315      * @param aOutput Reference to descriptor pointer which is used to

   316      *                return a pointer to allocated return buffer.

   317      * @param aHandle An integer that identifies receiver. 

   318      * @param aStatus A request status which indicates the 

   319      *                completion status of the asynchronous call.

   320      * @param aLength Expected length of the return message.

   321      */

   322     void SendAsyncAlloc( TInt aFunction,

   323                           const TDesC8& aInput,

   324                           HBufC8*& aOutput,

   325                           TInt aHandle,

   326                           TRequestStatus& aStatus,

   327                           TInt aLength );

   328 

   329     /**

   330      * From MCatalogsClientServer

   331      * @see MCatalogsClientServer

   332      *

   333      * Function to inform that sender is going down. This means that

   334      * all asyncTasks that are handling message transfer of the

   335      * sender will complete with KErrCancel. The asyncTasks handling

   336      * message sending of the identified sender will not be deleted

   337      * at this point. Instead they continue to wait for completion

   338      * of the messages from the server side. When message from

   339      * the server side is received, corresponding asyncTask will be

   340      * silently deleted.

   341      *

   342      * @since S60 ?S60_version

   343      * @param aStatus TRequestStatus that identifies the sender whose

   344      *                messages should be completed immediately with

   345      *                KErrCancel.

   346      */                          

   347     void AsyncMessageSenderDown( TRequestStatus& aStatus );

   348 

   349 private:

   350 

   351     /**

   352      * Function to get a task that handles async message send/receive

   353      *

   354      * @since S60 ?S60_version

   355      * @param aTask Reference to a pointer, which is used to return

   356      *              a task that handles single asynchronous message

   357      *              send and receive task

   358      */

   359     void GetAsyncTaskL( CCatalogsClientServerAsyncTask*& aTask );

   360 

   361 

   362     /**

   363      * Assignment operator. Private with no implementation to prevent

   364      * usage.

   365      *

   366      * @since S60 ?S60_version

   367      * @param aOther Object that should be assigned to this.

   368      */

   369     RCatalogsClientServerClientSession&  operator=(

   370         const RCatalogsClientServerClientSession& aOther );

   371 

   372     /**

   373      * Copy constructor. Private with no implementation to prevent

   374      * usage.

   375      *

   376      * @since S60 ?S60_version

   377      * @param aOther Object that should be copied.

   378      */

   379     RCatalogsClientServerClientSession(

   380         const RCatalogsClientServerClientSession& aOther );

   381 

   382 private: // data

   383 

   384     /**

   385      * Array that holds pending tasks.

   386      */

   387     RPointerArray<CCatalogsClientServerAsyncTask> iTasks;

   388 

   389     /**

   390      * Variable to keep track whether session has been opened

   391      * or not.

   392      */

   393     enum

   394         {

   395         EOpen,

   396         EClosed

   397         } iSessionStatus;

   398 

   399     };

   400 

   401 #endif // R_CATALOGS_CLIENT_SERVER_CLIENT_SESSION_H