From: taekeun.kang Date: Tue, 13 Dec 2016 01:27:24 +0000 (+0900) Subject: [Push] update latest spec - remove type of PushMessage X-Git-Tag: GitHub/PR#40/tizen-studio~221^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=refs%2Fchanges%2F32%2F104232%2F1;p=sdk%2Fonline-doc.git [Push] update latest spec - remove type of PushMessage Change-Id: I9ebe81c1764cd6a2b6ae0033e44474623d6de36f Signed-off-by: taekeun.kang --- 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 62b5f3d..2a60013 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 @@ -1113,8 +1113,6 @@ catch (err) readonly attribute DOMString sessionInfo; readonly attribute DOMString requestId; - - readonly attribute long type; };

Since: @@ -1197,16 +1195,6 @@ This data is the message that the sender wants to send and its length must be le Since: 3.0

- -
  • - readonly -long type
    - The type value assigned by the sender. -
    -

    - Since: - 3.0 -

    Code example:

     /* Defines the connect success callback */
@@ -1219,7 +1207,6 @@ function notificationCallback(noti)
    console.log(' - message: ' + noti.message);
    console.log(' - session: ' + noti.sessionInfo);
    console.log(' - request ID: ' + noti.requestId);
-   console.log(' - type: ' + noti.type);
 }
 
 /* Requests for push service connection */
@@ -1234,7 +1221,6 @@ tizen.push.connectService(notificationCallback);
   - message: alertMessage=Hi
   - session: 002002
   - request ID: 23
-  - type: 1
    • @@ -1452,8 +1438,6 @@ To guarantee that the push application runs on a device with the push feature, d readonly attribute DOMString sessionInfo; readonly attribute DOMString requestId; - - readonly attribute long type; }; [Callback=FunctionOnly, NoInterfaceObject] diff --git a/org.tizen.web.apireference/html/device_api/wearable/tizen/push.html b/org.tizen.web.apireference/html/device_api/wearable/tizen/push.html index 26aecfe..e7c2ea4 100755 --- a/org.tizen.web.apireference/html/device_api/wearable/tizen/push.html +++ b/org.tizen.web.apireference/html/device_api/wearable/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 the native 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,7 +550,7 @@ 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,44 +658,142 @@ 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 application registration */
-tizen.push.register(registerSuccessCallback, errorCallback);
+/* 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);
+}
 
-/* Defines the connect success callback */
-function notificationCallback(noti)
+/* Defines the notification callback */
+function notificationCallback(notification)
 {
-   console.log("Notification received with alert message: " + noti.alertMessage);
+   console.log("A notification arrives.");
+}
+
+/* Defines the error callback */
+function errorCallback(error)
+{
+   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();

    Since: - 2.3.1 + 2.1

    Privilege level: @@ -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. @@ -834,8 +1113,6 @@ catch (err) readonly attribute DOMString sessionInfo; readonly attribute DOMString requestId; - - readonly attribute long type; };

    Since: @@ -918,16 +1195,6 @@ This data is the message that the sender wants to send and its length must be le Since: 3.0

    - -
  • - readonly -long type
    - The type value assigned by the sender. -
    -

    - Since: - 3.0 -

    Code example:

     /* Defines the connect success callback */
@@ -940,7 +1207,6 @@ function notificationCallback(noti)
    console.log(' - message: ' + noti.message);
    console.log(' - session: ' + noti.sessionInfo);
    console.log(' - request ID: ' + noti.requestId);
-   console.log(' - type: ' + noti.type);
 }
 
 /* Requests for push service connection */
@@ -950,11 +1216,11 @@ tizen.push.connectService(notificationCallback);
 
    
 
    Output example:
     Notification received on Thu Jan 01 2015 from: xyz.AnotherApp
  Details:
-  - data: example data
-  - alert message: Data from xyz.AnotherApp received
-  - session: example session info
+  - data: {id:asdf}
+  - alert message: Hi
+  - message: alertMessage=Hi
+  - session: 002002
   - request ID: 23
-  - type: 1
    • @@ -1008,8 +1274,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.
    @@ -1068,12 +1382,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;
     };
@@ -1089,12 +1406,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);
@@ -1116,8 +1438,6 @@ To guarantee that the push application runs on a device with the push feature, d
         readonly attribute DOMString sessionInfo;
 
         readonly attribute DOMString requestId;
-
-        readonly attribute long type;
     };
 
     [Callback=FunctionOnly, NoInterfaceObject]
@@ -1126,6 +1446,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);
     };