BlackBerry Push APIs (part 2) - Building an Application that Uses the BlackBerry Push APIs - Unsubscribing From the Push System, Pushing Data to a Subscriber

- Free product key for windows 10
- Free Product Key for Microsoft office 365
- Malwarebytes Premium 3.7.1 Serial Keys (LifeTime) 2019
3.3 Unsubscribing From the Push System

When a subscriber no longer wants to receive content from the service, the device-side application must notify the RIM Push Infrastructure and, if the listener application registered with the push application, notify the push application as well. To unsubscribe with the RIM Push Infrastructure, the following URL must be used:


The push parameters are described in Table 4.

Table 4. BlackBerry Push API Deregistration URL Parameters
Registration ParameterDescription
Push-DomainThe regional domain that the push recipient resides in. Refer to Table 1 for the possible values for this parameter.
Service-IDThe unique ID for the push service; this value will be provided during registration of the service.

For a North American subscriber, the POST URL would look something like this:

The RIM Push Infrastructure responds with a string of encrypted data that the application must return (within a certain timeframe) to the RIM Push Infrastructure for the deregistration process to complete successfully. The return URL looks similar to the previous one except for the addition of the encrypted data to the end of the URL. The follow-up registration URL is performed via another HTTP POST and is in the following format, where [Encrypted-Data] is replaced with the content received from the server on the first request:


If the RIM Push Infrastructure returned someencryptedvalue from the initial registration request, the subsequent POST URL looks like this:

The RIM Push Infrastructure returns a response code, indicating the status of the request in the format of rc=some-value, where some-value is one of the response codes listed in Table 5.

Table 5. BlackBerry Push API Deregistration Request Result Codes
Response CodeDescription
200The deregistration was completed successfully.
10004The deregistration process has already been completed by the user.
10005The deregistration process has already been completed by the service provider.

The device-side application is also responsible for notifying the content provider service of the unsubscribe using whatever mechanism is appropriate for the application.

This concludes the discussion of the push receiver, device-side application. The remaining activities related to the BlackBerry Push APIs are all performed from the backend push application.

3.4 Pushing Data to a Subscriber

When the push application is ready to send data to one or more subscriber devices, the application must submit a push request to the RIM Push Infrastructure containing the data being delivered. The push request is a simple PAP request. Because the application merely pushes data to a destination application, the format of the push request is much simpler because many of the push parameters used for browser push don’t apply and are, therefore, not needed.

For a PAP push request, the message body is sent as a MIME multipart message, as shown in Figure 3. The MIME message contains an XML document that describes the push (the control entity), plus the data that is pushed to the destination device(s). The boundary shown in the figure is just a random series of characters that is not included anywhere as part of the message content. It distinguishes between the different parts of the MIME multipart message.

Figure 3. PAP Push Request Format

When pushing data to a subscriber, the push application uses the following URL for the HTTP POST request sent to the RIM Push infrastructure, where push-domain refers to one of domains listed in Table 1:


The HTTP POST request must contain two header values: Content-Type and Authorization. The push application must set the Content-Type HTTP request header to tell the receiving service the format of the request. In the Content-Type header, the application can use any boundary string, as long as it is unique (not used anywhere else in the message). The following example just uses some random characters typed on the keyboard:

Content-Type:multipart/related; type="application/xml";

In Java, the header can be set using the following code:

HttpURLConnection psConn =
psConn.setRequestProperty( "Content-Type", "multipart/related;
type=\"application/xml\"; boundary=jausyhstaositate" );

The application delivers the credentials for the push request in the Authorization header. The credentials are passed as a Base64 encoded combination of the provider’s push service ID (PSID) and password (PSID:Password). To perform this operation in Java, use the following code:

String auth = "Basic " + new BASE64Encoder().encode((psid + ":"
+ pswd).getBytes());
psConn.setRequestProperty("Authorization", auth);

After the request headers are set up correctly, it’s time to format the content of the message. As shown in Figure 3, the first component of the push request is an XML control entity that describes the push request. A simple push-message control entity is shown here that defines a push request for a single device PIN:

<push-message push-id="UniquePushID" source-reference="PSID">
<address address-value="DevicePIN1" />

To push to multiple devices, the push request would contain multiple address elements, as shown here:

<push-message push-id="UniquePushID" source-reference="PSID">
<address address-value="DevicePIN1" />
<address address-value="DevicePIN2" />
<address address-value="DevicePIN3" />

If the application needed to push to all subscribers, the push request would look similar to the one shown here:

<push-message push-id="UniquePushID" source-reference="PSID">
<address address-value="push_all" />

