PAP push format

Your server-side application can use the PAP push format to send three types of requests to the BlackBerry MDS Connection Service:

  • Push request: This request allows you to push data to the specified recipients. A PAP push request is a MIME multipart message which contains a PAP control entity that defines the delivery parameters, and the data to be pushed.
  • Status-query request: This request allows you to query the status of a push request for one or more specified recipients. A PAP status-query request includes an XML-based PAP control entity, which identifies the associated push request, and lists the recipient addresses for which the push request status should be queried.
  • Cancellation request: This request allows you to cancel a push request for one or more specified recipients. A PAP cancellation request includes an XML-based PAP control entity, which identifies the associated push request, and lists the recipient addresses for which the push request should be cancelled.

In each case, you send the request as an HTTP POST request to the BlackBerry MDS Connection Service. If the BlackBerry MDS Connection Service is configured to support secure connections, you can use the HTTPS protocol. The HTTP POST request must use the following format:

POST http://<MDS_CS>:<MDS_CS_port>/pap
<message>

The variables in the request contain the following information:

  • <MDS_CS> is the URL address of the BlackBerry MDS Connection Service web server. If you're unsure of the URL address of the BlackBerry MDS Connection Service, contact your BlackBerry Enterprise Service administrator.
  • <MDS_CS_port> is the port number on which the BlackBerry MDS Connection Service web server listens. By default, the BlackBerry MDS Connection Service listens on port number is 8080. If you are unsure of the port number, contact your administrator.
  • <message> is either a multipart message with the PAP control entity and the data (in the case of push requests), or a PAP control entity on its own (in the case of status-query and cancellation requests).

Constructing a PAP control entity

A PAP control entity is an XML document which contains the control information that is required by the Push Access Protocol. When a PAP control entity is included in a multipart message, as in a push request, it must be the first entity in the message.

The BlackBerry MDS Connection Service supports three request types: a push request, a cancellation request, and a status-query request. These request types each correspond to a different PAP control entity: the push message control entity, the cancellation message control entity, and the status-query message control entity.

All PAP control entities have three common document elements: the XML declaration, the DOCTYPE declaration, and a root <pap> element. Because the BlackBerry MDS Connection Service supports only WAP PAP version 2.0, the DOCTYPE declaration included in all PAP control entities must specify supported version information.

The following code sample shows you how to format a PAP control entity to send to the BlackBerry MDS Connection Service.

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.0//EN" 
          "http://www.openmobilealliance.org/tech/DTD/pap_2.0.dtd" 
          [<?wap-pap-ver supported-versions="2.0"?>]>
<pap>

    <-- message-specific elements go here -->

</pap>

For more information about PAP control entities, see the Push Access Protocol specification at http://www.openmobilealliance.org.

Elements of a PAP push message

Element

Attribute

Description

<pap>

 

Defines a PAP control entity.

<push-message>

push-id

ppg- notify- requested- to

deliver- before- timestamp

deliver- after- timestamp

Specifies a request to push data to a BlackBerry device.

You must include one or more <address> elements in the <push-message> element to specify the recipient addresses.

You can optionally include a <quality-of-service> element in the <push-message> element to specify the reliability level of the push request.

You must include the push-id attribute, which specifies a string that uniquely identifies the push request. To ensure that the string is unique, it is recommended that you specify a URL with a value, such as 123@blackberry.com.

You can also include the following attributes:

  • ppg- notify- requested- to : Specifies a URL to which the BlackBerry MDS Connection Service can post result notification messages. If you include the value for <quality-of-service> element, you should specify a value for this attribute.
  • deliver- before- timestamp and deliver- after- timestamp: Specify the date and time, in 24-hour UTC format, before or after which the push request must be delivered, or the push request is considered unsuccessful. These attributes are optional.

<address>

address- value

Specifies a single recipient of the push request.

You must include the address-value attribute to specify the recipient address. The address-value attribute uses the following format:

WAPPUSH=<recipient>/TYPE=USER@blackberry.com

where <recipient> is the email address, BlackBerry device PIN, or BlackBerry user group name.

The port number on which the client-side listener application listens is specified using the X-Rim-Push-Dest-Port header.

 

