BlackBerry Push APIs (part 3) - Building an Application that Uses the BlackBerry Push APIs - Checking the Status of a Push Request and Cancelling a Push Request

10/12/2013 3:20:51 AM

3.5 Checking the Status of a Push Request and Cancelling a Push Request

The push application can check the status of a push request by sending a statusquery-message control entity to the RIM Push Infrastructure and can cancel a push request by sending a cancel-message control entity. Because neither request types contain content being pushed to devices, these requests use a slightly modified version of the push request. For both, the request sent to the RIM push infrastructure contains just the XML control entity needed to define the parameters for the request, as shown in Figure 4.

Figure 4. PAP cancel-message and statusquery-message format

For these requests, the push application uses the same URL used when pushing data to a subscriber, where [push-domain] refers to one of the domains listed in Table 1:

https://[push-domain]/mss/PD_pushRequest

When sending one of these messages, the application must set the Content-Type HTTP request header to tell the receiving service the format of the request.

Content-Type: application/xml

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

HttpURLConnection mdsConn =
(HttpURLConnection)mdsUrl.openConnection();
mdsConn.setRequestProperty( "Content-Type", "application/xml"
);

Note

The documentation does not indicate that the PSID or credentials are included with either the cancel-message and statusquery-message requests, but it would seem that the RIM Push Infrastructure would need to have those values to identify the push service being updated.

3.6 Cancelling a Push Request

The cancel-message control entity cancels a push request for all or some push destinations. The RIM Push Infrastructure is only able to cancel a push request if the original push request is still pending (the data has not yet been delivered). A simple cancel-message control entity is shown here; in this example, the cancellation request being made only for a single device:

<pap>
  <cancel-message push-id="UniquePushID">
    <address address-value="DevicePIN1" />
  </cancel-message>
</pap>

A cancel-message control entity that cancels a push for all destinations would look like the following:

<pap>
  <cancel-message push-id="UniquePushID">
    <address />
  </cancel-message>
</pap>

The supported attributes for the cancel-message control entity elements are defined in Table 11.

Table 11. PAP Cancel-Message Control Entity Elements/Attributes
Element	Attributes
<cancel-message>	push-id: A unique ID associated with this particular request. This must be the same the ID used when the push request was submitted.
<address>	address-value: Specifies the device PIN for one or more destination devices. Use this attribute to define the list of destinations for which the push should be canceled. This allows you to cancel the push request only for certain destinations. If no addresses are included with the cancel-message, the push is cancelled for all recipients of the specified push.

A sample cancel-message request is shown here:

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 1.0//EN"
  "http://www.openmobilealliance.org/DTD/pap_1.0.dtd"
<pap>
  <cancel-message push-id="UniquePushID">
    <address address-value="DevicePIN1" />
  </cancel-message>
</pap>

When the RIM Push Infrastructure has processed the cancellation request, it returns an XML document that containing the results of the request, as shown here:

Content-Type: application/xml
<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 1.0//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_1.0.dtd">
<pap>
  <cancel-response push-id="UniquePushID">
    <cancel-result code="status-code" desc="Description" />
  </cancel-response>
</pap>

Table 12 lists the elements and the attribute values associated with each element in the cancel-response message.

Table 712. PAP Cancel-Response Elements/Attributes
Element	Attribute/Description
<cancel -response>	Push-ID: the unique Push ID associated with the push request.
<cancel -result>	Code: One of the status codes listed in Table 7. Desc: The description for the status code.

3.6 Checking the Status of a Push Request

The push application can check the status of any push request by sending a request containing a statusquery-message control entity to the RIM Push Infrastructure. The request must be submitted within 24 hours of the original push request. A simple statusquery-message control entity is shown here:

<pap>
  <statusquery-message push-id="UniquePushID">
    <address address-value="DevicePIN" />
  </statusquery-message>
</pap>

The supported attributes for the statusquery-message control entity elements are defined in Table 13.

Table 13. PAP Statusquery-Message Control Entity Elements/Attributes
Element	Attributes
<statusquery-message>	push-id: The unique ID of the request being queried for status. This must be same the ID used to submit the push.
<address>	address-value: The device PIN for one or more destination devices.

To query the status for every device listed in the original push request, submit the statusquery-message control entity without specifying an address element, as shown in the following example:

<pap>
  <statusquery-message push-id="UniquePushID" />
</pap>

A sample statusquery-message request for a single device is shown here:

Content-Type: application/xml
<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 1.0//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_1.0.dtd">
<pap>
  <statusquery-message push-id="UniquePushID">
    <address address-value="DevicePIN1" />
  </statusquery-message>
</pap>

When the RIM Push Infrastructure has received and processed the request, it returns an XML document containing the status for the push request for the specified (or all) recipient devices, as shown here:

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.0//EN"
"http://www.openmobilealliance.org/tech/DTD/pap_2.0.dtd">
<pap>
  <statusquery-response push-id="UniquePushID">
    <statusquery-result
      event-time="2009-03-05T20:51:05Z"
      message-state="pending"
      code="status-code"
      desc="the request has been accepted for processing.">
        <address address-value="somePIN" />
    </statusquery-result>
  </statusquery-response>
</pap>

The supported attributes for the statusquery-response control entity elements are defined in Table 14.

Table 14. PAP Statusquery-Message Response Address Attributes
Address Attribute	Description/Possible Values
Message-state	One of the Message state options listed in Table 9.
code	A list of status codes is provided in Table 7.
Desc	A description of the result code.