From: Szymon Jastrzebski Date: Mon, 14 Nov 2016 09:06:52 +0000 (+0100) Subject: [Push] Guide and apireference updated X-Git-Tag: tizen_3.0/TD_SYNC/20161201~14^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F83%2F97483%2F18;p=sdk%2Fonline-doc.git [Push] Guide and apireference updated PS3: [LB] Reviewed PS5: [LB] Reviewed further changes PS6: [LB] Tagging fix PS8: [LB] Checked query answer PS14: [LB] Reviewed further changes PS18: [LB] Reviewed once more... will this ever end... :-) Change-Id: I3497dd82c2e310a92fb53ad33c1dbe0f75063467 Signed-off-by: Szymon Jastrzebski --- diff --git a/org.tizen.guides/html/web/messaging/push_w.htm b/org.tizen.guides/html/web/messaging/push_w.htm index be61b0f..6fb3e42 100644 --- a/org.tizen.guides/html/web/messaging/push_w.htm +++ b/org.tizen.guides/html/web/messaging/push_w.htm @@ -34,6 +34,7 @@
  • Registering to the Push Service
  • Receiving Push Notifications
  • Retrieving Missed Push Messages
    • +
  • Handling a Launch by the Push Service
  • Retrieving Messages When Launched by the Push Service

    • Related Info

    @@ -47,7 +48,7 @@

    Push Notification

    -

    Tizen enables you to receive notifications from a push server. The push service is a client daemon that maintains a permanent connection between the device and the push server. Push enables you to push events from an application server to your application on a Tizen device. Connection with the push server is used to deliver push notifications to the application, and process the registration and deregistration requests.

    +

    Tizen enables you to receive notifications from a push server. The push service is a client daemon that maintains a permanent connection between the device and the push server. Push enables you to push events from an application server to your application on a Tizen device. Connection with the push service is used to deliver push notifications to the application, and process the registration and deregistration requests.

    This feature is supported in mobile and wearable applications only.

    @@ -66,11 +67,11 @@
  • Registering to the push service

    You can register or deregister the application for the push service. If the registration process is successful, it returns the registration identifier through the PushRegisterSuccessCallback listener (in mobile and wearable applications). The application server needs the registration ID to send notifications to the application installed on a specific device.

  • Receiving push notifications -

    You can connect to the push service and start receiving push notifications with the connectService() method. You must pass the PushNotificationCallback listener (in mobile and wearable applications) as a parameter in the method to receive push notifications.

    • +

    You can connect to the push service and start receiving push notifications with the connectService() method up to Tizen 2.4, or with connect() method since Tizen 3.0. Up to Tizen 2.4, you must pass the PushNotificationCallback listener (in mobile and wearable applications) as a parameter in the method to receive push notifications. Since Tizen 3.0, you must pass the PushRegistrationStateChangeCallback (in mobile applications) and PushNotificationCallback callbacks as parameters in the method. The first callback is called when the registration change state changes. This callback is called at least once, just after the connection is established. The second callback is called when notification messages arrive. You can also pass the ErrorCallback as a parameter to be called if the connection request fails.

  • Retrieving missed push messages

    While the application is not running, messages cannot be delivered. You can retrieve such missed push messages later on.

    • -
  • Getting push messages when the application is launched by the push service -

    The application can be launched by the push service. In that case, you can get the last message delivered from the push service.

    • +
  • Reacting to a launch by the push service +

    The application can be launched by the push service. In that case, you must determine the reason for the launch, and react to it appropriately. If the application is launched due to a notification, you can retrieve and read the last message delivered from the push service.

  • Sending push notifications

    The push service implements the RESTful open API for sending a push message. For more information on sending push notifications, see Push Server.

    • @@ -100,10 +101,11 @@

    Become familiar with the Push API basics by learning about:

    Prerequisites

    @@ -191,19 +193,22 @@ - -

    Registering to the Push Service

    - -

    To receive push notifications, you must learn how to register your application to the push service:

    +

    To receive push notifications, you must learn how to register your application to the push service:

    +
      +
    • +

      Up to Tizen 2.4:

      1. Define event handlers for the registration results:

        +/* Define the data to be used when this process is launched by the notification service */
+var service = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/push_test");
+
 /* Define the error callback */
 function errorCallback(response)
 {
-   console.log("The following error occurred: " +  response.name);
+   console.log("The following error occurred: " + response.name);
 }
 
 /* Define the registration success callback */