The application can specify additional (optional) elements/attributes in the control entity, as shown here:

<push-message push-id="UniquePushID" source-reference="PSID"
deliver-before-timestamp="sometime" >
<address address-value="DevicePIN1" />
<quality-of-service delivery-method="confirmed" />

The supported attributes for the push-message control entity elements are defined in Table 5.

Table 5. PAP Push Push-Message Control Entity Elements/Attributes
<push-message>push-id: A unique ID associated with this particular push request. The ID must be provided with any subsequent requests cancelling or requesting the status of the push request. The push application is responsible for generating this unique push-id. This is a required attribute for the push-message element.

source-reference: The unique Push Service ID (PSID) assigned to the push service when it was registered with the RIM Push Infrastructure. The ID identifies the push content provider, the push application, and the port number the data is delivered to on the destination device. This is a required attribute for the push-message element.

ppg-notify-requested-to: Specifies the URL that is triggered by the RIM Push Infrastructure when the push request has been processed. This is an optional attribute for the push-message element; if no value is provided, the push application is not notified when the pushed content has been delivered.

deliver-before-timestamp: Specifies the date and time that the push must be delivered before. If the content is not delivered by this date/time, it is discarded by the RIM Push Infrastructure. The value provided here must be in Coordinated Universal Time (UTC). Example: ‘2009-02-11T11:00:00Z’ where the Z at the end of the string indicates UTC. This is a required attribute for the push-message element.
<address>address-value: Specifies the address of one or more destination devices. The address-value must be a valid device PIN that has already been registered in the RIM Push Infrastructure for this push application. This is a required element for the push request.
<quality-of-service>delivery-method: Specifies the delivery reliability for the push message. The attribute values defined below here define criteria for determining successful delivery of the push content. Possible values are:

confirmed: A message is considered delivered when the content has been delivered to the destination application on the device.

notspecified, preferconfirmed, or unconfirmed: A message is considered delivered when the content has been delivered to the destination device.

In order to have a delivery notification sent to the push application, the request must also enable the ppg-notify-requested-to attribute defined above.

The following is an example of what the push message would look like when sent to the RIM Push Infrastructure:

Content-Type: application/xml; charset=UTF-8

<?xml version="1.0"?>
[<?wap-pap-ver supported-versions="2.0,1.*"?>]>
<push-message push-id="UniquePushID" source-reference="PSID">
<address address-value="DevicePIN1" />
CouponTitle="Really Great Deal"
CouponExpiry="September 12, 2009"
CouponDetails="Act now to receive 20% off on all products"

When the RIM Push Infrastructure has processed the push request, it returns an HTTP result code and an XML document containing information about the results of the request. The server returns either a 200 (OK) or a 202 (Accepted); any other status code indicates that there was a problem with the push. A sample of the XML document returned is shown in the following example:

Content-Type: application/xml
<?xml version="1.0"?>
<push-response push-id="UniquePushID"
sender-name="RIM Push-Data"
<response-result code="status-code" desc="Description" />

Table 6 lists the elements and the attribute values associated with each element in the response message.

Table 6. PAP Push Response Elements/Attributes
<push-response>Push-ID: The unique Push ID associated with the push request

Sender-Address: The name of the server sending the response

Reply-Time: The date and time (in Coordinated Universal Time [UTC]) that the reply was sent
<response-result>Code: One of the status codes listed in Table 7 Desc: The description for the status code

Table 7 contains the list of PAP response status codes used by the push-response message and other response messages from the RIM push infrastructure.

Table 7. PAP Response Status Codes
Status CodeDescription
1000The request succeeded (the data reached the destination device).
1001The request has been accepted for processing (the push request has been accepted by the server but has not been validated for delivery to the destination device).
2000The request is invalid (malformed syntax).
2001The requested action is forbidden or the request was refused.
2002The specified PIN is not recognized.
2003Address not found.
2004The Push ID specified was not found for the provided push service.
2005Capabilities mismatch.
2006Required capabilities not supported by client.
2007The Push ID specified is not unique.
2008The Push ID was located, but cancellation is not possible.
3000Internal server error.
3001The server does not support the requested operation.
3002Version not supported.
3003The action is not possible because the message is no longer available.
3006Transformation failure.
3007Specified delivery method not possible.
4000Service failure.
4001Service unavailable.
4500The request has expired.
4501The request failed.
4502The push request failed because the BlackBerry device listen port was closed.
5xxxThe mobile client aborted the operation.

The push application must parse the response message to determine the results of the push request. The application can also receive a notification when the data actually arrives on the device by specifying a URL in the ppg-notify-requested-to attribute of the push-message element in the push request.

