1 imconnection.h

     1 /*

     2 * Copyright (c) 2004 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  IM Connection interface

    15 *

    16 */

    17 

    18 

    19 #ifndef IMCONNECTION_H

    20 #define IMCONNECTION_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 #include <ecom/ecom.h>

    25 

    26 // DATA TYPES

    27 enum TImConnectionStatus

    28     {

    29     ELoggedIn = 0,

    30     ENotLoggedIn

    31     };

    32 

    33 // FORWARD DECLARATIONS

    34 class MImClient;

    35 class MImConnectionObserver;

    36 

    37 // CLASS DECLARATION

    38 

    39 /**

    40 *  Instant Messaging API class

    41 *  By creating this class the user automatically connects to the Symbian server

    42 *  but to do something reasonable the IM interface has to be created using

    43 *  this class. The following order of calling the methods is one possibility to

    44 *  use this class:

    45 *  1. NewL() - instantiate the object

    46 *  2. RegisterObserverL() - register the observer methods

    47 *  3. LoginL() - connect to the protocol stack and login to remote IM server

    48 *  4. CreateImClientL() - get the IM interface

    49 *

    50 *  All the error codes are returned using the leave mechanism.

    51 *

    52 *  @lib imclient.dll

    53 *  @since S60 3.0

    54 */

    55 class CImConnection : public CBase

    56     {

    57     public:

    58 

    59         /**

    60         * Factory method for creating the class instance.

    61         * @since S60 3.0

    62         * @param aApplicationId the ApplicationId of the application

    63         * @return CImConnection

    64         */

    65         static CImConnection* NewL(

    66             const TDesC& aApplicationId );

    67 

    68         // Destructor

    69         virtual ~CImConnection( );

    70 

    71 

    72     public: // New functions

    73 

    74         /**

    75         * Creates the IM interface to sending and receiving IMs

    76         * @since S60 3.0

    77         * @return MImClient

    78         */

    79         virtual MImClient* CreateImClientL( ) = 0;

    80 

    81         /**

    82         * Method for registering the IM Connection observer to the API.

    83         * This method is synchronous.

    84         * @since S60 3.0

    85         * @param aObserver observer object which receives the notification

    86         * @leave KImApiErrAlreadyRegistered if it was registered already or other system wide error code

    87         */

    88         virtual void RegisterObserverL(

    89             MImConnectionObserver* aObserver ) = 0;

    90 

    91         /**

    92         * Method for unregistering the IM Connection observer.

    93         * This method is synchronous.

    94         * @since S60 2.6

    95         */

    96         virtual void UnregisterObserver( ) = 0;

    97 

    98         /**

    99         * Method for getting the connection status.

   100         * This method is synchronous.

   101         * @since S60 3.0

   102         * @return connection status enum

   103         */

   104         virtual TImConnectionStatus ImConnectionStatus( ) = 0;

   105 

   106         /**

   107         * Connects the application to the protocol stack and logs in to the

   108         * remote SAP server using the given login info.

   109         * This method is asynchronous and the completion is signaled by

   110         * HandleLoginL() observer method.

   111         * @since S60 3.0

   112         * @return connection status enum

   113         * @leave KImApiErrLoginInProgress already logging in

   114         * @leave KImApiErrLogoutInProgress logout is ongoing

   115         * @leave KImApiErrCancelLoginInProgress cancel login is ongoing

   116         * @leave KImApiErrAlreadyLoggedIn already logged in

   117         */

   118         virtual void LoginL(

   119             const TDesC&  aServer,

   120             const TDesC&  aUserID,

   121             const TDesC&  aPassword,

   122             const TUint32 aAP ) = 0;

   123 

   124         /**

   125         * Cancels the ongoing login operation.

   126         * This method is asynchronous and the completion is signaled by

   127         * HandleCancelLoginL() observer method.

   128         * @since S60 3.0

   129         * @leave KImApiErrNotLogged not logged in

   130         * @leave KImApiErrLogoutInProgress logout is ongoing

   131         * @leave KImApiErrCancelLoginInProgress cancel login is ongoing

   132         * @leave KImApiErrAlreadyLoggedIn already logged in

   133         */

   134         virtual void CancelLoginL( ) = 0;

   135 

   136         /**

   137         * Logs out from current session.

   138         * This method is asynchronous and the completion is signaled by

   139         * HandleLogoutL() observer method.

   140         * Possible leave reasons:

   141         * @since S60 3.0

   142         * @leave KImApiErrNotLogged not logged in

   143         * @leave KImApiErrLogoutInProgress logout is ongoing

   144         * @leave KImApiErrCancelLoginInProgress cancel login is ongoing

   145         */

   146         virtual void LogoutL( ) = 0;

   147 

   148     protected:

   149         // C++ constructor

   150         inline CImConnection( );

   151 

   152     private:

   153         // Unique instance identifier key (needed for ECom)

   154         TUid iDtor_ID_Key;

   155 

   156     };

   157 

   158 /**

   159 *  Connection Observer interface

   160 *

   161 *  @lib imclient.dll

   162 *  @since S60 3.0

   163 */

   164 class MImConnectionObserver

   165     {

   166     public:

   167 

   168         /**

   169         * Method is called when the LoginL() is completed.

   170         * @since S60 3.0

   171         * @param aErrorCode status code

   172         */

   173         virtual void HandleLoginL(

   174             const TInt aErrorCode ) = 0;

   175 

   176         /**

   177         * Method is called when the CancelLoginL() is completed.

   178         * @since S60 3.0

   179         * @param aErrorCode status code

   180         */

   181         virtual void HandleCancelLoginL(

   182             const TInt aErrorCode ) = 0;

   183 

   184         /**

   185         * Method is called when the LogoutL() is completed.

   186         * Also called in situations when the Logout was initiated by the server

   187         * or another client which was using the same connection

   188         * @since S60 3.0

   189         * @param aErrorCode status code

   190         */

   191         virtual void HandleLogoutL(

   192             const TInt aErrorCode ) = 0;

   193 

   194     };

   195 

   196 #include "imconnection.inl"

   197 

   198 #endif