@@ -213,15 +218,61 @@ function registerSuccessCallback(id)
 }
        2. -

      2. Register the application for the service with the register() method. This operation only needs to be done once.

        +

      3. Register the application for the service with the register() method. This operation has to be done only once.

         /* Request application registration */
-tizen.push.register(registerSuccessCallback, errorCallback);
+tizen.push.registerService(service, registerSuccessCallback, errorCallback);
        -

        If the registration is successful, the registerSuccessCallback() is called, and the registration ID is passed as a parameter.

        4. -
      +
      • + + +
    • +

      Since Tizen 3.0:

      +

      Before registering, you must connect to the push service:

      +
        +

      1. Define event handlers:

        + 
        +/* Define the error callback */
+function errorCallback(response)
+{
+   console.log("The following error occurred: " + response.name);
+}
+
+/* Define the registration success callback */
+function registerSuccessCallback(id)
+{
+   console.log("Registration succeeded with id: " + id);
+}
+
+/* Define the state change callback */
+function stateChangeCallback(state)
+{
+   console.log("The state is changed to: " + state);
+
+   if (state == "UNREGISTERED")
+   {
+      /* Request application registration */
+      tizen.push.register(registerSuccessCallback, errorCallback);
+   }
+}
 
- 
        Any time after a successful registration, you can get the registration ID using the getRegistrationId() method:
        
+/* Define the notification callback */
+function notificationCallback(notification)
+{
+   console.log("A notification arrives.");
+}
+
        +
        2. +

      2. Connect to the push service with the connect() method. The register() method is called in the stateChangeCallback() callback. This operation has to be done only once.

        + 
        +/* Connect to push service */
+tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
+
        +
        3. +
      +
      • +
    +

    If the registration is successful, the registerSuccessCallback() callback is called, and the registration ID is passed as a parameter. Any time after a successful registration, you can get the registration ID using the getRegistrationId() method:

     var registrationId = tizen.push.getRegistrationId();
 if (registrationId != null)
@@ -229,6 +280,8 @@ if (registrationId != null)
    console.log("The registration id: " + registrationId);
 }
    +

    Since Tizen 3.0, you must connect to the push service before getting the registration ID.

    +

    Receiving Push Notifications

    @@ -260,12 +313,20 @@ if (registrationId != null) 
     function errorCallback(response)
 {
-   console.log('The following error occurred: ' +  response.name);
+   console.log('The following error occurred: ' + response.name);
 }
 
 function notificationCallback(message)
 {
-   console.log("New push message : " + message.alertMessage + ", date : " + message.date + ", data : " + message.appData);
+   console.log("New push message: " + message.alertMessage + ", date: " + message.date + ", data: " + message.appData);
+}
+
+/* Since Tizen 3.0, you must provide PushRegistrationStateChangeCallback */
+/* Define the state change callback */
+
+function stateChangeCallback(state)
+{
+   console.log("The state is changed to: " + state);
 }

    The following table lists the fields available in the notification callback.

    @@ -325,25 +386,43 @@ function notificationCallback(message)
  • -

    Request the push service connection with the connectService() method:

    +

    Request the push service connection:

    +
      +
    • +

      Up to Tizen 2.4:

       tizen.push.connectService(notificationCallback, errorCallback);
      +
      • +
    • +

      Since Tizen 3.0:

      +
      +tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
+
      +
      • +

    If the connection is established, you start receiving push notifications.

    • -

    To stop listening for new push messages, call the disconnectService() method:

    +

    To stop listening for new push messages, call the disconnectService() method up to Tizen 2.4 or the disconnect() method since Tizen 3.0:

    +/* Up to Tizen 2.4 */
 tizen.push.disconnectService();
+
+/* Since Tizen 3.0 */
+tizen.push.disconnect();

    To learn how send a simple push notification to the device, see Sending Push Notifications. For advanced features in sending notifications, see the Push Server guide for server developers.

    Retrieving Missed Push Messages

    While the application is not running, messages cannot be delivered. To retrieve such missed push messages:

    +
      +
    • +

      Up to Tizen 2.4:

        -
      1. Call the connectService() method to connect to the Tizen push server and receive push notifications, before calling the getUnreadNotifications() method. +
      2. Call the connectService() method to connect to the Tizen push server and receive new push notifications: 
         /* Method to be called when the notification message arrives */
 function notificationCallback(message)