If the X-Wap-Application-Id header is provided in the request, then that header represents the Application Id. If this header is not present, then the X-Rim-Push-Dest-Port header is being considered to be the Application ID.

All non-alphanumeric characters in the device email portion of the address-value attribute, other than "+", "-", ".", or "_" must be URL encoded as hexadecimal values in the PAP control entity.

You can include multiple <address> elements in a <push-message> element, one for each recipient address you want to specify.

<quality-of-service>

delivery- method

Specifies the level of reliability for the push request. The value you specify defines the criteria for a successful outcome of the push request.

The BlackBerry MDS Connection Service supports the delivery- method attribute, which can have one of the following values.

This attribute can have any of the following values:

  • confirmed: This value is equivalent to application-level reliability.

  • unconfirmed, preferconfirmed, or notspecified: These values are equivalent to transport-level reliability. The BlackBerry Infrastructure treats these values identically.

This attribute does not imply any notification from the BlackBerry MDS Connection Service specifying the outcome of the push request. To receive a result notification, you must set the ppg- notify- requested- to attribute of the <push-message> element.

Submitting a PAP push request

The following code sample shows an example of the push request that is sent to the BlackBerry MDS Connection Service. This request is a multipart message that includes a PAP push message control entity and the pushed data.

The PAP push message control entity requests the BlackBerry MDS Connection Service to push accompanying data to two individual BlackBerry device users (user1@blackberry.com and user2@blackberry.com). The <quality-of-service> element defines this request as application-reliable.

Special characters specified in the email address portion of the address-value attribute are URL encoded, as specified in the WAP PAP 2.0 specification.

The data portion of the multipart message includes a number of browser push headers, which specify a browser channel and the icons that represent the browser channel on the Home screen.

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

--asdlfkjiurwghasf
Content-Type: application/xml

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.0//EN" 
          "http://www.openmobilealliance.org/tech/DTD/pap_2.0.dtd" 
          [<?wap-pap-ver supported-versions="2.0"?>]>

<pap>
  <push-message push- id="_done123@foo.blackberry.com13522321633359"
        deliver-before-timestamp="2009-12-31T13:30:00Z"
        ppg-notify-requested-to="http://blackberry.com/ReceiveNotify">
    <address address-value="WAPPUSH=user1%40blackberry.com%3A7874/
       TYPE=USER@blackberry.com"/>
    <address address-value="WAPPUSH=user2%40blackberry.com%3A7874/
       TYPE=USER@blackberry.com"/>
    <quality-of-service  delivery-method="confirmed"/>
  </push-message>
</pap>

