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         For information on how 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. @n
 159         * For full construction, the Construct() method must be called right after calling this constructor.
 160         *
 161         * @since                2.0
 162         */
 163         PushManager(void);
 164
 165    /**
 166         * This destructor overrides Tizen::Base::Object::~Object().
 167         *
 168         * @since                2.0
 169         */
 170         virtual ~PushManager(void);
 171
 172 public:
 173    /**
 174         * Initializes this instance of %PushManager with the specified parameters.
 175         *
 176         * @since                2.0
 177         * @privlevel    public
 178         * @privilege    %http://tizen.org/privilege/push
 179         *
 180         * @pre                  For information on how to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 181         * @feature              %http://tizen.org/feature/network.push
 182         * @return               An error code
 183         * @param[in]    managerListener                 The listener to receive the result of the %PushManager
 184         *                                       class asynchronous methods
 185         * @param[in]    eventListener                   The listener to receive the incoming push messages
 186         * @exception    E_SUCCESS               The method is successful.
 187         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 188         * @exception    E_SYSTEM                A system error has occurred.
 189         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 190         * @exception    E_UNSUPPORTED_OPERATION The Emulator or target device does not support the required feature. @b Since: @b 2.1
 191         *                                                                               For more information, see <a href="../org.tizen.gettingstarted/html/tizen_overview/application_filtering.htm">Application Filtering</a>.
 192         * @exception    E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 193         * @remarks              Before calling this method, check whether the feature is supported by
 194         *                               Tizen::System::SystemInfo::GetValue(const Tizen::Base::String&, bool&).
 195         */
 196         result Construct(IPushManagerListener& managerListener, IPushEventListener& eventListener);
 197
 198    /**
 199         * Registers the push messaging service for the current application. @n
 200         * The %RegisterPushService() method is asynchronous.
 201         *
 202         * @since                2.0
 203         * @privlevel    public
 204         * @privilege    %http://tizen.org/privilege/push
 205         *
 206         * @pre                  For information on how 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 has blocked the 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         * The %UnregisterPushService() method is asynchronous.
 222         *
 223         * @since                2.0
 224         * @privlevel    public
 225         * @privilege    %http://tizen.org/privilege/push
 226         *
 227         * @pre                  For information on how 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 has blocked the 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 is registered for the current application.
 242         *
 243         * @since                2.0
 244         *
 245         * @pre                  For information on how 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 the %GetUnreadMessagesN() 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                  For information on how 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 has blocked the application from calling this method. @b Since: @b 2.1
 268         * @remarks
 269         *                       - 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, the push message related to the
 271         *                         notification is delivered to the application as a launch argument.
 272         *                       - The launch arguments are the input parameters for Tizen::App::IAppControlProviderEventListener::OnAppControlRequestReceivedN().
 273         *                       - This method returns all the unread messages including the message delivered as a launch argument.
 274         * @see          Tizen::App::IAppControlProviderEventListener
 275         */
 276         Tizen::Base::Collection::IList* GetUnreadMessagesN(void);
 277
 278    /**
 279         * Sends the specified push message to a single recipient. @n
 280         * The %SendPushMessage() method is asynchronous.
 281         *
 282         * @since                2.0
 283         * @privlevel    public
 284         * @privilege    %http://tizen.org/privilege/push and %http://tizen.org/privilege/http @n
 285         *                               Both the privileges are required.
 286         *
 287         * @pre                  For information on how to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 288         *
 289         * @return               An error code
 290         * @param[in]    message                                 The push message
 291         * @param[in]    registrationId                  The registration ID of the recipient
 292         * @param[in]    appSecret                               The secret code of the application issued by the push server to authenticate the application
 293         * @param[out]   reqId                                   The request ID
 294         * @exception    E_SUCCESS                               The method is successful.
 295         * @exception    E_INVALID_ARG                   A specified input parameter is invalid.
 296         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 297         * @exception    E_SYSTEM                                A system error has occurred.
 298         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 299         * @exception    E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 300         * @see          IPushManagerListener::OnPushMessageSent()
 301         */
 302         result SendPushMessage(const PushMessage& message, const Tizen::Base::String& registrationId, const Tizen::Base::String& appSecret, RequestId& reqId);
 303
 304
 305    /**
 306         * Sends the specified push message to multiple recipients. @n
 307         * The %SendPushMessage() method is asynchronous.
 308         *
 309         * @since                2.0
 310         * @privlevel    public
 311         * @privilege    %http://tizen.org/privilege/push and %http://tizen.org/privilege/http @n
 312         *                               Both the privileges are required.
 313         *
 314         * @pre                  For information on how to use the push messaging service, see <a href="../org.tizen.native.appprogramming/html/guide/messaging/push_messaging.htm">Push Messaging Guide</a>.
 315         *
 316         * @return               An error code
 317         * @param[in]    message                                 The push message
 318         * @param[in]    registrationIdList              The list of registration IDs of the recipients
 319         * @param[in]    appSecret                               The secret code of the application issued by the push server to authenticate the application
 320         * @param[out]   reqId                                   The request ID
 321         * @exception    E_SUCCESS                               The method is successful.
 322         * @exception    E_INVALID_ARG                   A specified input parameter is invalid.
 323         * @exception    E_MAX_EXCEEDED                  The number of registration IDs has crossed the maximum limit.
 324         * @exception    E_OUT_OF_MEMORY                 The memory is insufficient.
 325         * @exception    E_SYSTEM                                A system error has occurred.
 326         * @exception    E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 327         * @exception    E_USER_NOT_CONSENTED    The user has blocked the application from calling this method. @b Since: @b 2.1
 328         * @remarks              The maximum limit can be checked by using GetMaxRecipientCount().
 329         * @see                  IPushManagerListener::OnPushMessageSent()
 330         */
 331         result SendPushMessage(const PushMessage& message, const Tizen::Base::Collection::IList& registrationIdList, const Tizen::Base::String& appSecret, RequestId& reqId);
 332
 333         /**
 334         * Gets the maximum number of recipients for push messages sent by the multiple SendPushMessage() method.
 335         *
 336         * @since                2.0
 337         *
 338         * @return               The maximum number of recipients
 339         */
 340         static int GetMaxRecipientCount(void);
 341
 342 private:
 343         /**
 344          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 345          *
 346          * @param[in]   rhs                     An instance of PushManager
 347          */
 348         PushManager(const PushManager& rhs);
 349
 350         /**
 351          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 352          *
 353          * @return              A reference to this instance
 354          * @param[in]   rhs                             An instance of PushManager
 355          */
 356         PushManager& operator =(const PushManager& rhs);
 357
 358 private:
 359         _PushManagerImpl* __pPushManagerImpl;
 360
 361         friend class _PushManagerImpl;
 362 }; // PushManager
 363
 364 } } // Tizen::Messaging
 365 #endif // _FMSG_PUSH_MANAGER_H_