@@ -352,38 +431,124 @@ function notificationCallback(message)
 }
 
 tizen.push.connectService(notificationCallback);
-
        -
        3. -
      3. Receive the unread messages: - 
        +
        +
        4. +
      4. Retrieve any unread messages: +
         tizen.push.getUnreadNotifications();
        -

        The notification callback passed to the connectService() method is called for every unread message.

        -
        5. + +
      +
      • +
    • + +

      Since Tizen 3.0:

      +

      Call the connect() method to connect to the Tizen push server, and retrieve any unread messages with the getUnreadNotifications() method in the state change callback when the application is registered:

      +
      +/* Define the error callback */
+function errorCallback(response)
+{
+   console.log("The following error occurred: " + response.name);
+}
+
+/* Define the registration success callback */
+function registerSuccessCallback(id)
+{
+   console.log("Registration succeeded with id: " + id);
+}
+
+/* Define the state change callback */
+function stateChangeCallback(state)
+{
+   console.log("The state is changed to: " + state);
+
+   if (state === "UNREGISTERED")
+   {
+      /* Request application registration */
+      tizen.push.register(registerSuccessCallback, errorCallback);
+   }
+   else if (state === "REGISTERED")
+   {
+      /* Gets unread push notifications */
+      tizen.push.getUnreadNotifications();
+   }
+}
+
+/* Define the notification callback */
+function notificationCallback(notification)
+{
+   console.log("A notification arrives.");
+}
+
+tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
+
      +
      • + +
    +

    The notification callback passed to the connectService() (up to Tizen 2.4) or connect() (since Tizen 3.0) method is called for every unread message.

    + +

    Handling a Launch by the Push Service

    +

    If the application is launched by the push service, determine the reason for the application launch and react to it appropriately:

    + +
      +
    1. Get the requested application control with the getRequestedAppControl() method: +
      +var requestedAppControl = tizen.application.getCurrentApplication().getRequestedAppControl().appControl;
+
      2. +
    2. Determine the reason for the application launch. If the reason for the launch is a notification, retrieve the latest push message. +
      +for (var i = 0; i < requestedAppControl.data.length; ++i)
+{
+   if (requestedAppControl.data[i].key === 'http://tizen.org/appcontrol/data/push/launch_type')
+   {
+      /* Launch type is 'registration_change' or 'notification' */
+      var appData = requestedAppControl.data[i].value[0];
+      console.log('launch_type: ' + appData);
+      if (appData === 'registration_change')
+      {
+         /* Launched due to change in the registration state */
+      }
+      else if (appData === 'notification')
+      {
+         /* Launched due to a notification */
+         try
+         {
+            /* Retrieve the latest message */
+            var pushMessage = tizen.push.getPushMessage();
+            /* Handle the retrieved message */
+         }
+         catch (error)
+         {
+            console.log(error.name + ': ' + error.message);
+         }
+      }
+   }
+}
+

    Retrieving Messages When Launched by the Push Service

    -

    If the application is launched by the push service, use the getPushMessage() method to return the last undelivered push message. If none exists, it returns NULL.

    +

    If the application is launched by the push service due to a notification, use the getPushMessage() method to return the last undelivered push message. If none exists, the function returns NULL.

    -

    To retrieve the last message:

    +

    To retrieve and read the last message:

    1. Retrieve the message: 
      -var message = tizen.push.getPushMessage();
+var pushMessage = tizen.push.getPushMessage();
    2. Read the message content: 
      -if (message)
