2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FShellNotificationManager.h
20 * @brief This is the header file for the %NotificationManager class.
22 * This header file contains the declarations of the %NotificationManager class.
25 #ifndef _FSHELL_NOTIFICATION_MANAGER_H_
26 #define _FSHELL_NOTIFICATION_MANAGER_H_
29 #include <FAppTypes.h>
31 namespace Tizen { namespace Base
39 namespace Tizen { namespace Shell
42 class NotificationRequest;
43 class IBadgeEventListener;
46 * The maximum length of a notification message.
50 static const int MAX_NOTIFICATION_MESSAGE_LENGTH = 1024;
53 * The maximum length of the launch arguments for a notification in bytes.
57 static const int MAX_NOTIFICATION_LAUNCH_ARGUMENTS_LENGTH = 1024;
60 * The maximum length of a notification badge number.
64 static const int MAX_NOTIFICATION_BADGE_NUMBER = 999;
67 * The maximum length of a title text.
71 static const int MAX_NOTIFICATION_TITLE_LENGTH = 1024;
74 * @enum OngoingActivityType
76 * Defines the notification type for an ongoing activity.
80 enum OngoingActivityType
82 ONGOING_ACTIVITY_TYPE_TEXT = 1, /**< The progress is indicated with a text */
83 ONGOING_ACTIVITY_TYPE_PROGRESS_BYTE, /**< The progress is indicated with the number of bytes */
84 ONGOING_ACTIVITY_TYPE_PROGRESS_PERCENTAGE /**< The progress is indicated with percentage */
88 * @enum NotificationStyle
90 * Defines the notification style.
94 enum NotificationStyle
96 NOTIFICATION_STYLE_NORMAL = 1, /**< The notification is normal style */
97 NOTIFICATION_STYLE_THUMBNAIL /**< The notification is thumbnail style */
102 * @class NotificationManager
103 * @brief This class provides methods to alert the user about a notification.
107 * @final This class is not intended for extension.
109 * The %NotificationManager class provides methods to alert the user about notifications.
111 * For more information about the class features, see <a href="../org.tizen.native.appprogramming/html/guide/shell/notifications.htm">Notifications</a>.
113 * The following example demonstrates how to use the %NotificationManager class.
117 * MyClass::NotificationSample(void)
120 * NotificationManager notiMgr;
121 * notiMgr.Construct();
122 * badgeNumber = notiMgr.GetBadgeNumber();
124 * notiMgr.Notify(L"A new message has arrived.", badgeNumber);
129 class _OSP_EXPORT_ NotificationManager
130 : public Tizen::Base::Object
135 * This is the default constructor for this class.
139 NotificationManager(void);
142 * This destructor overrides Tizen::Base::Object::~Object().
146 virtual ~NotificationManager(void);
149 * Initializes this instance of %NotificationManager.
153 * @return An error code
154 * @exception E_SUCCESS The method is successful.
156 result Construct(void);
159 * Gets the current badge number of an application icon.
163 * @privilege %http://tizen.org/privilege/notification
165 * @return The current badge number if the method is successful, @n
166 * else @c -1 if the method fails
167 * @exception E_SUCCESS The method is successful.
168 * @exception E_OPERATION_FAILED The operation has failed.
169 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
170 * @remarks The specific error code can be accessed using the GetLastResult() method.
173 int GetBadgeNumber(void);
176 * Notifies the user who has @c badgeNumber as a badge number.
180 * @privilege %http://tizen.org/privilege/notification
182 * @return An error code
183 * @param[in] badgeNumber The badge number
184 * @exception E_SUCCESS The method is successful.
185 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
186 * - The specified input parameter is invalid.
187 * - The specified @c badgeNumber is less than @c 0 or the @c badgeNumber is greater than Shell::MAX_NOTIFICATION_BADGE_NUMBER.
188 * @exception E_OPERATION_FAILED The operation has failed.
189 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
191 result Notify(int badgeNumber);
194 * Notifies the user with a message.
198 * @privilege %http://tizen.org/privilege/notification
200 * @return An error code
201 * @param[in] messageText The notification message
202 * @exception E_SUCCESS The method is successful.
203 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
204 * - The specified input parameter is invalid.
205 * - The specified @c messageText is empty or the length of @c messageText is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
206 * @exception E_OPERATION_FAILED The operation has failed.
207 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
209 result Notify(const Tizen::Base::String& messageText);
212 * Notifies the user who has @c badgeNumber as badge number with a message.
216 * @privilege %http://tizen.org/privilege/notification
218 * @return An error code
219 * @param[in] messageText The notification message
220 * @param[in] badgeNumber The badge number
221 * @exception E_SUCCESS The method is successful.
222 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
223 * - The specified @c messageText is empty or the length of @c messageText is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
224 * - The specified @c badgeNumber is less than @c 0 or the @c badgeNumber is greater than Shell::MAX_NOTIFICATION_BADGE_NUMBER.
225 * @exception E_OPERATION_FAILED The operation has failed.
226 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
228 result Notify(const Tizen::Base::String& messageText, int badgeNumber);
231 * Notifies the user who has @c badgeNumber as badge number with a message. @n
232 * If the user selects this message, @c launchArguments is delivered to the application. @n
233 * @c launchArguments is delivered as the value of the %http://tizen.org/appcontrol/data/notification key
234 * for Tizen::App::IAppControlProviderEventListener::OnAppControlRequestReceived().
238 * @privilege %http://tizen.org/privilege/notification
240 * @return An error code
241 * @param[in] messageText The notification message
242 * @param[in] badgeNumber The badge number
243 * @param[in] launchArguments The message for the application
244 * @exception E_SUCCESS The method is successful.
245 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
246 * - A specified input parameter is invalid. @n
247 * - The specified @c badgeNumber is less than @c 0 or the @c badgeNumber is greater than Shell::MAX_NOTIFICATION_BADGE_NUMBER. @n
248 * - The specified @c messageText is empty or the length of @c messageText is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH. @n
249 * - The specified @c launchArguments is empty or the length of @c launchArguments is greater than Shell::MAX_NOTIFICATION_LAUNCH_ARGUMENTS_LENGTH.
250 * @exception E_OPERATION_FAILED The operation has failed.
251 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
253 result Notify(const Tizen::Base::String& messageText, int badgeNumber, const Tizen::Base::String& launchArguments);
256 * Notifies the user with a request message. @n
257 * The notification request may have various pieces of information such as alert text, title text, launch arguments, and so on.
261 * @privilege %http://tizen.org/privilege/notification
263 * @return An error code
264 * @param[in] request The notification request
265 * @exception E_SUCCESS The method is successful.
266 * @exception E_INVALID_ARG The specified input parameter is invalid.
267 * @exception E_OPERATION_FAILED The operation has failed.
268 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
270 result Notify(const NotificationRequest& request);
273 * The user who is identified with the @c appId is notified with a request message. @n
274 * The request may have various pieces of information such as alert text, title text, launch arguments, and so on.
278 * @privilege %http://tizen.org/privilege/notification @n
279 * (%http://tizen.org/privilege/notificationmanager is deprecated.)
281 * @return An error code
282 * @param[in] appId The application ID
283 * @param[in] request The notification request
284 * @exception E_SUCCESS The method is successful.
285 * @exception E_APP_NOT_INSTALLED The application is not installed.
286 * @exception E_INVALID_ARG The specified input parameter is invalid.
287 * @exception E_OPERATION_FAILED The operation has failed.
288 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
290 result NotifyByAppId(const Tizen::App::AppId& appId, const NotificationRequest& request);
293 * Removes the notification message.
297 * @privilege %http://tizen.org/privilege/notification
299 * @return An error code
300 * @exception E_SUCCESS The method is successful.
301 * @exception E_OPERATION_FAILED The operation has failed.
302 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
303 * @remarks This method returns @c E_SUCCESS when there is no outstanding notification.
305 result RemoveNotification(void);
308 * Removes the notification message on behalf of the specified application.
312 * @privilege %http://tizen.org/privilege/notification @n
313 * (%http://tizen.org/privilege/notificationmanager is deprecated.)
315 * @return An error code
316 * @param[in] appId The application ID
317 * @exception E_SUCCESS The method is successful.
318 * @exception E_APP_NOT_INSTALLED The application is not installed.
319 * @exception E_OPERATION_FAILED The operation has failed.
320 * @exception E_PRIVILEGE_DENIED The application did not have the privilege to call this method.
321 * @remarks Although there is no outstanding notification for the calling application, this method returns @c E_SUCCESS.
323 result RemoveNotificationByAppId(const Tizen::App::AppId& appId);
326 * Notifies the user about the ongoing activity using a message.
330 * @privilege %http://tizen.org/privilege/notification
332 * @return An error code
333 * @param[in] messageText The notification message
334 * @exception E_SUCCESS The method is successful.
335 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
336 * - The specified input parameter is invalid. @n
337 * - The specified @c messageText is empty or the length of @c messageText is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
338 * @exception E_OPERATION_FAILED The operation has failed.
339 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
341 result NotifyOngoingActivity(const Tizen::Base::String& messageText);
344 * Notifies the user about the ongoing activity using a message. @n
345 * If the user selects the message, @c launchArguments is delivered to the application. @n
346 * @c launchArguments is delivered as the value of the %http://tizen.org/appcontrol/data/notification key
347 * for Tizen::App::IAppControlProviderEventListener::OnAppControlRequestReceived().
351 * @privilege %http://tizen.org/privilege/notification
353 * @return An error code
354 * @param[in] messageText The notification message
355 * @param[in] launchArguments The launch arguments for the application
356 * @exception E_SUCCESS The method is successful.
357 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
358 * - A specified input parameter is invalid. @n
359 * - The specified @c messageText is empty or the length of @c messageText is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH. @n
360 * - The specified @c launchArguments is empty or the length of @c launchArguments is greater than Shell::MAX_NOTIFICATION_LAUNCH_ARGUMENTS_LENGTH.
361 * @exception E_OPERATION_FAILED The operation has failed.
362 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
364 result NotifyOngoingActivity(const Tizen::Base::String& messageText, const Tizen::Base::String& launchArguments);
367 * Notifies the user about the ongoing activity using a request message. @n
368 * The request may have various pieces of information such as alert text, title text, launch arguments, and so on.
372 * @privilege %http://tizen.org/privilege/notification
374 * @return An error code
375 * @param[in] request The notification request
376 * @exception E_SUCCESS The method is successful.
377 * @exception E_INVALID_ARG The specified input parameter is invalid.
378 * @exception E_OPERATION_FAILED The operation has failed.
379 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
381 result NotifyOngoingActivity(const NotificationRequest& request);
384 * Notifies the user about the ongoing activity using a request message. @n
385 * The request may have various information like alert text, title text, launch arguments, and so on.
389 * @privilege %http://tizen.org/privilege/notification @n
390 * (%http://tizen.org/privilege/notificationmanager is deprecated.)
392 * @return An error code
393 * @param[in] appId The application ID
394 * @param[in] request The notification request
395 * @exception E_SUCCESS The method is successful.
396 * @exception E_INVALID_ARG The specified input parameter is invalid.
397 * @exception E_APP_NOT_INSTALLED The application is not installed.
398 * @exception E_OPERATION_FAILED The operation has failed.
399 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
401 result NotifyOngoingActivityByAppId(const Tizen::App::AppId& appId, const NotificationRequest& request);
404 * Removes the notification message for the ongoing activity.
408 * @privilege %http://tizen.org/privilege/notification
410 * @return An error code
411 * @exception E_SUCCESS The method is successful.
412 * @exception E_OPERATION_FAILED The operation has failed.
413 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
414 * @remarks This method returns @c E_SUCCESS when there is no outstanding notification.
416 result RemoveOngoingActivityNotification(void);
419 * Removes the notification message for ongoing activity on behalf of the specified application.
423 * @privilege %http://tizen.org/privilege/notification @n
424 * (%http://tizen.org/privilege/notificationmanager is deprecated.)
426 * @return An error code
427 * @param[in] appId The application ID
428 * @exception E_SUCCESS The method is successful.
429 * @exception E_APP_NOT_INSTALLED The application is not installed.
430 * @exception E_OPERATION_FAILED The operation has failed.
431 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
432 * @remarks Although there is no outstanding notification for the calling application, this method returns @c E_SUCCESS.
434 result RemoveOngoingActivityNotificationByAppId(const Tizen::App::AppId& appId);
437 * Gets the badge number of the application icon mentioned in the @c appId.
441 * @privilege %http://tizen.org/privilege/notification @n
442 * (%http://tizen.org/privilege/notificationmanager is deprecated.)
444 * @return The current badge number if the method is successful, @n
445 * else @c -1 if the method fails
446 * @param[in] appId The application ID
447 * @exception E_SUCCESS The method is successful.
448 * @exception E_OPERATION_FAILED The operation has failed.
449 * @exception E_APP_NOT_INSTALLED The application is not installed.
450 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
451 * @remarks The specific error code can be accessed using the GetLastResult() method. @n
454 int GetBadgeNumberByAppId(const Tizen::App::AppId& appId);
457 * Notifies the user with a message. @n
458 * It will disappear in a few seconds.
462 * @privilege %http://tizen.org/privilege/notification
464 * @return An error code
465 * @param[in] messageText The notification message
466 * @exception E_SUCCESS The method is successful.
467 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
468 * - The specified input parameter is invalid.
469 * - The specified @c messageText is empty or the length of @c messageText is greater than Shell::MAX_NOTIFICATION_MESSAGE_LENGTH.
470 * @exception E_OPERATION_FAILED The operation has failed.
471 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
472 * @remarks The message is displayed in the status bar.
474 result NotifyTextMessage(const Tizen::Base::String& messageText);
477 * Notifies the user using a request message and try implicit AppControl resolution when the user selects the message on the notification area. @n
478 * The request may have various information like alert text, title text, launch arguments, and so on.
482 * @privilege %http://tizen.org/privilege/notification
484 * @return An error code
485 * @param[in] operationId The operation ID
486 * @param[in] pUriData A pointer to the URI data
487 * @param[in] pDataType A pointer to the MIME type (RFC 2046) data
488 * @param[in] pExtraData A pointer to an argument map of key and value pair where the key is of type Tizen::Base::String and the value is of type %Tizen::Base::String to deliver to the resolved application @n
489 * The maximum size is @c 16 kilo bytes.
490 * @param[in] request The notification request
491 * @exception E_SUCCESS The method is successful.
492 * @exception E_INVALID_ARG The specified input parameter is invalid.
493 * @exception E_OPERATION_FAILED The operation has failed.
494 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
495 * @remarks For more information on the implicit AppControl resolution, see <a href="../org.tizen.native.appprogramming/html/guide/app/resolving_appcontrols.htm">here</a>.
498 result NotifyByAppControl(const Tizen::Base::String& operationId, const Tizen::Base::String* pUriData, const Tizen::Base::String* pDataType,
499 const Tizen::Base::Collection::IMap* pExtraData, const NotificationRequest& request);
502 * Notifies the user about the ongoing activity using a request message and try implicit AppControl resolution when the user selects the message on the notification area. @n
503 * The request may have various information like alert text, title text, launch arguments, and so on.
507 * @privilege %http://tizen.org/privilege/notification
509 * @return An error code
510 * @param[in] operationId The operation ID
511 * @param[in] pUriData A pointer to the URI data
512 * @param[in] pDataType A pointer to the MIME type (RFC 2046) data
513 * @param[in] pExtraData A pointer to an argument map of key and value pair where the key is of type Tizen::Base::String and the value is of type %Tizen::Base::String to deliver to the resolved application @n
514 * The maximum size is @c 16 kilo bytes.
515 * @param[in] request The notification request
516 * @exception E_SUCCESS The method is successful.
517 * @exception E_INVALID_ARG The specified input parameter is invalid.
518 * @exception E_OPERATION_FAILED The operation has failed.
519 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
520 * @remarks For more information on the implicit AppControl resolution, see <a href="../org.tizen.native.appprogramming/html/guide/app/resolving_appcontrols.htm">here</a>.
522 result NotifyOngoingActivityByAppControl(const Tizen::Base::String& operationId, const Tizen::Base::String* pUriData, const Tizen::Base::String* pDataType,
523 const Tizen::Base::Collection::IMap* pExtraData, const NotificationRequest& request);
526 * Adds an IBadgeEventListener instance to the %NotificationManager instance. @n
527 * The listener gets notified when a badge number is updated. @n
531 * @return An error code
532 * @param[in] listener The listener to add
533 * @exception E_SUCCESS The method is successful.
534 * @exception E_OBJ_ALREADY_EXIST The listener is already added.
535 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
536 * @remarks Internally platform does not have the ownership of this pointer, so caller should manage the listener object properly.
537 * @see NotificationManager::Notify()
539 result AddBadgeEventListener(IBadgeEventListener& listener);
542 * Removes an IBadgeEventListener instance from the %NotificationManager instance.
546 * @return An error code
547 * @param[in] listener The listener to remove
548 * @exception E_SUCCESS The method is successful.
549 * @exception E_OBJ_NOT_FOUND The listener is not found.
550 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
551 * @remarks Internally platform does not have the ownership of this pointer, so caller should manage the listener object properly.
553 result RemoveBadgeEventListener(IBadgeEventListener& listener);
557 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
561 NotificationManager(const NotificationManager& rhs);
564 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
568 NotificationManager& operator =(const NotificationManager& rhs);
571 class _NotificationManagerImpl * __pNotificationManagerImpl;
573 friend class _NotificationManagerImpl;
574 }; // NotificationManager
578 #endif // _FSHELL_NOTIFICATION_MANAGER_H_