<p>For example, to show a "Hi" message in the quick panel and increase the badge count by 1 when the notification arrives at the device, the message field of the notification must be the following:</p>
-<pre class="prettyprint">"badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi"</pre>
+<pre class="prettyprint">
+"badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi"
+</pre>
<p>The message field takes effect only when the application is not running (more precisely, when the application is not connected to the push service). If a notification with the above message field arrives at the device where the application is running, the push service delivers the notification directly to the application. It does not show the "Hi" message in the quick panel or increase the badge count.</p>
</li>
<p>If the <span style="font-family: Courier New,Courier,monospace;">regId</span> is base64-encoded, use the <span style="font-family: Courier New,Courier,monospace;">"base64"</span> value for this field. Otherwise, leave this field blank to allow the push server to handle the <span style="font-family: Courier New,Courier,monospace;">regId</span> as a hex string.</p></td>
<td><ul><li>Optional</li>
<li>Type: string</li>
- <li>Default: null</li></ul></td>
+ <li>Default: <span style="font-family: Courier New,Courier,monospace;">NULL</span></li></ul></td>
</tr>
<tr>
<td>
<ul><li>Optional</li>
<li>Type: string</li>
- <li>Default: null</li></ul></td>
+ <li>Default: <span style="font-family: Courier New,Courier,monospace;">NULL</span></li></ul></td>
</tr>
<tr>
<td><span style="font-family: Courier New,Courier,monospace;">message</span></td>
<p>Maximum message length must be less than 2 kb. Make sure that if there is no message and <span style="font-family: Courier New,Courier,monospace;">appData</span>, the push server rejects the message and returns an error.</p></td>
<td>
<ul><li>Conditionally mandatory
-(if <span style="font-family: Courier New,Courier,monospace;">appData</span> is null, this field is required)</li>
+(if <span style="font-family: Courier New,Courier,monospace;">appData</span> is <span style="font-family: Courier New,Courier,monospace;">NULL</span>, this field is required)</li>
<li>Type: string</li>
- <li>Default: null</li></ul>
+ <li>Default: <span style="font-family: Courier New,Courier,monospace;">NULL</span></li></ul>
</td>
</tr>
<tr>
<td>Applications can use this field to carry their own data. The handling of this data depends on the type defined with the <span style="font-family: Courier New,Courier,monospace;">type</span> key.
<p>Make sure that if there is no message and no <span style="font-family: Courier New,Courier,monospace;">appData</span>, the push server rejects the message and returns an error.</p></td>
<td>
- <ul><li>Conditionally mandatory (if message is null, this field is required)</li>
+ <ul><li>Conditionally mandatory (if message is <span style="font-family: Courier New,Courier,monospace;">NULL</span>, this field is required)</li>
<li>Type: string</li>
- <li>Default: null</li></ul>
+ <li>Default: <span style="font-family: Courier New,Courier,monospace;">NULL</span></li></ul>
</td>
</tr>
<td>
<ul><li>Optional</li>
<li>Type: string</li>
- <li>Default: null</li></ul>
+ <li>Default: <span style="font-family: Courier New,Courier,monospace;">NULL</span></li></ul>
</td>
</tr>
<tr>
<td>
<ul><li>Optional</li>
<li>Type: long</li>
- <li>Default: null</li></ul>
+ <li>Default: <span style="font-family: Courier New,Courier,monospace;">NULL</span></li></ul>
</td>
</tr>
</tbody>
<li>Example request:
<pre class="prettyprint">
{
- "encoding": "base64" // Optional
- "regID": "ab123456",
- "requestID": "0000001",
- "sender": "oscal", // Optional
- "type": 0 //Optional
- "message": "badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi", // Optional
- "appData": "{id:asdf&passwd:1234}", // Optional, (Opaque)
- "sessionInfo": "002002", // Optional
- "timeStamp": 1234567890, // Optional
+ "encoding": "base64" /* Optional */
+ "regID": "ab123456",
+ "requestID": "0000001",
+ "sender": "oscal", /* Optional */
+ "type": 0 /* Optional */
+ "message": "badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi", /* Optional */
+ "appData": "{id:asdf&passwd:1234}", /* Optional, (Opaque) */
+ "sessionInfo": "002002", /* Optional */
+ "timeStamp": 1234567890, /* Optional */
}
</pre>
</li>
<p>The following example shows a response message when the request is successful:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "ab123456",
- "requestID": "0000001",
- "statusCode": 1000,
- "statusMsg": "Success"
- }]
+ "results":
+ [{
+ "regID": "ab123456",
+ "requestID": "0000001",
+ "statusCode": 1000,
+ "statusMsg": "Success"
+ }]
}
</pre>
</li>
<p>The following example shows a response message when the request fails due to malformation:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "",
- "requestID": "",
- "statusCode": 3023,
- "statusMsg": "error of json mapping exception"
- }]
+ "results":
+ [{
+ "regID": "",
+ "requestID": "",
+ "statusCode": 3023,
+ "statusMsg": "error of json mapping exception"
+ }]
}
</pre>
</li>
<p>The following example shows a response message when the request fails due to abnormal data:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "ab123456",
- "requestID": "0000001",
- "statusCode": 3008,
- "statusMsg": "error of not registered regID"
- }]
+ "results":
+ [{
+ "regID": "ab123456",
+ "requestID": "0000001",
+ "statusCode": 3008,
+ "statusMsg": "error of not registered regID"
+ }]
}
</pre>
<table class="note">
<li>Example request:
<pre class="prettyprint">
{
- "messages":
- [{
- "encoding": "base64" // Optional
- "regID": "ab123456",
- "requestID": "0000001",
- "sender": "oscal", // Optional
- "type": 0 // Optional
- "message": "example", // Optional
- "appData": "{id:asdf&passwd:1234}", // Optional, (Opaque)
- "reliableOption": "Transport", // Optional
- "sessionInfo": "192.168.0.1-8080-12345567", // Optional
- "timeStamp": 1234567890, // Optional
- }
- {
- "encoding": "base64" // Optional
- "regID": "ab234567",
- "requestID": "0000002",
- "sender": "oscal", // Optional
- "type": 0 // Optional
- "message": "example", // Optional
- "appData": "{id:asdf&passwd:1234}", // Optional, (Opaque)
- "reliableOption": "Transport", // Optional
- "sessionInfo": "192.168.0.1-8080-12345567", // Optional
- "timeStamp": 1234567890, // Optional
- ]}
+ "messages":
+ [{
+ "encoding": "base64" /* Optional */
+ "regID": "ab123456",
+ "requestID": "0000001",
+ "sender": "oscal", /* Optional */
+ "type": 0 /* Optional */
+ "message": "example", /* Optional */
+ "appData": "{id:asdf&passwd:1234}", /* Optional, (Opaque) */
+ "reliableOption": "Transport", /* Optional */
+ "sessionInfo": "192.168.0.1-8080-12345567", /* Optional */
+ "timeStamp": 1234567890, /* Optional */
+ }
+ {
+ "encoding": "base64" /* Optional */
+ "regID": "ab234567",
+ "requestID": "0000002",
+ "sender": "oscal", /* Optional */
+ "type": 0 /* Optional */
+ "message": "example", /* Optional */
+ "appData": "{id:asdf&passwd:1234}", /* Optional, (Opaque) */
+ "reliableOption": "Transport", /* Optional */
+ "sessionInfo": "192.168.0.1-8080-12345567", /* Optional */
+ "timeStamp": 1234567890, /* Optional */
+ ]}
}
</pre>
</li>
<p>The following example shows a response message when the request is successful:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "ab123456",
- "requestID": "0000001",
- "statusCode": 1000,
- "statusMsg": "Success"
- }
- {
- "regID": "ab234567",
- "requestID": "0000002",
- "statusCode": 1000,
- "statusMsg": "Success"
- }]
+ "results":
+ [{
+ "regID": "ab123456",
+ "requestID": "0000001",
+ "statusCode": 1000,
+ "statusMsg": "Success"
+ }
+ {
+ "regID": "ab234567",
+ "requestID": "0000002",
+ "statusCode": 1000,
+ "statusMsg": "Success"
+ }]
}
</pre>
</li>
<p>The following example shows a response message when the request fails due to malformation:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "",
- "requestID": "",
- "statusCode": 3023,
- "statusMsg": "error of json mapping exception"
- }]
+ "results":
+ [{
+ "regID": "",
+ "requestID": "",
+ "statusCode": 3023,
+ "statusMsg": "error of json mapping exception"
+ }]
}
</pre>
</li>
<p>The following example shows a response message when some parts of the multiple request have failed and the others have not:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "ab123456",
- "requestID": "0000001",
- "statusCode": 1000,
- "statusMsg": "Success"
- }
- {
- "regID": "ab234567",
- "requestID": "0000002",
- "statusCode": 3008,
- "statusMsg": "error of not registered regID"+ }]
+ "results":
+ [{
+ "regID": "ab123456",
+ "requestID": "0000001",
+ "statusCode": 1000,
+ "statusMsg": "Success"
+ }
+ {
+ "regID": "ab234567",
+ "requestID": "0000002",
+ "statusCode": 3008,
+ "statusMsg": "error of not registered regID"+ }]
}
</pre>
</li>
<li>Example request:
<pre class="prettyprint">
{
- "messages":
- [{
- "encoding": "base64" // Optional
- "regID": ["ab123456", "ab234567", "ab345678"]
- "requestID": "0000001",
- "sender": "oscal", // Optional
- "type": 0 // Optional
- "message": "example", // Optional
- "appData": "{id:asdf&passwd:1234}", // Optional
- "sessionInfo": "192.168.0.1-8080-12345567", // Optional
- "timeStamp": 1234567890, // Optional
- ]}
+ "messages":
+ [{
+ "encoding": "base64" /* Optional */
+ "regID": ["ab123456", "ab234567", "ab345678"]
+ "requestID": "0000001",
+ "sender": "oscal", /* Optional */
+ "type": 0 /* Optional */
+ "message": "example", /* Optional */
+ "appData": "{id:asdf&passwd:1234}", /* Optional */
+ "sessionInfo": "192.168.0.1-8080-12345567", /* Optional */
+ "timeStamp": 1234567890, /* Optional */
+ ]}
}
</pre>
</li>
<p>The following example shows a response message when the request is successful:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "ab123456",
- "requestID": "0000001",
- "statusCode": 1000,
- "statusMsg": "Success"
- }
- {
- "regID": "ab234567",
- "requestID": "0000002",
- "statusCode": 1000,
- "statusMsg": "Success"
- }
- {
- "regID": "ab345678",
- "requestID": "0000002",
- "statusCode": 1000,
- "statusMsg": "Success"
- }]
+ "results":
+ [{
+ "regID": "ab123456",
+ "requestID": "0000001",
+ "statusCode": 1000,
+ "statusMsg": "Success"
+ }
+ {
+ "regID": "ab234567",
+ "requestID": "0000002",
+ "statusCode": 1000,
+ "statusMsg": "Success"
+ }
+ {
+ "regID": "ab345678",
+ "requestID": "0000002",
+ "statusCode": 1000,
+ "statusMsg": "Success"
+ }]
}
</pre>
</li>
<p>The following example shows a response message when the request fails due to malformation:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "",
- "requestID": "",
- "statusCode": 3023,
- "statusMsg": "error of json mapping exception"
- }]
+ "results":
+ [{
+ "regID": "",
+ "requestID": "",
+ "statusCode": 3023,
+ "statusMsg": "error of json mapping exception"
+ }]
}
</pre>
</li>
<p>The following example shows a response message when some parts of the multicast request have failed and the others have not:</p>
<pre class="prettyprint">
{
- "results":
- [{
- "regID": "ab123456",
- "requestID": "0000001",
- "statusCode": 1000,
- "statusMsg": "Success"
- }
- {
- "regID": "ab234567",
- "requestID": "0000001",
- "statusCode": 3008,
- "statusMsg": "error of not registered regID"
- }
- {
- "regID": "ab345678",
- "requestID": "0000001",
- "statusCode": 3013,
- "statusMsg": "error of impossible to enqueue"
- }]
+ "results":
+ [{
+ "regID": "ab123456",
+ "requestID": "0000001",
+ "statusCode": 1000,
+ "statusMsg": "Success"
+ }
+ {
+ "regID": "ab234567",
+ "requestID": "0000001",
+ "statusCode": 3008,
+ "statusMsg": "error of not registered regID"
+ }
+ {
+ "regID": "ab345678",
+ "requestID": "0000001",
+ "statusCode": 3013,
+ "statusMsg": "error of impossible to enqueue"
+ }]
}
</pre>
</li>
</tr>
<tr>
<td>3018</td>
- <td>Error of notification data contains unreadable data or null</td>
+ <td>Error of notification data contains unreadable data or <span style="font-family: Courier New,Courier,monospace;">NULL</span></td>
</tr>
<tr>
<td>3019</td>
<div id="toc_border"><div id="toc">
<p class="toc-title">Content</p>
<ul class="toc">
+ <li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#start">Initializing the Push Service</a></li>
<li><a href="#connect">Connecting to the Push Service</a></li>
<li><a href="#registration">Registering with the Push Server</a></li>
<li><a href="#security">Managing Security</a>
<p>Ensure the security of notifications containing sensitive information.</p></li>
</ul>
-
+
+<h2 id="prerequisites">Prerequisites</h2>
+
+<p>To use the Push API, the application has to request permission by adding the following privilege to the <span style="font-family: Courier New,Courier,monospace;">tizen-manifest.xml</span> file:</p>
+<pre class="prettyprint">
+<privileges>
+ <privilege>http://tizen.org/privilege/push</privilege>
+</privileges>
+</pre>
<h2 id="start" name="start">Initializing the Push Service</h2>
<p>To use the push messaging service, the application needs the permission to access the Tizen push server. Request the permission from the Tizen push service team by <a href="mailto:push.tizen@samsung.com">email</a>, including the following information. When the team approves the request, you receive a push app ID corresponding to your package ID.</p></li>
</ol>
-<table>
+<table id="request_form">
<caption>Table: Request form details</caption>
<tbody>
<tr>
</table>
-<p>To set up the required library and privilege for the application:</p>
+<p>To define the required library and application set-up:</p>
<ol>
<li><p>To use the functions and data types of the Push API (in <a href="../../../../org.tizen.native.mobile.apireference/group__CAPI__MESSAGING__PUSH__PUBLIC__MODULE.html">mobile</a> and <a href="../../../../org.tizen.native.wearable.apireference/group__CAPI__MESSAGING__PUSH__PUBLIC__MODULE.html">wearable</a> applications), include the <span style="font-family: Courier New,Courier,monospace;"><push-service.h></span> header file to your application:</p>
</pre>
</li>
-<li id="privilege" name="privilege"><p>To access the Tizen push service on the device, add the following privilege to the manifest file:
-</p>
-
-<pre class="prettyprint">
-http://tizen.org/privilege/push
-</pre>
-</li>
<li><p>To ensure that push notifications are handled fluently, make both a service and UI application. The service application receives push notifications in the background, while the UI application shows the notifications or events triggered by notifications to the users. An example implementation is available in the push sample package in the Tizen SDK.</p>
</li>
</ol>
<pre class="prettyprint">
#define PUSH_APP_ID "YOUR_PUSH_ID_HERE"
-static bool
+static bool
app_create(void *data)
{
- int ret;
+ int ret;
- // Connect to the push service when the application is launched
- ret = push_service_connect(PUSH_APP_ID, _state_cb, _noti_cb, NULL, &push_conn);
+ /* Connect to the push service when the application is launched */
+ ret = push_service_connect(PUSH_APP_ID, _state_cb, _noti_cb, NULL, &push_conn);
- if (ret != PUSH_SERVICE_ERROR_NONE)
- {
- // Implementation here
- dlog_print(DLOG_INFO, LOG_TAG, "push_service_connect() Failed");
- }
+ if (ret != PUSH_SERVICE_ERROR_NONE) {
+ /* Implementation here */
+ dlog_print(DLOG_INFO, LOG_TAG, "push_service_connect() Failed");
+ }
- return true;
+ return true;
}
</pre>
<ul>
<li>The <span style="font-family: Courier New,Courier,monospace;">YOUR_PUSH_ID_HERE</span> parameter is the push app ID received from the Tizen push server team when the access to the server was requested. Keep this push app ID confidential, otherwise your push notifications can be hijacked by malicious applications.</li>
<li>The <span style="font-family: Courier New,Courier,monospace;">_state_cb()</span> and <span style="font-family: Courier New,Courier,monospace;">_noti_cb()</span> parameters are callback functions called when the <a href="#state">state changes</a> or <a href="#receive_push">a notification arrives from the server</a> through the push service.</li>
-<li>The <span style="font-family: Courier New,Courier,monospace;">push_conn</span> parameter is the output of the <span style="font-family: Courier New,Courier,monospace;">push_service_connect()</span> function. If the connection between the application and the service is successful, the <span style="font-family: Courier New,Courier,monospace;">push_service_connect()</span> function returns <span style="font-family: Courier New,Courier,monospace;">PUSH_SERVICE_ERROR_NONE</span> and the <span style="font-family: Courier New,Courier,monospace;">push_conn</span> connection handle is returned through the last parameter. If the <span style="font-family: Courier New,Courier,monospace;">push_service_connect()</span> function returns other values, the connection to the service failed. This happens most likely when the <a href="#privilege">push privilege</a> is not added in the SDK.</li>
+<li>The <span style="font-family: Courier New,Courier,monospace;">push_conn</span> parameter is the output of the <span style="font-family: Courier New,Courier,monospace;">push_service_connect()</span> function. If the connection between the application and the service is successful, the <span style="font-family: Courier New,Courier,monospace;">push_service_connect()</span> function returns <span style="font-family: Courier New,Courier,monospace;">PUSH_SERVICE_ERROR_NONE</span> and the <span style="font-family: Courier New,Courier,monospace;">push_conn</span> connection handle is returned through the last parameter. If the <span style="font-family: Courier New,Courier,monospace;">push_service_connect()</span> function returns other values, the connection to the service failed. This happens most likely when the <a href="#prerequisites">push privilege</a> is not added in the SDK.</li>
</ul>
<p>This sample application establishes a connection to the service when it is launched and disconnects from the service when it terminates. Due to this, the <span style="font-family: Courier New,Courier,monospace;">push_service_connect()</span> function is located in the <span style="font-family: Courier New,Courier,monospace;">app_create()</span> function, which is called when the application is launched.
<p>When the current state transits, the <span style="font-family: Courier New,Courier,monospace;">_state_cb()</span> function is called and the new state is obtained from the first parameter. Determine the application actions based on the new state:</p>
<pre class="prettyprint">
-static void
-_state_cb(push_service_state_e state, const char *err, void *user_data)
+static void
+_state_cb(push_service_state_e state, const char *err, void *user_data)
{
- switch (state)
- {
- case PUSH_SERVICE_STATE_UNREGISTERED:
- dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_UNREGISTERED");
- _on_state_unregistered(user_data);
- break;
-
- case PUSH_SERVICE_STATE_REGISTERED:
- dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_REGISTERED");
- _on_state_registered(user_data);
- break;
-
- case PUSH_SERVICE_STATE_ERROR:
- dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_ERROR");
- _on_state_error(err, user_data);
- break;
-
- default:
- dlog_print(DLOG_INFO, LOG_TAG, "Unknown State");
- break;
- }
+ switch (state) {
+ case PUSH_SERVICE_STATE_UNREGISTERED:
+ dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_UNREGISTERED");
+ _on_state_unregistered(user_data);
+ break;
+ case PUSH_SERVICE_STATE_REGISTERED:
+ dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_REGISTERED");
+ _on_state_registered(user_data);
+ break;
+ case PUSH_SERVICE_STATE_ERROR:
+ dlog_print(DLOG_INFO, LOG_TAG, "Arrived at STATE_ERROR");
+ _on_state_error(err, user_data);
+ break;
+ default:
+ dlog_print(DLOG_INFO, LOG_TAG, "Unknown State");
+ break;
+ }
}
</pre>
<pre class="prettyprint">
#define PUSH_HASH_KEY "existing_push_reg_id"
-static void
-_on_state_unregistered(void *user_data)
+static void
+_on_state_unregistered(void *user_data)
{
- int ret;
+ int ret;
- // Reset the previously-stored registration ID
- ret = preference_set_string(PUSH_HASH_KEY, "");
+ /* Reset the previously-stored registration ID */
+ ret = preference_set_string(PUSH_HASH_KEY, "");
- // Send a registration request to the push service
- ret = push_service_register(push_conn, _result_cb, NULL);
+ /* Send a registration request to the push service */
+ ret = push_service_register(push_conn, _result_cb, NULL);
}
</pre>
<p>The registration request is non-blocking. If the <span style="font-family: Courier New,Courier,monospace;">push_service_register()</span> function returns <span style="font-family: Courier New,Courier,monospace;">PUSH_SERVICE_ERROR_NONE</span>, the request is successfully delivered to the push service. However, it does not necessarily mean that the request is approved by the server. If the push service successfully sends the request to the server and receives an approval, the <span style="font-family: Courier New,Courier,monospace;">_result_cb()</span> callback is called with <span style="font-family: Courier New,Courier,monospace;">PUSH_SERVICE_RESULT_SUCCESS</span> as the first parameter:</p>
<pre class="prettyprint">
-static void
-_result_cb(push_service_result_e result, const char *msg, void *user_data)
+static void
+_result_cb(push_service_result_e result, const char *msg, void *user_data)
{
- if (result == PUSH_SERVICE_RESULT_SUCCESS)
- dlog_print(DLOG_INFO, LOG_TAG, "Registration request is approved.");
- else
- dlog_print(DLOG_ERROR, LOG_TAG, "Registration ERROR [%s]", msg);
+ if (result == PUSH_SERVICE_RESULT_SUCCESS)
+ dlog_print(DLOG_INFO, LOG_TAG, "Registration request is approved.");
+ else
+ dlog_print(DLOG_ERROR, LOG_TAG, "Registration ERROR [%s]", msg);
- return;
+ return;
}
</pre>
</ul>
<pre class="prettyprint">
-static void
-_on_state_registered(void *user_data)
+static void
+_on_state_registered(void *user_data)
{
- int ret;
- char *reg_id = NULL;
- char *app_id = NULL;
+ int ret;
+ char *reg_id = NULL;
+ char *app_id = NULL;
- // Request unread notifications to the push service
- // _noti_cb() is called if there are unread notifications
- ret = push_service_request_unread_notification(push_conn);
+ /* Request unread notifications to the push service */
+ /* _noti_cb() is called if there are unread notifications */
+ ret = push_service_request_unread_notification(push_conn);
- // Get the registration ID
- ret = push_service_get_registration_id(push_conn, &reg_id);
- if (ret != PUSH_SERVICE_ERROR_NONE)
- {
- dlog_print(DLOG_ERROR, LOG_TAG, "ERROR [%d]: push_service_get_registration_id()", ret);
+ /* Get the registration ID */
+ ret = push_service_get_registration_id(push_conn, &reg_id);
+ if (ret != PUSH_SERVICE_ERROR_NONE) {
+ dlog_print(DLOG_ERROR, LOG_TAG, "ERROR [%d]: push_service_get_registration_id()", ret);
- return;
- }
+ return;
+ }
- // Send reg_id to your application server if necessary
- _send_reg_id_if_necessary(reg_id);
+ /* Send reg_id to your application server if necessary */
+ _send_reg_id_if_necessary(reg_id);
- if (reg_id)
- free(reg_id);
+ if (reg_id)
+ free(reg_id);
}
</pre>
#include <openssl/sha.h>
#define PUSH_HASH_KEY "existing_push_reg_id"
-static void
+static void
_send_reg_id_if_necessary(const char *reg_id)
{
- unsigned char md[SHA_DIGEST_LENGTH];
- char hash_string[2*SHA_DIGEST_LENGTH+1];
- char *buf_ptr = hash_string;
- char *stored_hash_value = NULL;
- int ret, i;
-
- // Generate a hash string from reg_id
- SHA1((unsigned char *)reg_id, sizeof(reg_id), md);
-
- // Convert byte array to hex string
- for (i = 0; i < SHA_DIGEST_LENGTH; i++)
- {
- buf_ptr += sprintf(buf_ptr, "%02X", md[i]);
- }
- hash_string[2*SHA_DIGEST_LENGTH] = '\0';
-
- // Get the saved hash string
- ret = preference_get_string(PUSH_HASH_KEY, &stored_hash_value);
-
- // If there is no hash string stored before or
- // if the stored hash string is different from the new one,
- // send reg_id to the server
- if (ret != PREFERENCE_ERROR_NONE || strncmp(stored_hash_value, hash_string, 2*SHA_DIGEST_LENGTH) !=0)
- {
- // Send the reg_id to your application server
- ret = _send_reg_id(reg_id);
-
- // If reg_id is successfully sent, store the new hash value.
- if (!ret)
- {
- ret = preference_set_string(PUSH_HASH_KEY, hash_string);
- }
- }
- if (stored_hash_value)
- free(stored_hash_value);
-
- return;
+ unsigned char md[SHA_DIGEST_LENGTH];
+ char hash_string[2*SHA_DIGEST_LENGTH+1];
+ char *buf_ptr = hash_string;
+ char *stored_hash_value = NULL;
+ int ret;
+ int i;
+
+ /* Generate a hash string from reg_id */
+ SHA1((unsigned char *)reg_id, sizeof(reg_id), md);
+
+ /* Convert byte array to hex string */
+ for (i = 0; i < SHA_DIGEST_LENGTH; i++)
+ buf_ptr += sprintf(buf_ptr, "%02X", md[i]);
+ hash_string[2*SHA_DIGEST_LENGTH] = '\0';
+
+ /* Get the saved hash string */
+ ret = preference_get_string(PUSH_HASH_KEY, &stored_hash_value);
+
+ /*
+ If there is no hash string stored before or
+ if the stored hash string is different from the new one,
+ send reg_id to the server
+ */
+ if (ret != PREFERENCE_ERROR_NONE || strncmp(stored_hash_value, hash_string, 2*SHA_DIGEST_LENGTH) !=0) {
+ /* Send the reg_id to your application server */
+ ret = _send_reg_id(reg_id);
+
+ /* If reg_id is successfully sent, store the new hash value */
+ if (!ret)
+ ret = preference_set_string(PUSH_HASH_KEY, hash_string);
+ }
+ if (stored_hash_value)
+ free(stored_hash_value);
+
+ return;
}
</pre>
</li>
<li>Body:
<pre class="prettyprint">
{
- "regID": "0501a53f4affdcbb98197f188345ff30c04b",
- "requestID": "01231-22EAX-223442",
- "message": "badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi",
- "appData": "{id:asdf&passwd:1234}", // Optional, if the message field is not empty
+ "regID": "0501a53f4affdcbb98197f188345ff30c04b",
+ "requestID": "01231-22EAX-223442",
+ "message": "badgeOption=INCREASE&badgeNumber=1&action=ALERT&alertMessage=Hi",
+ "appData": "{id:asdf&passwd:1234}", /* Optional, if the message field is not empty */
}
</pre></li>
</ul>
<p>The following example shows how the application can retrieve the app data (payload), message, and timestamp from the received notification. When the <span style="font-family: Courier New,Courier,monospace;">_noti_cb()</span> callback is called, obtain the notification through the first parameter. You can retrieve the app data, message, and time stamp from the handle using the <span style="font-family: Courier New,Courier,monospace;">push_service_get_notification_data()</span>, <span style="font-family: Courier New,Courier,monospace;">push_service_get_notification_message()</span>, and <span style="font-family: Courier New,Courier,monospace;">push_service_get_notification_time()</span> functions respectively. Before exiting the function, free the data, except for the notification itself. The notification is freed automatically right after the callback.</p>
<pre class="prettyprint">
-static void
+static void
_noti_cb(push_service_notification_h noti, void *user_data)
{
- int ret;
-
- char *data=NULL; // App data loaded on the notification
- char *msg=NULL; // Noti message
- long long int time_stamp; // Time when the noti is generated
- char *sender=NULL; // Optional sender information
- char *session_info=NULL; // Optional session information
- char *request_id=NULL; // Optional request ID
- int type=0; // Optional type information
-
- // Retrieve app data from noti
- ret = push_service_get_notification_data(noti, &data);
- // Decrypt app data here if it is encrypted
-
- // Retrieve notification message from noti
- ret = push_service_get_notification_message(noti, &msg);
-
- // Retrieve the time when notification is created from noti
- ret = push_service_get_notification_time(noti, &time_stamp);
-
- // Retrieve the optional information
- ret = push_service_get_notification_sender(noti, &sender);
- ret = push_service_get_notification_session_info(noti, &session_info);
- ret = push_service_get_notification_request_id(noti, &request_id);
- ret = push_service_get_notification_type(noti, &type);
-
- // Use data, msg, time_stamp, sender,
- // session_info, request_id, and type as needed
-
- // Free all resources
- // Do not free noti in the callback function
- if (data)
- free(data);
- if (msg)
- free(msg);
- if (sender)
- free(sender);
- if (session_info)
- free(session_info);
- if (request_id)
- free(request_id);
+ int ret;
+
+ char *data=NULL; /* App data loaded on the notification */
+ char *msg=NULL; /* Noti message */
+ long long int time_stamp; /* Time when the noti is generated */
+ char *sender=NULL; /* Optional sender information */
+ char *session_info=NULL; /* Optional session information */
+ char *request_id=NULL; /* Optional request ID */
+ int type=0; /* Optional type information */
+
+ /* Retrieve app data from noti */
+ ret = push_service_get_notification_data(noti, &data);
+ /* Decrypt app data here if it is encrypted */
+
+ /* Retrieve notification message from noti */
+ ret = push_service_get_notification_message(noti, &msg);
+
+ /* Retrieve the time when notification is created from noti */
+ ret = push_service_get_notification_time(noti, &time_stamp);
+
+ /* Retrieve the optional information */
+ ret = push_service_get_notification_sender(noti, &sender);
+ ret = push_service_get_notification_session_info(noti, &session_info);
+ ret = push_service_get_notification_request_id(noti, &request_id);
+ ret = push_service_get_notification_type(noti, &type);
+
+ /*
+ Use data, msg, time_stamp, sender,
+ session_info, request_id, and type as needed
+ */
+
+ /* Free all resources */
+ /* Do not free noti in the callback function */
+ if (data)
+ free(data);
+ if (msg)
+ free(msg);
+ if (sender)
+ free(sender);
+ if (session_info)
+ free(session_info);
+ if (request_id)
+ free(request_id);
}
</pre>
</li>
<p>If the application is not launched by the push service, this function returns as <span style="font-family: Courier New,Courier,monospace;">NULL</span>.</p>
<pre class="prettyprint">
-static void
+static void
app_control(app_control_h app_control, void *data)
{
- char *op = NULL;
- push_service_notification_h noti = NULL;
- int ret;
-
- if (app_control_get_operation(app_control, &op) < 0)
- {
- return;
- }
-
- // Retrieve the noti from the bundle
- ret = push_service_app_control_to_notification(app_control, op, &noti);
-
- if (noti)
- {
- // Handle the noti
-
- // Free the noti
- push_service_free_notification(noti);
- }
- else
- {
- // Case when the application is not launched by the push service
- }
- if (op)
- free(op);
+ char *op = NULL;
+ push_service_notification_h noti = NULL;
+ int ret;
+
+ if (app_control_get_operation(app_control, &op) < 0)
+ return;
+
+ /* Retrieve the noti from the bundle */
+ ret = push_service_app_control_to_notification(app_control, op, &noti);
+
+ if (noti) {
+ /* Handle the noti */
+
+ /* Free the noti */
+ push_service_free_notification(noti);
+ } else {
+ /* Case when the application is not launched by the push service */
+ }
+ if (op)
+ free(op);
}
</pre></li>
<li>Store the notification at the push service database and request it later when the application is launched.
<p>You need to set the action to <span style="font-family: Courier New,Courier,monospace;">ALERT</span> or <span style="font-family: Courier New,Courier,monospace;">SILENT</span> in the message field when sending the notification from the application server. When such a notification arrives at the device, the push service keeps the notification in the database and waits for the request from the application.</p>
<p>The difference between the <span style="font-family: Courier New,Courier,monospace;">ALERT</span> and <span style="font-family: Courier New,Courier,monospace;">SILENT</span> actions is that the former shows an alert message in the quick panel and changes the badge count, while the latter does not. If the user clicks the alert message in the quick panel, the push service <a href="#force_launch">forcibly launches the application</a> and delivers the notification through the app control callback function.</p></li>
<li>Discard it.
-<p>You need to set the action to <span style="font-family: Courier New,Courier,monospace;">DISCARD </span>in the message field when sending the notification from the application server. When such a notification arrives at the device, the push service discards the notification unless the application is running.</p></li>
+<p>You need to set the action to <span style="font-family: Courier New,Courier,monospace;">DISCARD</span> in the message field when sending the notification from the application server. When such a notification arrives at the device, the push service discards the notification unless the application is running.</p></li>
</ul>
</li>
<pre class="prettyprint">
push_service_notification_h noti;
int ret;
-do
-{
- ret = push_service_get_unread_notification(push_conn, &noti);
+do {
+ ret = push_service_get_unread_notification(push_conn, &noti);
- // Process the unread message noti
+ /* Process the unread message noti */
- push_server_free_notification(&noti);
+ push_server_free_notification(&noti);
} while (1);
</pre>
projects / sdk / online-doc.git / commitdiff