+if (pushMessage)
 {
-   console.log('notification received on ' + message.date + ' from: ' + message.sender);
+   console.log('notification received on ' + pushMessage.date + ' from: ' + pushMessage.sender);
    console.log('Details:');
-   console.log(' - data: ' + message.appData);
-   console.log(' - alert message: ' + message.alertMessage);
-   console.log(' - message: ' + message.message);
-   console.log(' - session: ' + message.sessionInfo);
-   console.log(' - request ID: ' + message.requestId);
-   console.log(' - type: ' + message.type);
+   console.log(' - data: ' + pushMessage.appData);
+   console.log(' - alert message: ' + pushMessage.alertMessage);
+   console.log(' - message: ' + pushMessage.message);
+   console.log(' - session: ' + pushMessage.sessionInfo);
+   console.log(' - request ID: ' + pushMessage.requestId);
+   console.log(' - type: ' + pushMessage.type);
 }
    @@ -410,4 +575,4 @@ var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga - \ No newline at end of file + diff --git a/org.tizen.web.apireference/html/device_api/mobile/tizen/push.html b/org.tizen.web.apireference/html/device_api/mobile/tizen/push.html index caa056e..62b5f3d 100644 --- a/org.tizen.web.apireference/html/device_api/mobile/tizen/push.html +++ b/org.tizen.web.apireference/html/device_api/mobile/tizen/push.html @@ -13,34 +13,35 @@ The Push API provides functionality for receiving push notifications from the Tizen push server. The push service is a client daemon that maintains a permanent connection -between your device and the Tizen push server in order to process your registration -and deregistration requests and deliver push notifications to applications on a device. +between your device and the Tizen push server. Connection with push service is used to deliver push notifications +to the application, and process the registration and deregistration requests.

    -If the application is connected, the push service passes the notification data over -the connection. Otherwise, the push service posts a UI notification with the data. -It will be delivered when a user launches the application by selecting the posting. -

    -

    To receive push notifications, follow the steps below:

    • -Get administrative permission for an application on your device
      • -
    • -Register the application
      • +Connecting to the push service
    • -Connect to the push service
      • +Registering your application, if the application has not been registered yet
    • -Get notification data
      • +Getting notification data

    -To use Push features, you must register to the Push service. +For more information on the Push features, see Push Guide.

    -For more information on the Push features, see Push Guide. +To use Push features the application needs the permission to access the Tizen Push servers.

    +

    +Service Limitation:

    +
      +
    • +Size of a push message is limited: alertMessage up to 127 bytes, and appData (payload data) less than 1 KB.
      • +
    • +Push service does not guarantee delivery and order of push messages.
      • +

    Since: @@ -48,8 +49,14 @@ For more information on the Push features, see -

  • 1. Type Definitions +
  • 1. Type Definitions
  • 2. Interfaces
    • @@ -88,8 +97,10 @@ For more information on the Push features, see register (PushRegisterSuccessCallback successCallback, optional ErrorCallback? errorCallback)
    void unregisterService (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
    void unregister (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
    -
    void connectService (PushNotificationCallback notificationCallback)
    -
    void disconnectService ()
    +
    void connectService (PushNotificationCallback notificationCallback)
    +
    void connect (PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback)
    +
    void disconnectService ()
    +
    void disconnect ()
    PushRegistrationId getRegistrationId ()
    void getUnreadNotifications ()
    @@ -106,6 +117,10 @@ For more information on the Push features, see onsuccess (PushRegistrationId id)
    +PushRegistrationStateChangeCallback +
    void onsuccess (PushRegistrationState state)
    + + PushNotificationCallback
    void onsuccess (PushMessage message)
    @@ -124,6 +139,25 @@ For more information on the Push features, see +

    1.2. PushRegistrationState

    +
    + A push registration state. +
    +
        enum PushRegistrationState {"REGISTERED", "UNREGISTERED"};
    +

    + Since: + 3.0 +

    +
    +
      +
    • +REGISTERED - The application is registered to the push server.
      • +
    • +UNREGISTERED - The application is not registered to the push server.
      • +
    +
    +

    2. Interfaces

    @@ -161,12 +195,17 @@ The tizen.push object allows access to the functionality of the Push AP optional ErrorCallback? errorCallback) raises(WebAPIException); void unregister(optional SuccessCallback? successCallback, - optional ErrorCallback? errorCallback) raises(WebAPIException); + optional ErrorCallback? errorCallback) raises(WebAPIException); void connectService(PushNotificationCallback notificationCallback) raises(WebAPIException); + void connect(PushRegistrationStateChangeCallback stateChangeCallback, + PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); + void disconnectService() raises(WebAPIException); + void disconnect() raises(WebAPIException); + PushRegistrationId getRegistrationId() raises(WebAPIException); void getUnreadNotifications() raises(WebAPIException); @@ -216,7 +255,7 @@ UnknownError - If any other error occurs. http://tizen.org/privilege/push

    Remark : - In order to use the push messaging service, see Push Messaging Guide. + In order to use the push messaging service, see Push Guide.

    Parameters:

    @@ -263,7 +302,7 @@ var service = new tizen.ApplicationControl("http://tizen.org/appcontrol/operatio /* Defines the error callback */ function errorCallback(response) { -   console.log('The following error occurred: ' + response.name); +   console.log('The following error occurred: ' + response.name); } /* Defines the registration success callback */ @@ -296,9 +335,16 @@ The ErrorCallback() is launched with these error types:

    • +TimeoutError - If the operation timed out.
      • +
    • AbortError - If the operation cannot be finished properly.
    +
    +

    +The connect() method must be called before calling the register() method. +

    +

    Privilege level: public @@ -307,16 +353,19 @@ AbortError - If the operation cannot be finished properly. Privilege: http://tizen.org/privilege/push

    +

    Remark : + In order to use the push messaging service, see Push Guide. +

    Parameters:

    • successCallback: - The method to be called when the registration request succeeds. + The callback to be called when the registration request succeeds.
    • errorCallback [optional] [nullable]: - The method to be called when the registration request fails. + The callback to be called when the registration request fails.
    @@ -329,6 +378,12 @@ AbortError - If the operation cannot be finished properly.

  • with error type SecurityError, if the application does not have the privilege to call this method.

    • +

  • + with error type InvalidStateError, if the application is not connected to the push service. +

    • +

  • + with error type AbortError, if the operation cannot be finished properly. +

    • @@ -337,7 +392,7 @@ AbortError - If the operation cannot be finished properly. /* Defines the error callback */ function errorCallback(response) { -   console.log("The following error occurred: " + response.name); +   console.log("The following error occurred: " + response.name); } /* Defines the registration success callback */ @@ -346,12 +401,32 @@ function registerSuccessCallback(id)    console.log("Registration succeeded with id: " + id); } -/* Requests application registration */ -tizen.push.register(registerSuccessCallback, errorCallback); +/* Defines the state change callback */ +function stateChangeCallback(state) +{ +   console.log("The state is changed to: " + state); + +   if (state == "UNREGISTERED") +   { +      /* Requests application registration */ +      tizen.push.register(registerSuccessCallback, errorCallback); +   } +} + +/* Defines the notification callback */ +function notificationCallback(notification) +{ +   console.log("A notification arrives."); +} + +/* Connects to push service */ +tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
    -

    Output example:

     Registration succeeded with id: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c
