2 * Copyright (c) 2004 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: Interface for Instant Messaging services
19 #ifndef OPENAPI_IM_CLIENT_H
20 #define OPENAPI_IM_CLIENT_H
29 // FORWARD DECLARATIONS
31 class MImClientDetailedError;
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
50 virtual ~MImClient() {}
53 * Method for registering the IM client to the WV Engine.
54 * This method is synchronous.
56 * @param aObserver observer object used for notifying the user
58 * @leave KImApiErrAlreadyRegistered if it was registered already or other system wide error code
60 virtual void RegisterObserverL(
61 MImObserver* aObserver ) = 0;
64 * Method for unregistering the IM Sender from the WV Engine.
65 * This method is synchronous method.
68 virtual void UnregisterObserver( ) = 0;
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
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
83 virtual TInt SendPToPMessageL(
84 const TContactItemId& aContactItem,
85 const TDesC16& aContent ) = 0;
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
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.
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
102 virtual TInt SendPToPMessageL(
103 const CContactIdArray& aContactIds,
104 const TDesC16& aContent ) = 0;
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
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.
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
120 * NOTE: Not yet supported!
122 virtual TInt SendPToPMessageL(
123 const CContactIdArray& aContactIds,
124 const TDesC& aContentType,
125 const TDesC8& aContent ) = 0;
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
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
141 virtual TInt SendPToPMessageL(
142 const TDesC& aUserId,
143 const TDesC16& aContent ) = 0;
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
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
159 virtual TInt SendPToPMessageL(
160 const MDesCArray& aUserIds,
161 const TDesC16& aContent ) = 0;
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
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.
176 * NOTE: Not yet supported!
178 virtual TInt SendPToPMessageL(
179 const MDesCArray& aUserIds,
180 const TDesC& aContentType,
181 const TDesC8& aContent ) = 0;
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
201 * This method is called when the SendPToPMessageL succeeded
203 * @param aOpCode operation code matching the called functions.
204 * @param aErrorCode error codes.
206 virtual void HandleMessageSentL(
208 const TInt aErrorCode ) = 0;
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.
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.
221 virtual void HandleSendErrorL(
223 const TInt aErrorCode,
224 MImClientDetailedError* aDetailedError ) = 0;
227 * This method is called when a new point-to-point text message
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
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;
244 * This method is called when a new point-to-point message (8bit)
245 * has arrived. The message can be text or binary data.
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
253 * NOTE: Not yet supported!
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;
266 * Detailed errors accessor class
270 class MImClientDetailedError
275 * Gets the number of failed User IDs
277 * @return number of failed user IDs
279 virtual TInt Count() = 0;
282 * Gets the failed User ID
284 * @param aIndex index of the user in the list
285 * @return failed user ID
287 virtual const TDesC& UserId( TInt aIndex ) = 0;
290 * Gets the reason of the failure. The API specific error codes are
291 * defined in imerrors.h file.
293 * @param aIndex index of the user in the list
294 * @return the fail reason
296 virtual TInt ErrorCode( TInt aIndex ) = 0;