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.
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. |