+
    Output example:
     The state is changed to: UNREGISTERED
+ Registration succeeded with id: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c
+ The state is changed to: REGISTERED
    @@ -424,7 +499,7 @@ UnknownError - If an unknown error occurs. /* Defines the error callback */ function errorCallback(response) { -   console.log('The following error occurred: ' + response.name); +   console.log('The following error occurred: ' + response.name); } /* Defines the unregistration success callback */ @@ -457,6 +532,8 @@ The ErrorCallback() is launched with these error types:

    @@ -473,11 +550,11 @@ AbortError - If the operation cannot be finished properly. @@ -490,15 +567,23 @@ AbortError - If the operation cannot be finished properly.

  • with error type SecurityError, if the application does not have the privilege to call this method.

    • +

  • + with error type InvalidStateError, if the application is not connected to the push service. +

    • +

  • + with error type AbortError, if the operation cannot be finished properly. +

    • Code example:

    +/* Connection to push service should be established (with connect()) and application should be registered (with register()) before calling the code below */
+
 /* Defines the error callback */
 function errorCallback(response)
 {
-   console.log("The following error occurred: " +  response.name);
+   console.log("The following error occurred: " + response.name);
 }
 
 /* Defines the unregistration success callback */
@@ -516,13 +601,16 @@ tizen.push.unregister(unregisterSuccessCallback, errorCallback);
    -
    +
    connectService
    -
    +
    Connects to the push service and receives push notifications.
    +

    Deprecated. + This function has been deprecated since 3.0. Use the connect() function instead. + 

    void connectService(PushNotificationCallback notificationCallback);

    @@ -539,7 +627,7 @@ tizen.push.unregister(unregisterSuccessCallback, errorCallback);

    Remark : If the application calling the connectService() method has not been registered to the Tizen push server, -the register() method must be called before calling the connectService() method. +the registerService() method must be called before calling the connectService() method.

    Parameters:

    @@ -570,39 +658,137 @@ the register() method must be called before calling the connectServ

    Code example:

    -/* Defines the registration error callback */
