epoc32/include/app/imconnection.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000
branchSymbian2
changeset 2 2fe1408b6811
parent 1 666f914201fb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
     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