epoc32/include/app/imclient.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:  Interface for Instant Messaging services
    15 *
    16 */
    17 
    18 
    19 #ifndef OPENAPI_IM_CLIENT_H
    20 #define OPENAPI_IM_CLIENT_H
    21 
    22 // INCLUDES
    23 #include <e32base.h>
    24 #include <bamdesca.h>
    25 #include <cntdef.h>
    26 
    27 // CONSTANTS
    28 
    29 // FORWARD DECLARATIONS
    30 class MImObserver;
    31 class MImClientDetailedError;
    32 
    33 // CLASS DECLARATION
    34 /**
    35 *  Instant Messaging interface class
    36 *  This interface class provides methods to send and receive instant messages.
    37 *  Application to be able to receive IMs it must register its own observer
    38 *  using this interface class.
    39 *  This interface can be obtained using a factory method from the CImConnection
    40 *  class.
    41 *
    42 *  @lib imclient.lib
    43 *  @since S60 3.0
    44 */
    45 class MImClient
    46     {
    47 
    48     public:
    49 
    50         virtual ~MImClient() {}
    51 
    52         /**
    53         * Method for registering the IM client to the WV Engine.
    54         * This method is synchronous.
    55         * @since S60 3.0
    56         * @param aObserver observer object used for notifying the user
    57         *        software
    58         * @leave KImApiErrAlreadyRegistered if it was registered already or other system wide error code
    59         */
    60         virtual void RegisterObserverL(
    61             MImObserver* aObserver ) = 0;
    62 
    63         /**
    64         * Method for unregistering the IM Sender from the WV Engine.
    65         * This method is synchronous method.
    66         * @since S60 3.0
    67         */
    68         virtual void UnregisterObserver( ) = 0;
    69 
    70         /**
    71         * Method for sending person-to-person text message (UNICODE) using
    72         * Contact Model IDs. This method is asynchronous and it’s completion
    73         * is signaled in HandleMessageSentL() method.
    74         * The method will leave on error. The API specific error codes are
    75         * in imerrors.h file
    76         * @since S60 3.0
    77         * @param aContactItem Contact Model ID of the recipient
    78         * @param aContent The content of the message in UNICODE
    79         * @return operation code
    80         * @leave KImApiErrNotRegistered observer was not registered
    81         * @leave KImApiErrInvalidContactId the contact ID does not have a corresponding User ID
    82         */
    83         virtual TInt SendPToPMessageL(
    84             const TContactItemId& aContactItem,
    85             const TDesC16& aContent ) = 0;
    86 
    87         /**
    88         * Method for sending person-to-person text message (UNICODE) using
    89         * Contact Model IDs. This method is asynchronous and its completion
    90         * is signaled in HandleMessageSentL() method.
    91         * The method will leave on error. The API specific error codes are
    92         * in imerrors.h file
    93         * Please note that one contact can have more than one assigned IM user
    94         * ID. Sending IM to those contacts will result in partial success.
    95         * @since S60 3.0
    96         * @param aContactIds Contact Model Ids of the recipient(s)
    97         * @param aContent The content of the message in UNICODE
    98         * @return operation code
    99         * @leave KImApiErrNotRegistered observer was not registered
   100         * @leave KImApiErrInvalidContactId the contact ID does not have a corresponding User ID
   101         */
   102         virtual TInt SendPToPMessageL(
   103             const CContactIdArray& aContactIds,
   104             const TDesC16& aContent ) = 0;
   105 
   106         /**
   107         * Method for sending person-to-person binary (or 8bit text) message
   108         * using Contact Model IDs. This method is asynchronous and its
   109         * completion is signaled in HandleMessageSentL() method.
   110         * The method will leave on error. The API specific error codes are
   111         * in imerrors.h file
   112         * Please note that one contact can have more than one assigned IM user
   113         * ID. Sending IM to those contacts will result in partial success.
   114         * @since S60 3.0
   115         * @param aContactIds Contact Model Ids of the recipient(s)
   116         * @param aContentType MIME type of the content
   117         * @param aContent The content of the message
   118         * @return operation code
   119         *
   120         * NOTE: Not yet supported!
   121         */
   122         virtual TInt SendPToPMessageL(
   123             const CContactIdArray& aContactIds,
   124             const TDesC& aContentType,
   125             const TDesC8& aContent ) = 0;
   126 
   127         /**
   128         * Method for sending person-to-person text message using
   129         * directly the User IDs.
   130         * This method is asynchronous and its completion is signaled
   131         * in HandleMessageSentL() method.
   132         * The method will leave on error. The API specific error codes are
   133         * in imerrors.h file
   134         * @since S60 3.0
   135         * @param aUserId the recipient of the message
   136         * @param aContent the message in UNICODE
   137         * @return operation code.
   138         * @leave KImApiErrNotRegistered observer was not registered
   139         * @leave KImApiErrInvalidUserId wrong User ID
   140         */
   141         virtual TInt SendPToPMessageL(
   142             const TDesC& aUserId,
   143             const TDesC16& aContent ) = 0;
   144 
   145         /**
   146         * Method for sending person-to-person text message using
   147         * directly the User IDs.
   148         * This method is asynchronous and its completion is signaled
   149         * in HandleMessageSentL() method.
   150         * The method will leave on error. The API specific error codes are
   151         * in imerrors.h file
   152         * @since S60 3.0
   153         * @param aUserIds recipient(s) of the message
   154         * @param aContent the message in UNICODE
   155         * @return operation code.
   156         * @leave KImApiErrNotRegistered observer was not registered
   157         * @leave KImApiErrInvalidUserId wrong User ID
   158         */
   159         virtual TInt SendPToPMessageL(
   160             const MDesCArray& aUserIds,
   161             const TDesC16& aContent ) = 0;
   162 
   163         /**
   164         * Method for sending person-to-person binary (or 8 bit text) message
   165         * using directly the User IDs.
   166         * This method is asynchronous and its completion is signaled
   167         * in HandleMessageSentL() method.
   168         * The method will leave on error. The API specific error codes are
   169         * in imerrors.h file
   170         * @since S60 3.0
   171         * @param aUserIds recipient(s) of the message
   172         * @param aContentType MIME type of the message
   173         * @param aContent the message
   174         * @return operation code.
   175         *
   176         * NOTE: Not yet supported!
   177         */
   178         virtual TInt SendPToPMessageL(
   179             const MDesCArray& aUserIds,
   180             const TDesC& aContentType,
   181             const TDesC8& aContent ) = 0;
   182 
   183     };
   184 
   185 
   186 // CLASS DECLARATION
   187 /**
   188 *  Observer interface for Instant Messaging
   189 *  The user shall implement this interface and register it through the MImClient
   190 *  interface to the API to be able to receive IMs
   191 *
   192 *  @lib imclient.lib
   193 *  @since S60 3.0
   194 */
   195 class MImObserver
   196     {
   197 
   198     public:
   199 
   200         /**
   201         * This method is called when the SendPToPMessageL succeeded
   202         * @since S60 3.0
   203         * @param aOpCode operation code matching the called functions.
   204         * @param aErrorCode error codes.
   205         */
   206         virtual void HandleMessageSentL(
   207             const TInt aOpCode,
   208             const TInt aErrorCode ) = 0;
   209 
   210         /**
   211         * This method is called when the SendPToPMessageL failed for some reason.
   212         * If the IM was sent to more recipients the error can be a partial
   213         * success. In that case the detailed error codes for each user can
   214         * fetched separately. Please note that the aDetailedError is valid
   215         * during the function call. After that it gets destroyed in the API.
   216         * @since S60 3.0
   217         * @param aOpCode operation code matching the called functions.
   218         * @param aErrorCode error codes.
   219         * @param aDetailedError list of errors for each failed user ID.
   220         */
   221         virtual void HandleSendErrorL(
   222             const TInt aOpCode,
   223             const TInt aErrorCode,
   224             MImClientDetailedError* aDetailedError ) = 0;
   225 
   226         /**
   227         * This method is called when a new point-to-point text message
   228         * has arrived.
   229         * @since S60 3.0
   230         * @param aErrorCode error codes (to be defined)
   231         * @param aContactId Contact model ID of the sender
   232         * @param aUserId UserID of the message sender
   233         * @param aMessageType MIME type of the received message
   234         * @param aContent the message in UNICODE
   235         */
   236         virtual void HandleNewPToPMessageL(
   237             const TInt aErrorCode,
   238             const TContactItemId  aContactId,
   239             const TDesC& aUserId,
   240             const TDesC& aMessageType,
   241             const TDesC16& aContent ) = 0;
   242 
   243         /**
   244         * This method is called when a new point-to-point message (8bit)
   245         * has arrived. The message can be text or binary data.
   246         * @since S60 3.0
   247         * @param aErrorCode error codes (to be defined)
   248         * @param aContactId Contact model ID of the sender
   249         * @param aUserId UserID of the message sender
   250         * @param aMessageType MIME type of the received message
   251         * @param aContent the message
   252         *
   253         * NOTE: Not yet supported!
   254         */
   255         virtual void HandleNewPToPMessageL(
   256             const TInt aErrorCode,
   257             const TContactItemId  aContactId,
   258             const TDesC& aUserId,
   259             const TDesC& aMessageType,
   260             const TDesC8& aContent ) = 0;
   261 
   262     };
   263 
   264 // CLASS DECLARATION
   265 /**
   266 *  Detailed errors accessor class
   267 *  @lib imclient.lib
   268 *  @since S60 3.0
   269 */
   270 class MImClientDetailedError
   271     {
   272 
   273     public:
   274         /**
   275         * Gets the number of failed User IDs
   276         * @since S60 3.0
   277         * @return number of failed user IDs
   278         */
   279         virtual TInt Count() = 0;
   280 
   281         /**
   282         * Gets the failed User ID
   283         * @since S60 3.0
   284         * @param aIndex index of the user in the list
   285         * @return failed user ID
   286         */
   287         virtual const TDesC& UserId( TInt aIndex ) = 0;
   288 
   289         /**
   290         * Gets the reason of the failure. The API specific error codes are
   291         * defined in imerrors.h file.
   292         * @since S60 3.0
   293         * @param aIndex index of the user in the list
   294         * @return the fail reason
   295         */
   296         virtual TInt ErrorCode( TInt aIndex ) = 0;
   297 
   298     };
   299 
   300 #endif
   301 // End of File