+/* Defines the connect success callback */
+function notificationCallback(noti)
+{
+   console.log("Notification received with alert message: " + noti.alertMessage);
+}
+
+/* Defines the data to be used when this process is launched by notification service */
+var service = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/push_test");
+
+/* Defines the error callback */
 function errorCallback(response)
 {
-   console.log("The following error occurred: " +  response.name);
+   console.log("The following error occurred: " + response.name);
 }
 
 /* Defines the registration success callback */
 function registerSuccessCallback(id)
 {
    console.log("Registration succeeded with id: " + id);
+
+   /* Requests for push service connection */
+   tizen.push.connectService(notificationCallback);
+}
+
+/* Requests registration */
+tizen.push.registerService(service, registerSuccessCallback, errorCallback);
+
    +
    +
    +
    +connect +
    +
    +
    + Connects to the push service and gets state change events and push notifications. +
    +
    void connect(PushRegistrationStateChangeCallback stateChangeCallback, PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback);
+
    +

    + Since: + 3.0 +

    +
    +

    +The ErrorCallback() is launched with these error types: +

    +
      +
    • +AbortError - If the operation cannot be finished properly.
      • +
    +
    +

    + Privilege level: + public +

    +

    + Privilege: + http://tizen.org/privilege/push +

    +
    +

    Parameters:

    +
      +
    • +stateChangeCallback: + The callback to be called when the state of registration is changed. The callback would be called at least once, +just after connection is established. +
      • +
    • +notificationCallback: + The callback to be called when the notification message arrives. +
      • +
    • +errorCallback [optional] [nullable]: + The callback to be called when the connect request fails. +
      • +
    +
    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter. +

        • +

      • + with error type SecurityError, if the application does not have the privilege to call this method. +

        • +

      • + with error type AbortError, if the operation cannot be finished properly. +

        • +
      +
    +
    +
    +

    Code example:

    +/* Defines the state change callback */
+function stateChangeCallback(state)
+{
+   console.log("The state is changed to: " + state);
 }
 
-/* Requests application registration */
-tizen.push.register(registerSuccessCallback, errorCallback);
+/* Defines the notification callback */
+function notificationCallback(notification)
+{
+   console.log("A notification arrives.");
+}
 
-/* Defines the connect success callback */
-function notificationCallback(noti)
+/* Defines the error callback */
+function errorCallback(error)
 {
-   console.log("Notification received with alert message: " + noti.alertMessage);
+   console.log("The following error occurred: " + error.name);
 }
 
 /* Requests for push service connection */
-tizen.push.connectService(notificationCallback);
+tizen.push.connect(stateChangeCallback, notificationCallback, errorCallback);
    +
    +

    Output example:

     The state is changed to: UNREGISTERED
+
    +
    -
    +
    disconnectService
    -
    +
    Disconnects the push service and stops receiving push notifications.
    +

    Deprecated. + This function has been deprecated since 3.0. Use the disconnect() function instead. + 

    void disconnectService();

    @@ -624,7 +810,7 @@ tizen.push.connectService(notificationCallback); with error type SecurityError, if the application does not have the privilege to call this method.

  • - with error type UnknownError, if any other error occurs. + with error type AbortError, if the operation cannot be finished properly.

    • @@ -636,6 +822,46 @@ tizen.push.disconnectService();
    +
    +disconnect +
    +
    +
    + Disconnects the push service and stops receiving push notifications. +
    +
    void disconnect();
+
    +

    + Since: + 3.0 +

    +

    + Privilege level: + public +

    +

    + Privilege: + http://tizen.org/privilege/push +

    +
    +

    Exceptions:

    +
    • WebAPIException
        +

      • + with error type SecurityError, if the application does not have the privilege to call this method. +

        • +

      • + with error type UnknownError, if any other error occurs. +

        • +
      +
    +
    +
    +

    Code example:

    +/* Requests disconnection */
+tizen.push.disconnect();
+
    +
    +
    getRegistrationId
    @@ -682,6 +908,32 @@ if (registrationId != null) } +
    +

    Code example:

    +/* Defines the state change callback */
+function stateChangeCallback(state)
+{
+   console.log("The state is changed to: " + state);
+
+   var id = tizen.push.getRegisterationId();
+   console.log("The registration ID: " + id);
+}
+
+/* Defines the notification callback */
+function notificationCallback(notification)
+{
+   console.log("A notification arrives.");
+}
+
+/* Requests for push service connection */
+tizen.push.connect(stateChangeCallback, notificationCallback);
+
    +
    +
    +

    Output example:

     The state is changed to: UNREGISTERED
