inc/FMsgPushManager.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17 /**
  18  * @file                FMsgPushManager.h
  19  * @brief               This is the header file for the %PushManager class.
  20  *
  21  * This header file contains the declarations of the %PushManager class.
  22  */
  23
  24 #ifndef _FMSG_PUSH_MANAGER_H_
  25 #define _FMSG_PUSH_MANAGER_H_
  26
  27 #include <FBase.h>
  28 #include <FMsgIPushManagerListener.h>
  29 #include <FMsgIPushEventListener.h>
  30
  31 namespace Tizen { namespace Messaging
  32 {
  33 class _PushManagerImpl;
  34
  35 /**
  36 * @class        PushManager
  37 * @brief        This class provides methods to use the push messaging service.
  38 *
  39 * @since        2.0
  40 *
  41 * @remarks      If an application package contains multiple applications, only one application can use the push messaging service at a time.
  42 *
  43 * @pre          In order to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
  44 *
  45 *
  46 * The %PushManager class provides methods to register, unregister, and use the push messaging service.
  47 *
  48 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/messaging.htm">Messaging Guide</a>.
  49 *
  50 * @see      Tizen::Shell::NotificationManager
  51 *
  52 * The following example demonstrates how to use the %PushManager class.
  53 *
  54 * @code
  55 *
  56         #include <FBase.h>
  57         #include <FMessaging.h>
  58
  59         using namespace Tizen::Base;
  60         using namespace Tizen::Messaging;
  61
  62         // Creates a listener to override the methods of IPushManagerListener and IPushEventListener.
  63         class MyClass
  64                 : public Object
  65                 , public IPushEventListener
  66                 , public IPushManagerListener
  67         {
  68         public:
  69                 MyClass(void) {}
  70                 ~MyClass(void) {}
  71
  72                 //IPushManagerListener and IPushEventListener
  73                 void OnPushServiceRegistered(RequestId reqId, const String& registrationId, result r, const String& errorCode, const String& errorMsg);
  74                 void OnPushServiceUnregistered(RequestId reqId, result r, const String& errorCode, const String& errorMsg);
  75                 void OnPushMessageReceived(const PushMessage& message);
  76
  77                 void Initialize(void);
  78                 void EnablePushService(void);
  79                 void DisablePushService(void);
  80
  81         private:
  82                 PushManager* pPushManager;
  83         };
  84
  85         void
  86         MyClass::OnPushServiceRegistered(RequestId reqId, const String& registrationId, result r, const String& errorCode, const String& errorMsg)
  87         {
  88                 if (E_SUCCESS == r)
  89                 {
  90                         // The application must send registrationId to the application server.
  91                 }
  92                 else
  93                 {
  94                         // Error
  95                 }
  96         }
  97
  98         void
  99         MyClass::OnPushServiceUnregistered(RequestId reqId, result r, const String& errorCode, const String& errorMsg)
 100         {
 101                 // Do something
 102         }
 103
 104         void
 105         MyClass::OnPushMessageReceived(const PushMessage& message)
 106         {
 107                 // Do something
 108         }
 109
 110         void
 111         MyClass::Initialize(void)
 112         {
 113                 // Creates a PushManager instance.
 114                 pPushManager = new PushManager();
 115                 pPushManager->Construct(*this, *this);
 116         }
 117
 118         void
 119         MyClass::EnablePushService(void)
 120         {
 121                 RequestId reqId;
 122                 result r = E_SUCCESS;
 123
 124                 r = pPushManager->RegisterPushService(reqId);
 125                 if (IsFailed(r))
 126                 {
 127                         return;
 128                 }
 129
 130                 // The result of registration will be notified by IPushManagerListener::OnPushServiceRegistered().
 131         }
 132
 133         void
 134         MyClass::DisablePushService(void)
 135         {
 136                 // The application must notify the application server to stop sending push messages for this device.
 137
 138                 RequestId reqId;
 139                 result r = E_SUCCESS;
 140
 141                 r = pPushManager->UnregisterPushService(reqId);
 142                 if (IsFailed(r))
 143                 {
 144                         return;
 145                 }
 146
 147                 // The result of unregistration will be notified by IPushManagerListener::OnPushServiceUnregistered().
 148         }
 149
 150     *
 151     * @endcode
 152     */
 153 class _OSP_EXPORT_ PushManager
 154         : public Tizen::Base::Object
 155 {
 156 public:
 157         /**
 158          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 159          *
 160          * @since               2.0
 161          */
 162         PushManager(void);
 163
 164         /**
 165          * This destructor overrides Tizen::Base::Object::~Object().
 166          *
 167          * @since               2.0
 168          */
 169         virtual ~PushManager(void);
 170
 171 public:
 172         /**
 173         * Initializes this instance of the %PushManager class with the specified parameters.
 174         *
 175         * @since                2.0
 176         * @privlevel    public
 177         * @privilege    %http://tizen.org/privilege/push
 178         *
 179         * @pre                  In order to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 180         * @feature              %http://tizen.org/feature/network.push
 181         * @return               An error code
 182         * @param[in]    managerListener         A listener that receives the result of the %PushManager
 183         *                                   class asynchronous methods
 184         * @param[in]    eventListener           A listener that receives the incoming push messages
 185         * @exception    E_SUCCESS           The method is successful.
 186         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 187         * @exception    E_SYSTEM            A system error has occurred.
 188         * @exception    E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 189         * @exception    E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1
 190         *                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 191         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 192         * @remarks      Before calling this method, check whether the feature is supported by %Tizen::System::SystemInfo::GetValue() methods.
 193         * @see                  IPushManagerListener
 194         * @see                  IPushEventListener
 195         */
 196         result Construct(IPushManagerListener& managerListener, IPushEventListener& eventListener);
 197
 198         /**
 199         * Registers the push messaging service for the current application. @n
 200         * This method is asynchronous.
 201         *
 202         * @since                2.0
 203         * @privlevel    public
 204         * @privilege    %http://tizen.org/privilege/push
 205         *
 206         * @pre                  In order to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 207         *
 208         * @return               An error code
 209         * @param[out]   reqId                           The request ID
 210         * @exception    E_SUCCESS           The method is successful.
 211         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 212         * @exception    E_SYSTEM            A system error has occurred.
 213         * @exception    E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 214         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 215         * @see                  IPushManagerListener::OnPushServiceRegistered()
 216         */
 217         result RegisterPushService(RequestId& reqId);
 218
 219         /**
 220         * Unregisters the push messaging service for the current application. @n
 221         * This method is asynchronous.
 222         *
 223         * @since                2.0
 224         * @privlevel    public
 225         * @privilege    %http://tizen.org/privilege/push
 226         *
 227         * @pre                  In order to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 228         *
 229         * @return               An error code
 230         * @param[out]   reqId                           The request ID
 231         * @exception    E_SUCCESS           The method is successful.
 232         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 233         * @exception    E_SYSTEM            A system error has occurred.
 234         * @exception    E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 235         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 236         * @see                  IPushManagerListener::OnPushServiceUnregistered()
 237         */
 238         result UnregisterPushService(RequestId& reqId);
 239
 240         /**
 241         * Checks whether the push messaging service registration has been completed for the current application.
 242         *
 243         * @since                2.0
 244         *
 245         * @pre                  In order to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 246         *
 247         * @return               @c true if the registration is completed, @n
 248         *               else @c false
 249         */
 250         bool IsPushServiceRegistered(void) const;
 251
 252         /**
 253         * Gets the unread push messages. @n
 254         * If an application receives unread messages with this method, the messages are removed from the system.
 255         *
 256         * @since                2.0
 257         * @privlevel    public
 258         * @privilege    %http://tizen.org/privilege/push
 259         *
 260         * @pre                  In order to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 261         *
 262         * @return               A pointer to the list that contains unread push messages
 263         * @exception    E_SUCCESS                       The method is successful.
 264         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 265         * @exception    E_SYSTEM                        A system error has occurred.
 266         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 267         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 268         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 269         *               If the user launches the application using a ticker or a quick panel,
 270         *               the push message related to the notification is delivered to the application
 271         *               as a launch argument.
 272         *               The launch arguments are the input parameters for
 273         *               Tizen::App::IAppControlProviderEventListener::OnAppControlRequestReceivedN().
 274         *               This function returns all the unread messages including the message
 275         *               delivered as a launch argument.
 276         * @see                  Tizen::App::IAppControlProviderEventListener
 277         */
 278         Tizen::Base::Collection::IList* GetUnreadMessagesN(void);
 279
 280         /**
 281         * Sends the push message to a single recipient. @n
 282         * This method is asynchronous.
 283         *
 284         * @since                2.0
 285         * @privlevel    public
 286         * @privilege    %http://tizen.org/privilege/push and %http://tizen.org/privilege/http @n
 287         *                                                               Both privileges are required
 288         *
 289         * @pre                  In order to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 290         *
 291         * @return               An error code
 292         * @param[in]    message                         The push message
 293         * @param[in]    registrationId          The registration ID of the recipient
 294         * @param[in]    appSecret                       The secret code of the application issued by the push server to authenticate the application
 295         * @param[out]   reqId                           The request ID
 296         * @exception    E_SUCCESS                       The method is successful.
 297         * @exception    E_INVALID_ARG           A specified input parameter is invalid.
 298         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 299         * @exception    E_SYSTEM                        A system error has occurred.
 300         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 301         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 302         * @see                                                          IPushManagerListener::OnPushMessageSent()
 303         */
 304         result SendPushMessage(const PushMessage& message, const Tizen::Base::String& registrationId, const Tizen::Base::String& appSecret, RequestId& reqId);
 305
 306
 307         /**
 308         * Sends the push message to multiple recipients. @n
 309         * This method is asynchronous.
 310         *
 311         * @since                2.0
 312         * @privlevel    public
 313         * @privilege    %http://tizen.org/privilege/push and %http://tizen.org/privilege/http @n
 314         *                                                               Both privileges are required
 315         *
 316         * @pre                  In order to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 317         *
 318         * @return               An error code
 319         * @param[in]    message                         The push message
 320         * @param[in]    registrationIdList      The list of registration IDs of the recipients
 321         * @param[in]    appSecret                       The secret code of the application issued by the push server to authenticate the application
 322         * @param[out]   reqId                           The request ID
 323         * @exception    E_SUCCESS                       The method is successful.
 324         * @exception    E_INVALID_ARG           A specified input parameter is invalid.
 325         * @exception    E_MAX_EXCEEDED          The number of registration IDs has crossed the maximum limit.
 326         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 327         * @exception    E_SYSTEM                        A system error has occurred.
 328         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 329         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 330         * @remarks      The maximum limit can be checked by using GetMaxRecipientCount().
 331         * @see                                                          IPushManagerListener::OnPushMessageSent()
 332         */
 333         result SendPushMessage(const PushMessage& message, const Tizen::Base::Collection::IList& registrationIdList, const Tizen::Base::String& appSecret, RequestId& reqId);
 334
 335         /**
 336         * Gets the maximum number of recipients sent by a multiple SendPushMessage() method.
 337         *
 338         * @since                2.0
 339         *
 340         * @return               The maximum number of recipients
 341         */
 342         static int GetMaxRecipientCount(void);
 343
 344 private:
 345         /**
 346          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 347          *
 348          * @param[in]   rhs                     An instance of PushManager
 349          */
 350         PushManager(const PushManager& rhs);
 351
 352         /**
 353          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 354          *
 355          * @return              A reference to this instance
 356          * @param[in]   rhs                             An instance of PushManager
 357          */
 358         PushManager& operator =(const PushManager& rhs);
 359
 360 private:
 361         _PushManagerImpl* __pPushManagerImpl;
 362
 363         friend class _PushManagerImpl;
 364 }; // PushManager
 365
 366 } } // Tizen::Messaging
 367 #endif // _FMSG_PUSH_MANAGER_H_