BlackBerry push format

Your server-side application can use the BlackBerry push format to send both the data and the delivery parameters to the BlackBerry MDS Connection Service in a single byte stream.

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>/push?DESTINATION=
  <destination>&PORT=<client_port>&REQUESTURI=<uri>
<headers>
<data>

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, 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.
  • destination is the recipient email address, BlackBerry device PIN, or BlackBerry user group name, to whom the BlackBerry MDS Connection Service should push the data. To specify multiple recipient addresses, include a separate DESTINATION parameter for each intended recipient email address or BlackBerry device PIN.
  • port is the port number or a string representing the application ID with which your client-side application sets parameters to listen for pushed data. Custom BlackBerry Java Applications should each listen on a unique port.
  • uri is the URL sent to the BlackBerry device.
  • headers are the HTTP headers that specify the delivery parameters, such as reliability level or delivery time stamp. If you're pushing data to the BlackBerry Browser, you must also include the browser-specific HTTP headers.
  • data is a byte stream containing the data that the BlackBerry MDS Connection Service must deliver to the recipient BlackBerry devices.

HTTP headers for the BlackBerry push format

Header

Description

X-Rim-Push-Id

Specifies a unique string that uniquely identifies the push request.

To ensure that the string is unique, specify a URL with a value, such as 123@rim.com.

X-Rim-Push-Description

Specifies a description for the push request. This header is optional.

X-Rim-Push-Reliability

Specifies the level of reliability of your push request. This header is optional. If you specify a value for this header, you must also specify a value for X-Rim-Push-NotifyURL.

You can specify one of the following values:

  • transport: The BlackBerry device sends a response to the BlackBerry MDS Connection Service when the pushed data has arrived at the device.

  • application: The BlackBerry device sends a response to the BlackBerry MDS Connection Service when the pushed data has arrived at the client application's listening port number .
  • application-preferred: On devices running BlackBerry Device Software 3.8 or later, the BlackBerry device sends a response to the BlackBerry MDS Connection Service when the pushed data has arrived at the client application's listening port number. On devices running BlackBerry Device Software 3.7 or earlier, the BlackBerry device sends a response when the pushed data arrives at the device.

X-Rim-Push-NotifyURL

Specifies a URL to which the BlackBerry MDS Connection Service can post result notification messages. If you specify a value for X-Rim-Push-Reliability, you must also specify a value for this header.

X-RIM-Push-Deliver-Before

Specifies the date and time, in HTTP format, before which the push request must be delivered. This header is optional. For recipients that have not received the pushed data by this time, the push request is considered unsuccessful.

X-RIM-Push-Deliver-After

Specifies the date and time, in HTTP format, after which the push request must be delivered. This header is optional. For recipients that cannot receive the pushed after this time, the push request is considered unsuccessful.

Receiving a BlackBerry push format result notification

If you use the BlackBerry push format, the response information is returned in the headers of the HTTP POST request.

Header

Description

X-RIM-Push-ID

This header provides the ID that you specified in the original push request. If it is not specified, then the BlackBerry MDS Connection Service generates a random push request ID.

X-RIM-Push-Status

This header indicates the success or failure of the push request. A response status of 200 indicates a successfully delivered push request.

X-RIM-Push- Destination

This header contains the email address, BlackBerry device PIN, or BlackBerry device user group name to which the push request was sent.

Response codes for the BlackBerry push format

Response code

Description

200

The push request was accepted by the BlackBerry MDS Connection Service.

400

A general error occurred. This response is likely caused due to an invalid push format.

403

The BlackBerry device is not associated with the BlackBerry Enterprise Service, or push access control has been enabled on the BlackBerry Enterprise Service and the server making the push request does not have permission to push data.

404

The push request was not received by the BlackBerry MDS Connection Service. Verify that you have supplied the correct URL and application ID passed in the port field for the BlackBerry MDS Connection Service in your push request.

503

The BlackBerry MDS Connection Service is busy or is unable to manage the push request due to temporary overloading or server maintenance.

By default, the BlackBerry MDS Connection Service is configured to manage 1000 simultaneous push requests, including push requests that have previously been accepted and are pending delivery.