+ The registration ID: 04a150867a50f48cb79695ac732cbe550b4a6782fffd23cbc14ba8dd5c5ab0025dad29a3e4ef5de8849b95b726bea7a6395c
+
    +
    getUnreadNotifications @@ -746,6 +998,34 @@ tizen.push.connectService(notificationCallback); tizen.push.getUnreadNotifications(); +
    +

    Code example:

    +/* Defines the state change callback */
+function stateChangeCallback(state)
+{
+   console.log("The state is changed to: " + state);
+
+   if (state === "REGISTERED")
+   {
+      /* Gets unread push notifications */
+      tizen.push.getUnreadNotifications();
+   }
+}
+
+/* Defines the notification callback */
+function notificationCallback(notification)
+{
+   console.log("A notification arrives.");
+}
+
+/* Requests for push service connection */
+tizen.push.connect(stateChangeCallback, notificationCallback);
+
    +
    +
    +

    Output example:

     The state is changed to: REGISTERED
+
    +
    getPushMessage @@ -763,8 +1043,7 @@ tizen.push.getUnreadNotifications();

    If the application is launched by the push service, the push service is connected when the application is launched. -Therefore, you can get push messages without calling the register() and -connectService() functions. +Therefore, you can get push messages without calling the connect() function.

    If the application was not launched by the push service, this method returns null. @@ -1009,8 +1288,56 @@ This success callback is invoked when a push service registration request is suc

    +
    +

    2.5. PushRegistrationStateChangeCallback

    +
    + The PushRegistrationStateChangeCallback interface specifies the state change callback for the state change event. +
    +
        [Callback=FunctionOnly, NoInterfaceObject]
+    interface PushRegistrationStateChangeCallback {
+        void onsuccess(PushRegistrationState state);
+    };
    +

    + Since: + 3.0 +

    +
    +

    +This state change callback is invoked when the state of registration is changed. +Moreover PushRegistrationStateChangeCallback would be called at least once, just after connection is established. +

    +
    +
    +

    Methods

    +
    +
    +onsuccess +
    +
    +
    + Called when the state of push registration is changed. +
    +
    void onsuccess(PushRegistrationState state);
+
    +

    + Since: + 3.0 +

    +
    +

    Parameters:

    +
      +
    • +state: + The state of push registration. +
      • +
    +
    +
    +
    +
    +
    -

    2.5. PushNotificationCallback

    +

    2.6. PushNotificationCallback

    The PushNotificationCallback interface specifies the notification callback for the received push notification message.
    @@ -1069,12 +1396,15 @@ To guarantee that the push application runs on a device with the push feature, d
  • http://tizen.org/feature/network.push

    • - For more information, see Application Filtering. + For more information, see Application Filtering.

    4. Full WebIDL

    module Push {
+
     typedef DOMString PushRegistrationId;
 
+    enum PushRegistrationState {"REGISTERED", "UNREGISTERED"};
+
     [NoInterfaceObject] interface PushManagerObject {
         readonly attribute PushManager push;
     };
@@ -1090,12 +1420,17 @@ To guarantee that the push application runs on a device with the push feature, d
                     optional ErrorCallback? errorCallback) raises(WebAPIException);
 
       void unregister(optional SuccessCallback? successCallback,
-                    optional ErrorCallback? errorCallback) raises(WebAPIException);
+                      optional ErrorCallback? errorCallback) raises(WebAPIException);
 
       void connectService(PushNotificationCallback notificationCallback) raises(WebAPIException);
 
+      void connect(PushRegistrationStateChangeCallback stateChangeCallback,
+                   PushNotificationCallback notificationCallback, optional ErrorCallback? errorCallback) raises(WebAPIException);
+
       void disconnectService() raises(WebAPIException);
 
+      void disconnect() raises(WebAPIException);
+
       PushRegistrationId getRegistrationId() raises(WebAPIException);
 
       void getUnreadNotifications() raises(WebAPIException);
@@ -1127,6 +1462,11 @@ To guarantee that the push application runs on a device with the push feature, d
     };
 
     [Callback=FunctionOnly, NoInterfaceObject]
+    interface PushRegistrationStateChangeCallback {
+        void onsuccess(PushRegistrationState state);
+    };
+
+    [Callback=FunctionOnly, NoInterfaceObject]
     interface PushNotificationCallback {
         void onsuccess(PushMessage message);
     };