--asdlfkjiurwghasf
Content-Encoding: binary
Content-Type: text/html
X-Wap-Application-Id: /
X-Rim-Push-Type: browser-channel
X-Rim-Push-Title: Test
X-Rim-Push-Unread-Icon: http://rim.com/icon_new.png
X-Rim-Push-Read-Icon: http://rim.com/icon_viewed.png
X-Rim-Delete-URL: http://rim.com/ReceiveDelete
X-Rim-Transcode-Content: */*
Cache-Control: max-age=3600

Text or binary content to be delivered to BlackBerry device goes here.

 --asdlfkjiurwghasf–-

Elements of a PAP cancellation message

Element

Attribute

Description

<pap>

 

Defines a PAP control entity.

<cancel-message>

push-id

Specifies a request to cancel a previously submitted push request.

You can optionally include one or more <address> elements in the <cancel- message> element to indicate for which recipients the original push request should be cancelled. If you do not include an <address> element, then the cancellation request applies to all recipients specified in the original push request.

You must include the push-id attribute, which specifies the push ID of the push request to cancel.

<address>

address- value

Specifies a single recipient of the push request. Any recipients specified must match recipients specified in the original push request. This element is optional.

If you include the <address> element, you must include the address-value attribute to specify the recipient address. The address-value attribute uses the following format:

WAPPUSH=<recipient>%3A<port>/TYPE=USER@rim.com

where <recipient> is the email address, BlackBerry device PIN, or BlackBerry user group name, and <port> is the port number on which the client-side listener application listens.

All non-alphanumeric characters in the device email portion of the address-value attribute, other than "+", "-", ".", or "_" must be URL encoded as hexadecimal values in the PAP control entity.

You can include multiple <address> elements in a <cancel-message> element, one for each recipient address you want to specify.

Submitting a PAP cancellation request

The following code sample shows an example of the cancellation request that is sent to the BlackBerry MDS Connection Service. The PAP cancellation message control entity requests that the BlackBerry MDS Connection Service cancel the push request (push- id="_done123@rim.com13522321613992").

Because the <cancel-message> element does not contain any <address> elements, the cancellation request applies to all recipient addresses specified in the original push request.

 
<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.0//EN" 
          "http://www.openmobilealliance.org/tech/DTD/pap_2.0.dtd" 
          [<?wap-pap-ver supported-versions="2.0"?>]>

<pap>
  <cancel-message push- id="_done123@rim.com13522321619461">
  </cancel-message>
</pap>

Elements of a PAP status-query message

Element

Attribute

Description

<pap>

 

Defines a PAP control entity.

<statusquery-message>

push-id

Specifies a request to check the status of a previously submitted push request.

You can optionally include one or more <address> elements in the <statusquery- message> element to indicate for which recipients the original push request the status should be queried. If you do not include an <address> element, then the status-query request applies to all recipients specified in the original push request.

You must include the push-id attribute, which specifies the push ID of the push request to query.

<address>

address- value

Specifies a single recipient address of the push request. Any recipients specified must match recipients specified in the original push request. This element is optional.

If you include the <address> element, you must include the address-value attribute to specify the recipient address. The address-value attribute uses the following format:

WAPPUSH=<recipient>%3A<port>/TYPE=USER@rim.com

where <recipient> is the email address, BlackBerry device PIN, or BlackBerry user group name, and port is the ApplicationID which sets the parameters for the client-side listener.

All non-alphanumeric characters in the device email portion of the address-value attribute, other than "+", "-", ".", or "_" must be URL encoded as hexadecimal values in the PAP control entity.

You can include multiple <address> elements in a <statusquery-message> element, one for each recipient address you want to specify.

Submitting a PAP status-query request

The following code sample shows an example of the status-query request that is sent to the BlackBerry MDS Connection Service. The PAP status-query message control entity requests the BlackBerry MDS Connection Service to return the status of the push request (push- id="_done123@.rim.com13522321639352") for one BlackBerry user group (Marketing). Only one status is returned for the entire group. If all members have received the data except for one, the message state is returned as pending.

Special characters specified in the value of the address-value attribute are URL encoded, as specified in the WAP PAP 2.0 specification.

<?xml version="1.0"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.0//EN" 
          "http://www.openmobilealliance.org/tech/DTD/pap_2.0.dtd" 
          [<?wap-pap-ver supported-versions="2.0"?>]>

<pap>
  <statusquery-message push- id="_done123@.rim.com13522321631714">
    <address address-value="WAPPUSH=%24Marketing/TYPE=USER@rim.com"/>
  </statusquery-message>
</pap>

Receiving a PAP push format result notification

If you use the PAP push format, the BlackBerry MDS Connection Service sends the result notification as a PAP result notification control entity.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE pap PUBLIC "-//WAPFORUM//DTD PAP 2.0//EN"
          "http://www.wapforum.org/DTD/pap_2.0.dtd"
          [<?wap-pap-ver supported-versions="2.0"?>]>

<pap product-name="Research In Motion Ltd. Mobile Data Service">
    <resultnotification-message code="1000" 
           message-state="delivered"   
           event-time="2007-05-02T16:34:41Z" 
           received-time="2007-05-02T16:34:38Z" 
           sender-name="YOUR_MDS_CS_SERVER" 
           sender-address="http://YOUR_BES_NAME:8080/pap" 
           push- id="_done9f0e39jbf084@pi.com13522321797410">
        <address address-value="WAPPUSH=YOUR_EMAIL_ADDRESS%
           40YOUR_DOMAIN%2ecom/TYPE=USER@rim.net"/>
        <quality-of-service delivery-method="confirmed"/>
    </resultnotification-message>
</pap>