When the application specifies a ppg-notify-requested-to URL in the push request, depending on the quality of service defined in the request, the RIM Push Infrastructure triggers the URL when the data arrives on the device (quality-of-service confirmed) or when the data arrives at the destination application (all other options for quality-of-service). Additionally, the PAP specification indicates that this mechanism can also notify when an error has occurred. Because there’s no guarantee that the RIM Push Infrastructure is able to deliver the push, the push application should use this mechanism to detect whether the push was delivered and, if the data is important enough to the subscriber, push the data again if it wasn’t delivered.

The response from the RIM Push Infrastructure is delivered in the form of a Result Notification Response message. This message is an XML control entity containing information about the status of the push message. The PAP specification indicates that the result message could be a MIME multipart message containing XML control entities from both the push service and the device, but RIM does not seem to support that option. A sample result notification message is shown here:

<?xml version="1.0"?>
<resultnotification-message push-id="UniquePushID"
sender-name="RIM Push-Data"
message-state="Message State"
<address address-value="DevicePIN1" />

Table 8 lists the possible elements and attributes for the response message.

Table 8. PAP Resultnotification-Message Elements/Attributes
<resultnotification-message>Push-ID: The unique Push ID associated with the push request.

Sender-Address: The URL for the server sending the response.

Sender-Name: A descriptive name for the response sender.

Message-State: One of the Message state options listed in Table 9.

Code: One of the status codes listed in Table 7.

Desc: The description for the status code.

Received-Time: The date and time (in Coordinated Universal Time [UTC]) when the push request was received by the RIM Push Infrastructure.

Event-Time: The date and time (in Coordinated Universal Time [UTC]) that the push request reached its completed state.
<Address>Address-Value: The device PIN for which the response is associated.
<quality-of-service>Delivery-Method: If a quality of service element was included in the original push request, it is included in the response.

Table 9 contains the list of possible Message State attributes for the response message.

Table 9. Message State Options
Message StateDescription
AbortedThe destination BlackBerry device aborted the delivery process.
CancelledThe push message was cancelled by the content provider before the content was delivered to the destination BlackBerry device.
DeliveredThe push content was successfully delivered to the destination BlackBerry device.
ExpiredThe push message reached its maximum age (defined in seconds in the push request) before it could be delivered by the RIM Push Infrastructure.
PendingThe push message is still in queue, it has not been processed yet.
RejectedThe push message was not accepted for delivery by the RIM Push Infrastructure.
TimeoutThe delivery process timed-out.
UndeliverableThe push message cannot be delivered to the destination BlackBerry device.
UnknownAn unknown error has occurred.

The push application is responsible for responding to the RIM Push Infrastructure acknowledging receipt of the result notification. A sample resultnotification-response message is shown here:

<?xml version="1.0"?>
<resultnotification-response push-id="UniquePushID"
code="1000" desc="OK" />

Table 10 contains a listing of the possible attributes for the resultnotification-response element in the Result Notification Response message.

Table 10. PAP Push Resultnotification-Response Element Attributes
Push-idA unique ID associated with a particular push request. The push application is responsible for generating this unique push-id and including it with the initial push request.
CodeOne of the result codes listed in Table 7.
DescThe textual description for the result code.

It’s likely that the push application would always respond with a 1000, indicating that the response was received successfully.

Top 10
Free Mobile And Desktop Apps For Accessing Restricted Websites
TOYOTA CAMRY 2; 2.5 : Camry now more comely
KIA SORENTO 2.2CRDi : Fuel-sipping slugger
How To Setup, Password Protect & Encrypt Wireless Internet Connection
Emulate And Run iPad Apps On Windows, Mac OS X & Linux With iPadian
Backup & Restore Game Progress From Any Game With SaveGameProgress
Generate A Facebook Timeline Cover Using A Free App
New App for Women ‘Remix’ Offers Fashion Advice & Style Tips
SG50 Ferrari F12berlinetta : Prancing Horse for Lion City's 50th
- Messages forwarded by Outlook rule go nowhere
- Create and Deploy Windows 7 Image
- How do I check to see if my exchange 2003 is an open relay? (not using a open relay tester tool online, but on the console)
- Creating and using an unencrypted cookie in ASP.NET
- Directories
- Poor Performance on Sharepoint 2010 Server
- SBS 2008 ~ The e-mail alias already exists...
- Public to Private IP - DNS Changes
- Send Email from Winform application
- How to create a .mdb file from ms sql server database.......
programming4us programming4us