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
 193         *                       Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 194         * @see                  IPushManagerListener
 195         * @see                  IPushEventListener
 196         */
 197         result Construct(IPushManagerListener& managerListener, IPushEventListener& eventListener);
 198
 199         /**
 200         * Registers the push messaging service for the current application. @n
 201         * This method is asynchronous.
 202         *
 203         * @since                2.0
 204         * @privlevel    public
 205         * @privilege    %http://tizen.org/privilege/push
 206         *
 207         * @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>.
 208         *
 209         * @return               An error code
 210         * @param[out]   reqId                           The request ID
 211         * @exception    E_SUCCESS           The method is successful.
 212         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 213         * @exception    E_SYSTEM            A system error has occurred.
 214         * @exception    E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 215         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 216         * @see                  IPushManagerListener::OnPushServiceRegistered()
 217         */
 218         result RegisterPushService(RequestId& reqId);
 219
 220         /**
 221         * Unregisters the push messaging service for the current application. @n
 222         * This method is asynchronous.
 223         *
 224         * @since                2.0
 225         * @privlevel    public
 226         * @privilege    %http://tizen.org/privilege/push
 227         *
 228         * @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>.
 229         *
 230         * @return               An error code
 231         * @param[out]   reqId                           The request ID
 232         * @exception    E_SUCCESS           The method is successful.
 233         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 234         * @exception    E_SYSTEM            A system error has occurred.
 235         * @exception    E_PRIVILEGE_DENIED  The application does not have the privilege to call this method.
 236         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 237         * @see                  IPushManagerListener::OnPushServiceUnregistered()
 238         */
 239         result UnregisterPushService(RequestId& reqId);
 240
 241         /**
 242         * Checks whether the push messaging service registration has been completed for the current application.
 243         *
 244         * @since                2.0
 245         *
 246         * @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>.
 247         *
 248         * @return               @c true if the registration is completed, @n
 249         *               else @c false
 250         */
 251         bool IsPushServiceRegistered(void) const;
 252
 253         /**
 254         * Gets the unread push messages. @n
 255         * If an application receives unread messages with this method, the messages are removed from the system.
 256         *
 257         * @since                2.0
 258         * @privlevel    public
 259         * @privilege    %http://tizen.org/privilege/push
 260         *
 261         * @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>.
 262         *
 263         * @return               A pointer to the list that contains unread push messages
 264         * @exception    E_SUCCESS                       The method is successful.
 265         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 266         * @exception    E_SYSTEM                        A system error has occurred.
 267         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 268         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 269         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 270         *               If the user launches the application using a ticker or a quick panel,
 271         *               the push message related to the notification is delivered to the application
 272         *               as a launch argument.
 273         *               The launch arguments are the input parameters for
 274         *               Tizen::App::IAppControlProviderEventListener::OnAppControlRequestReceivedN().
 275         *               This function returns all the unread messages including the message
 276         *               delivered as a launch argument.
 277         * @see                  Tizen::App::IAppControlProviderEventListener
 278         */
 279         Tizen::Base::Collection::IList* GetUnreadMessagesN(void);
 280
 281         /**
 282         * Sends the push message to a single recipient. @n
 283         * This method is asynchronous.
 284         *
 285         * @since                2.0
 286         * @privlevel    public
 287         * @privilege    %http://tizen.org/privilege/push and %http://tizen.org/privilege/http @n
 288         *                                                               Both privileges are required
 289         *
 290         * @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>.
 291         *
 292         * @return               An error code
 293         * @param[in]    message                         The push message
 294         * @param[in]    registrationId          The registration ID of the recipient
 295         * @param[in]    appSecret                       The secret code of the application issued by the push server to authenticate the application
 296         * @param[out]   reqId                           The request ID
 297         * @exception    E_SUCCESS                       The method is successful.
 298         * @exception    E_INVALID_ARG           A specified input parameter is invalid.
 299         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 300         * @exception    E_SYSTEM                        A system error has occurred.
 301         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 302         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 303         * @see                                                          IPushManagerListener::OnPushMessageSent()
 304         */
 305         result SendPushMessage(const PushMessage& message, const Tizen::Base::String& registrationId, const Tizen::Base::String& appSecret, RequestId& reqId);
 306
 307
 308         /**
 309         * Sends the push message to multiple recipients. @n
 310         * This method is asynchronous.
 311         *
 312         * @since                2.0
 313         * @privlevel    public
 314         * @privilege    %http://tizen.org/privilege/push and %http://tizen.org/privilege/http @n
 315         *                                                               Both privileges are required
 316         *
 317         * @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>.
 318         *
 319         * @return               An error code
 320         * @param[in]    message                         The push message
 321         * @param[in]    registrationIdList      The list of registration IDs of the recipients
 322         * @param[in]    appSecret                       The secret code of the application issued by the push server to authenticate the application
 323         * @param[out]   reqId                           The request ID
 324         * @exception    E_SUCCESS                       The method is successful.
 325         * @exception    E_INVALID_ARG           A specified input parameter is invalid.
 326         * @exception    E_MAX_EXCEEDED          The number of registration IDs has crossed the maximum limit.
 327         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 328         * @exception    E_SYSTEM                        A system error has occurred.
 329         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 330         * @exception    E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1
 331         * @remarks      The maximum limit can be checked by using GetMaxRecipientCount().
 332         * @see                                                          IPushManagerListener::OnPushMessageSent()
 333         */
 334         result SendPushMessage(const PushMessage& message, const Tizen::Base::Collection::IList& registrationIdList, const Tizen::Base::String& appSecret, RequestId& reqId);
 335
 336         /**
 337         * Gets the maximum number of recipients sent by a multiple SendPushMessage() method.
 338         *
 339         * @since                2.0
 340         *
 341         * @return               The maximum number of recipients
 342         */
 343         static int GetMaxRecipientCount(void);
 344
 345 private:
 346         /**
 347          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 348          *
 349          * @param[in]   rhs                     An instance of PushManager
 350          */
 351         PushManager(const PushManager& rhs);
 352
 353         /**
 354          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 355          *
 356          * @return              A reference to this instance
 357          * @param[in]   rhs                             An instance of PushManager
 358          */
 359         PushManager& operator =(const PushManager& rhs);
 360
 361 private:
 362         _PushManagerImpl* __pPushManagerImpl;
 363
 364         friend class _PushManagerImpl;
 365 }; // PushManager
 366
 367 } } // Tizen::Messaging
 368 #endif // _FMSG_PUSH_MANAGER_H_