push applications - development guide

Push applicationsfor the BlackBerry Enterprise Server

Development Guide

Published: 2009-10-06SWD-915141-1006101942-001

Contents1 Overview....................................................................................................................................................................................... 3

Server-side push applications....................................................................................................................................................... 3

Supported push formats........................................................................................................................................................ 4

Client-side listener applications................................................................................................................................................... 4

How the BlackBerry MDS Connection Service pushes data...................................................................................................... 5

How the BlackBerry MDS Connection Service controls the flow of pushed messages................................................. 5

Storing push requests in the BlackBerry Configuration Database................................................................................... 6

2 Making a push request............................................................................................................................................................... 7

Pushing data to multiple BlackBerry device users...................................................................................................................... 7

Pushing data to multiple recipient addresses..................................................................................................................... 7

Pushing data to a BlackBerry user group............................................................................................................................ 8

Using push request reliability........................................................................................................................................................ 9

Levels of reliability.................................................................................................................................................................. 10

Receiving push result notifications...................................................................................................................................... 11

Specifying time restrictions for push delivery............................................................................................................................. 12

Querying the status of push requests.......................................................................................................................................... 12

Cancelling a pending push request.............................................................................................................................................. 13

3 Overview of the PAP push format............................................................................................................................................. 14

Constructing a PAP control entity................................................................................................................................................ 14

Elements of a PAP push message........................................................................................................................................ 15

Elements of a PAP cancellation message............................................................................................................................ 18

Elements of a PAP status-query message........................................................................................................................... 19

Code sample: Receiving a PAP push format result notification................................................................................................ 21

4 Overview of the RIM push format............................................................................................................................................. 22

HTTP headers for the RIM push format........................................................................................................................................ 22

Receiving a RIM push format result notification......................................................................................................................... 23

Response codes for the RIM push format.................................................................................................................................... 24

5 Pushing content to the BlackBerry Browser............................................................................................................................ 26

Pushing content to a browser channel......................................................................................................................................... 27

Deleting a browser channel from the BlackBerry device................................................................................................... 28

Pushing content to the messages application............................................................................................................................ 29

Pushing content to the browser cache......................................................................................................................................... 29

Additional considerations when pushing content to the BlackBerry Browser........................................................................ 30

Defining cache control properties........................................................................................................................................ 30

Transcoding content.............................................................................................................................................................. 31

HTTP headers used by the BlackBerry Browser........................................................................................................................... 31

Additional HTTP headers you can use with browser pushes..................................................................................................... 33

6 Provide feedback......................................................................................................................................................................... 35

7 Legal notice.................................................................................................................................................................................. 36

Overview 1

Application developers can use the BlackBerry® MDS Connection Service component of the BlackBerry® Enterprise Server toproactively deliver data or web content directly to BlackBerry devices that are activated on an organization’s BlackBerry EnterpriseServer. Users do not need to request or download data; the push application, in conjunction with the BlackBerry MDS ConnectionService, delivers it as soon as it is available.

To push data to a BlackBerry device, two applications are required: a server-side push application, which submits the push request,and a client-side listener application, which listens for incoming push messages.

• The server-side push application is designed to send HTTP POST requests to the BlackBerry MDS Connection Service onthe web server listen port. The HTTP POST requests contain delivery parameters and the data to be pushed. The BlackBerryMDS Connection Service then delivers the data to a specified port number on the BlackBerry device within a specified timeframe. Developers must create the server-side application. Push requests generated by this application must conform toeither the WAP PAP 2.0 specification or to the RIM push format.

• A client-side listener application listens for data to be delivered to its specific port number. You can create a customBlackBerry® Java Application that is designed to listen for and handle pushed data, or you can push web content to theBlackBerry® Browser. The BlackBerry Browser has an integrated listener thread, which allows you to push web content tothe BlackBerry device without the need to create a custom client-side application.

The BlackBerry MDS Connection Service manages the flow of pushed data from various push applications, and sends the datato the BlackBerry device using the same encrypted channel that is used for data communication between the device and theBlackBerry Enterprise Server. The BlackBerry MDS Connection Service can push data to individual users or to user groups.

Server-side push applicationsServer-side push applications make requests to the BlackBerry® MDS Connection Service to push data to specified BlackBerrydevice users. These requests include push delivery parameters that uniquely identify the push request, inform the BlackBerryMDS Connection Service which devices to send the data to, and provide additional delivery information, such as the priority andthe reliability level of the push request.

You can create a server-side push application using any development language. However, the application must generate andsend HTTP POST requests to the BlackBerry MDS Connection Service and use either the PAP push format or RIM push formatto specify the delivery parameters.

You can push data to individual users based on either their email addresses or their device PINs, or to groups of users createdand maintained on the BlackBerry® Enterprise Server.

RIM Confidential and Proprietary Information - Beta Customers Only. Content and software are subject to change.

3

Supported push formatsThe push format you use for push requests not only affects the format in which the delivery parameters are specified, but alsoaffects how the data is packaged within the POST request.

The BlackBerry® MDS Connection Service supports the following push formats:

Push format Description

PAP push format This push format sends an HTTP POST request to the BlackBerry MDS Connection Service. The request

contains a MIME multipart message that includes two components: an XML-based PAP control entity

that defines the delivery parameters, and the data to be pushed.

The PAP push format is an open standard developed by the Open Mobile Alliance. The BlackBerry

MDS Connection Service supports the WAP PAP 2.0 standard.

RIM push format This push format sends an HTTP POST request to the BlackBerry MDS Connection Service. However,

in this case, the pushed content is sent as a byte stream. The destination port is specified within the

URL of the pushed content, and the destination users and other delivery parameters are specified in

HTTP headers included with the request.

The RIM push format is a proprietary push format supported exclusively by the BlackBerry MDS

Connection Service and BlackBerry device. Although it

Client-side listener applicationsClient-side listener applications on the BlackBerry® device listen for incoming data. You can create a custom listener applicationusing Java®, or you can use the BlackBerry® Browser as your listener application.

• Using a custom listener application: You can create a custom BlackBerry Java Application that contains a listening threadthat listens for incoming data on a specified port.

To create a Java-based push application architecture, you must create both the custom client-side application that receivesthe pushed data and the server-side application that makes the push request.

This approach requires developers with some knowledge of Java® ME, as well as an understanding of BlackBerry applicationdesign and development. However, creating a custom BlackBerry Java Application can provide you with control over boththe type of data that you can deliver and the manner in which this data is processed and displayed on the BlackBerry device.


4

• Using the BlackBerry Browser: The BlackBerry Browser on the BlackBerry device contains a built-in listening thread, whichlistens on port 7874. You can push web content or other browser-supported data to the BlackBerry Browser, which storesit in a cache dedicated to pushed content. When the BlackBerry device user views the URL associated with the pushedcontent, the browser retrieves the content from the cache and displays it, rather than making an HTTP request for the content.

You can add an icon to the BlackBerry device Home screen that is associated with your push request. To the user, the iconlooks like an application, but it simply opens an instance of the BlackBerry Browser to the URL associated with the pushedcontent.

If you use the BlackBerry Browser as your client-side listener application, you must only create the server-side applicationthat makes the push request.

How the BlackBerry MDS Connection Service pushes data

How the BlackBerry MDS Connection Service controls the flow of pushed messages

The BlackBerry® MDS Connection Servicecontrols the flow of data that is sent to the BlackBerry device. This flow control allowsthe BlackBerry MDS Connection Service to minimize the amount of data that is sent over the wireless network, and can help toreduce the impact of pushing data to BlackBerry devices that are out of network coverage, turned off, or otherwise unavailable.

The BlackBerry MDS Connection Service sends data to each BlackBerry device specified in the push request as a series of packets.To control the flow of pushed data, the BlackBerry MDS Connection Service initially sends a maximum of five packets. TheBlackBerry MDS Connection Service does not send additional packets until the BlackBerry device returns an acknowledgmentthat the initial packets were received. By default, the BlackBerry MDS Connection Service limits the size of packets to 29 KB forBlackBerry® Enterprise Server4.0, or 1 KB for BlackBerry Enterprise Server 4.1 or later.

If the BlackBerry MDS Connection Service is unable to immediately deliver the packets to a BlackBerry device (for example,because the BlackBerry device is outside a network coverage area or is turned off), then the packets are queued, and the BlackBerryMDS Connection Service attempts to resend them later. If the BlackBerry MDS Connection Service is unable to deliver the packetsbefore the flow control timeout is reached, then the packets are removed from the queue, and the push request is consideredunsuccessful for the given BlackBerry device. By default, the flow control timeout is 10 minutes.

BlackBerry® Enterprise Server administrators can change the default size of the data packets and the default flow control timeout.Changing the default values can impact on the performance of the BlackBerry MDS Connection Service. For example, increasingthe default size of the data packets requires more memory to store the packets in the queue. Increasing the flow control timeoutmeans that push requests will be queued in memory longer. In addition, because the BlackBerry® Enterprise Server administratorlimits the number of queued push connections, the longer push requests remain in the queue, the more likely the BlackBerryMDS Connection Service will run out of available push connections, which could force the BlackBerry MDS Connection Serviceto deny future push requests.


5

Storing push requests in the BlackBerry Configuration Database

Administrators can configure the storage settings for push requests that are stored in the BlackBerry Configuration Database,including the maximum number, and the maximum age of push requests stored in the database.

Organizations that implement a push solution should develop standards for these configuration settings.

For more information about configuring the BlackBerry Configuration Database, see the BlackBerry Enterprise ServerAdministration Guide.


6

Making a push request 2

Whether you are using the PAP push format or the RIM push format, a push request is made up of the data to be pushed, and aset of delivery parameters, which define how, when, and to whom the data is pushed. The principle difference between the twoformats is the way in which the delivery parameters are specified.

Both the PAP push and RIM push formats support the following features:

• Reliable push requests: Allows you to request that the BlackBerry MDS Connection Service send a result notification toindicate the success or failure of the push request for each recipient address.

• Deliver-Before time stamp: Allows you to provide a time stamp before which the BlackBerry MDS Connection Service mustdeliver the pushed data. If the BlackBerry MDS Connection Service is unable to deliver the data by the specified time, thepush request is considered to have failed.

• Deliver-After time stamp: Lets push application developers provide a time stamp before which the push must not be delivered.If a push is not successfully delivered after the specified time, the push is considered to have failed.

In addition, the PAP push service implementation supports the following features:

• Push cancellation: Lets push applications cancel a push submission that has already been sent.• Push status query: Lets push applications check the status of a push submission.

If you are pushing data to the BlackBerry® Browser, you must also specify additional browser push HTTP headers in addition tothe delivery parameters.

Pushing data to multiple BlackBerry device usersIn BlackBerry® Enterprise Server 4.1 or later, the BlackBerry® MDS Connection Service allows you to submit a single push requestfor multiple BlackBerry device users. You can specify multiple recipients using one of the following methods:

• by specifying multiple email addresses or BlackBerry device PINs in the push request• by specifying a BlackBerry user group (which specifies multiple recipients using a single address) in the push request

Some BlackBerry Enterprise Server architectures feature multiple distributed BlackBerry MDS Connection Service push servers.If a push request is received by a central push server that supports multiple recipients, and the push request is redirected to aBlackBerry MDS Connection Service that does not support multiple recipients, then the central push server creates a new pushrequest for each address (or in the case of a group, each member address) specified in the original push request.

Pushing data to multiple recipient addresses

Pushing data to multiple recipient addresses rather than to a BlackBerry user group allows you to cancel, query, or receive resultnotifications for individual recipients.


7

However, using multiple addresses can result in large push requests, which can result in some complications. For example, theApache Tomcat server limits the total size of the URL and headers in an HTTP request to about 3KB. A RIM push request thatadds a large number of recipient addresses to the query string might exceed this limit, causing Tomcat to close the connection.To avoid this issue, the push initiator should push to fewer recipient addresses at a time.

Push requests might be redirected from a centralized push server to other BlackBerry® MDS Connection Services for deliveryusing the RIM push format. As a result, even if the original push request uses the PAP push format, the URL size limitation cancause a redirection error if enough destination addresses require redirection. In this case, the push initiator can either push tofewer recipient addresses at a time, or submit the push request directly to the BlackBerry MDS Connection Service to which therecipient addresses are mapped.

To push data to multiple recipient addresses• Using the PAP push format: Include an <address> element for each intended recipient. The address-value attribute

specifies the email address or BlackBerry device PIN for the recipient, along with the port number.

For example, the following XML indicates that data should be sent to two BlackBerry device users specified by their emailaddresses ([email protected] and [email protected]):

<address address-value="WAPPUSH=user1%40rim%2ecom%5B%3A7874/[email protected]" /><address address-value="WAPPUSH=user2%40rim%2ecom%5D%3A7874/[email protected]" />

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

• Using the RIM push format: Include a separate DESTINATION parameter for each intended recipient email address orBlackBerry device PIN in the query string.

For example, the following URL indicates that the push request should be sent to two BlackBerry device users specified bytheir email addresses ([email protected] and [email protected]):

http://mds_server:8080/[email protected]&[email protected]&PORT=7874&REQUESTURI=/

Pushing data to a BlackBerry user group

BlackBerry® user groups represent multiple recipients using a single address. Groups are administered on the , so BlackBerrydevice users can be added or removed as necessary without altering the address of the group as a whole. This reduces thecomplexity of adding many individual addresses to a push request, and minimizes the size of the push request.

When you send a push request to a group, the BlackBerry® MDS Connection Service considers the group to be a single entity,which can the inhibit flexibility of a push application. For example, if you submit a reliable push request for a group, you do notreceive a result notification for each member of the group. Instead, the BlackBerry MDS Connection Service returns a singleresult notification for the group as a whole. If you use the PAP push format, you cannot cancel or query the status of the pushrequest for a particular group member; you must cancel or query the status for the entire group.


8

The BlackBerry® MDS Simulator does not support pushing data to groups, so you cannot test pushing data to groups in a simulatedenvironment.

To push data to a group• Using the PAP push format: Include a single <address> element for the group. The address-value attribute specifies

the group name.

To identify the value as a BlackBerry user group, you must prefix the group name with a URL encoded $ character (%24).For example, the following XML indicates that the push request should be sent to a single group called Marketing:

<address address-value="WAPPUSH=%24Marketing/[email protected]"/>

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

• Using the RIM push format: Add a DESTINATION parameter for the group to the request.

To identify the value as a BlackBerry user group, you must prefix the group name with a $ character. For example, thefollowing URL indicates that the push request should be sent to a single group called Marketing:

http://mds_server:8080/push?DESTINATION=$Marketing&PORT=7874&REQUESTURI=/

Using push request reliabilityIn your push request, you can specify that you want the BlackBerry® device to return a result notification when the pushed datais successfully delivered. The BlackBerry® MDS Connection Service receives notifications from each destination BlackBerry devicethat successfully receives the pushed data and forwards those notifications to the push originator. Similarly, the BlackBerry MDSConnection Service sends a notification to the push originator if a push request is not successfully delivered to one or moredestination BlackBerry devices within the allotted time.

If you do not specify a reliability level for your push method, the BlackBerry MDS Connection Service does not provide the pushoriginator with any notification regarding the outcome of the push request.

You must also specify a notification URL to which the BlackBerry MDS Connection Service will send result notifications, withevery push request that specifies a reliability option. A push request that requests some level of reliability but does not providea notification URL is considered invalid and is rejected by the BlackBerry MDS Connection Service.

You must register the port number on which the client-side application listens with the BlackBerry MDS Connection Service ifyou are creating a custom BlackBerry® Java Application to receive and process pushed data and intend to use application-reliablepush requests. Contact your organization's BlackBerry® Enterprise Server Administrator with the unique port numbers that youdefined for any BlackBerry Java Application you develop. If you are pushing data to the BlackBerry® Browser, the port ispreregistered.

If you have created a BlackBerry Java Application as a push listener and you intend to use application-reliable push requests,you might need to design your application to make a request to the BlackBerry MDS Connection Service the first time the useropens it.


9

Before you can submit an application-reliable push request, the BlackBerry MDS Connection Service must know the BlackBerryDevice Software version information for each recipient BlackBerry device, since application-reliable push requests are onlysupported by BlackBerry devices running BlackBerry® Device Software 3.8 or later. The BlackBerry MDS Connection Serviceacquires the BlackBerry device information from the device profile, which is identified in the UAProf header that is included whena user makes a request for content using the BlackBerry® Browser.

If the user must register to use your push application, or if they must download your BlackBerry Java Application using theBlackBerry Browser to install it onto their BlackBerry device, then the BlackBerry MDS Connection Service will already haveregistered the device information for each recipient. However, if users acquire your BlackBerry Java Application without usingthe BlackBerry Browser, the BlackBerry MDS Connection Service will not have the user profile information it needs beforepermitting application-reliable requests. By developing your application so that it sends an HTTP request, you can make surethat the BlackBerry MDS Connection Service registers profile information for each BlackBerry device that receives pushed data.

To specify a reliable push request• Using the PAP push format: Include the <quality-of-service> element in the <push-message> element of the

control entity.• Using the RIM push format: Include the X-Rim-Push-Reliability header in the request.

Levels of reliabilityYou can choose the reliability level that is appropriate for your push request.

Reliability level Description

transport The BlackBerry device sends an acknowledgment notification when the pushed data reaches the device.

It does not attempt to verify that the data was received by the client-side application.

Transport-reliable push requests are supported by any BlackBerry device running BlackBerry Device

Software 3.6 or later.

application The BlackBerry device sends an acknowledgment notification when the pushed data reaches the client-

side application. The device sends the acknowledgment to the BlackBerry MDS Connection Service,

which forwards it on to the notification URL provided in the push request.

Before application-reliable push requests can be made, the listen port number on the BlackBerry device

must be registered with the BlackBerry MDS Connection Service. If you are pushing data to the

BlackBerry® Browser, the port is preregistered.

Application-reliable push requests are only supported by BlackBerry devices running BlackBerry Device



10

Reliability level Description

application-

preferred

Supported by the RIM push format only. If the BlackBerry device supports application-level reliability

(that is, if it is running BlackBerry Device Software 4.0 or later), it sends an acknowledgment notification

when the pushed data reaches the client-side application. If the BlackBerry device does not support

application-level reliability, it sends an acknowledgment notification when the pushed data reaches the

device.

Before application-reliable push requests can be made, the listen port number on the BlackBerry device

must be registered with the BlackBerry MDS Connection Service. If you are pushing data to the

BlackBerry® Browser, the port is preregistered.

Application-preferred push requests are not available with the PAP push format.

Application-reliable push requests are only supported by BlackBerry devices running BlackBerry Device


Receiving push result notifications

If you create a push request that specifies either application-level or transport-level reliability, you must also specify as part ofthe push request a valid notification URL. A push request that requests some level of reliability but does not provide a notificationURL is considered invalid and is rejected by the BlackBerry® MDS Connection Service.

The notification URL is the address to which the BlackBerry MDS Connection Service sends result notifications. When theBlackBerry device receives the pushed data, it returns a delivery confirmation message to the BlackBerry MDS Connection Service.The BlackBerry MDS Connection Service forwards the message to the URL provided in the push request. If the BlackBerry MDSConnection Service is unable to deliver the push request, it sends a result notification informing the push originator of theunsuccessful result.

The BlackBerry MDS Connection Service sends all result notifications to the notification URL as an HTTP POST.

If the push request is sent to multiple recipients specified by using multiple email addresses or multiple BlackBerry device PINs,the BlackBerry MDS Connection Service sends a unique result notification for each recipient.

If the push request is sent to a BlackBerry device user group, the BlackBerry MDS Connection Service sends a single resultnotification for the entire group. If one member is unable to receive the data, the push request is considered unsuccessful. Forexample, using the PAP push format, the delivered state means that the message was successfully delivered to all recipientsin the group, and the timeout state means that the delivery timed out before all recipients received the message, althoughsome may have received it.

To receive a push result notifications• Using the PAP push format: Specify the notification URL using the ppg-notify-requested-to attribute of the

<push-message> element


11

• Using the RIM push format: Specify the notification URL using the X-Rim-Push_NotifyURL header

Specifying time restrictions for push deliveryYou can define a window of time during which pushed data must be delivered to the recipient BlackBerry® devices.

You can set two time stamps to specify time restrictions:

• The Deliver-Before time stamp, which specifies the date and time by which the push request must be delivered to the device.If the BlackBerry MDS Connection Service is unable to deliver a push request to a recipient before the time specified in theDeliver-before time stamp, the push request is considered unsuccessful for the affected devices.

• The Deliver-After time stamp, which specifies the data and time before which the push request cannot delivered.

If the BlackBerry MDS Connection Service is unable to deliver a push request to a recipient before or after the times specifiedby using these time stamps, the push request is considered unsuccessful for the affected devices.

To specify time restrictions for push deliver• Using the PAP push format: Define one or both of the deliver-after-timestamp and the

deliver-after-timestamp attribute for the <push-message> element of the control entity.• Using the RIM push format: Include the X-Rim-Push-Deliver-Before and X-Rim-Push-Deliver-After

header in the request.

Querying the status of push requestsIf you use the PAP push format, you can query the status of a previously submitted push request for one or more specifiedrecipients. A PAP status-query request includes the XML-based PAP control entity. The PAP control entity identifies the associatedpush request and the recipient addresses that you want to query.

The BlackBerry® MDS Connection Service returns a single response that contains the status of the push request for all of thespecified recipient BlackBerry devices.

You can specify zero or more recipients in the status-query request. If you specify a recipient address, it must exactly match anaddress specified in the original push request. You cannot, for example, specify a BlackBerry user group in the original pushrequest, and then attempt to query the status of the push request for a single BlackBerry device, even if the BlackBerry deviceuser is a member of the specified group.

If you do not specify an address, the BlackBerry MDS Connection Service queries the push request status for all recipient BlackBerrydevices.

Querying the status of push requests can result in unnecessary network traffic which can negatively impact the performance ofthe BlackBerry MDS Connection Service. If it is important to know whether a push request was successfully delivered, requestinga result notification is typically more efficient.


12

To query the status of a push request, you send an HTTP POST request containing the PAP status-query request to the BlackBerryMDS Connection Service.

To create a status-query request• Using the PAP push format: Use the <statusquery-message> element in the PAP control entity.

Cancelling a pending push requestIf you use the PAP push format, you can send a cancellation request to cancel a push request. A PAP cancellation request includesthe XML-based PAP control entity. The control entity identifies the associated push request and the recipient addresses for whichthe push request should be cancelled.

You can specify zero or more addresses in the cancellation request. If you specify a recipient address, it must exactly match anaddress specified in the original push request. You cannot, for example, specify a BlackBerry user group in the original pushrequest, and then attempt to cancel the push request for a single BlackBerry device, even if the BlackBerry device user is a memberof the specified group.

If you do not specify an address, the BlackBerry MDS Connection Service attempts to cancel the push request for all recipientBlackBerry devices.

When the BlackBerry MDS Connection Service receives a cancellation request, if first queries the status of the push request. Ifthe push request is still pending for one or more recipients, the BlackBerry MDS Connection Service accepts the cancellationrequest and attempts to cancel the push request for the recipients listed in the cancellation request. The BlackBerry MDSConnection Service does not attempt to recall data from BlackBerry devices that have received the pushed data.

To cancel a push request, you send an HTTP POST request containing the PAP cancellation request to the BlackBerry MDSConnection Service.

To create a cancellation request• Using the PAP push format: Use the <cancel-message> element


13

Overview of the PAP push format 3

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

• Push request: This request allows you to push data to the specified recipients. A PAP push request is a MIME multipartmessage 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. APAP status-query request includes only an XML-based PAP control entity, which identifies the associated push request, andlists 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 cancellationrequest includes only an XML-based PAP control entity, which identifies the associated push request, and lists the recipientaddresses 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 MDSConnection Service is configured to support secure connections, you can use the HTTPS protocol. The HTTP POST request mustuse the following format:

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

where

• <MDS_CS> is the URL address of the BlackBerry MDS Connection Service web server. If you are unsure of the URL addressof the BlackBerry MDS Connection Service, contact your BlackBerry® Enterprise Server Administrator.

• <MDS_CS_port> is the port number on which the BlackBerry MDS Connection Service web server listens. By default, theBlackBerry MDS Connection Service listens on port number is 8080. If you are unsure of the port number, contact yourBlackBerry® Enterprise Server administrator.

• <message> is either a multipart message with the PAP control entity and the data (in the case of push requests), or a PAPcontrol entity on its own (in the case of status-query and cancellation requests)

Constructing a PAP control entityA 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, thecancellation message control entity, and the status-query message control entity.


14

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 declarationincluded in all PAP control entities submitted to the BlackBerry MDS Connection Service must specify supported versioninformation.

Code sample: Formatting 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 [email protected].

You can also include the following attributes:


15

http://www.openmobilealliance.org/

http://www.openmobilealliance.org/


• 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>%3A<port>/[email protected]

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.

Note: 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:


16


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

Code sample: 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. Thisrequest 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 twoindividual BlackBerry device users ([email protected] and [email protected]). The <quality-of-service> element defines thisrequest as application-reliable.

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

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

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

--asdlfkjiurwghasfContent-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="[email protected]" deliver-before-timestamp="2009-12-31T13:30:00Z" ppg-notify-requested-to="http://rim.com/ReceiveNotify"> <address address-value="WAPPUSH=user1%40rim.com%3A7874/[email protected]"/> <address address-value="WAPPUSH=user2%40rim.com%3A7874/[email protected]"/> <quality-of-service delivery-method="confirmed"/> </push-message>


17

</pap>

--asdlfkjiurwghasfContent-Encoding: binaryContent-Type: text/htmlX-Wap-Application-Id: /X-Rim-Push-Type: browser-channelX-Rim-Push-Channel-ID: 1AX-Rim-Push-Title: TestX-Rim-Push-Unread-Icon: http://rim.com/icon_new.pngX-Rim-Push-Read-Icon: http://rim.com/icon_viewed.pngX-Rim-Delete-URL: http://rim.com/ReceiveDeleteX-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



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



18


where <recipient> is the email address, BlackBerry® device PIN,



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.


<cancel-message> element, one for each recipient address you

want to specify.

Code sample: 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 the BlackBerry MDS Connection Service cancel the push request(push-id="[email protected]").

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

--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> <cancel-message push-id="[email protected]"> </cancel-message></pap>


Elements of a PAP status-query message




19


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


where <recipient> is the email address, BlackBerry® device PIN,



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.


<statusquery-message> element, one for each recipient

address you want to specify.

Code sample: 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 pushrequest (push-id="[email protected]") for one BlackBerry user group (Marketing). Only one status is returned for the entiregroup. If all members have received the data except for one, the message state is still returned as pending.


20

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

--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> <statusquery-message push-id="[email protected]"> <address address-value="WAPPUSH=%24Marketing/[email protected]"/> </statusquery-message></pap>


Code sample: Receiving a PAP push format result notificationIf you use the PAP push format, the BlackBerry® MDS Connection Service sends the result notification as a PAP result notificationcontrol 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="[email protected]"> <address address-value="WAPPUSH=YOUR_EMAIL_ADDRESS%40YOUR_DOMAIN%2ecom%3A7874/[email protected]"/> <quality-of-service delivery-method="confirmed"/> </resultnotification-message></pap>


21

Overview of the RIM push format 4

Your server-side application can use the RIM 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 ConnectionService is configured to support secure connections, you can use the HTTPS protocol. The HTTP POST request must use thefollowing format:

POST http://<MDS_CS>:<MDS_CS_port>/push?DESTINATION=<destination>&PORT=<client_port>&REQUESTURI=<uri><headers><data>

where

• MDS_CS is the URL address of the BlackBerry MDS Connection Service web server. If you are unsure of the URL addressof the BlackBerry MDS Connection Service, contact your BlackBerry® Enterprise Server Administrator.

• MDS_CS_port is the port number on which the BlackBerry MDS Connection Service web server listens. By default, theBlackBerry MDS Connection Service listens on port number is 8080. If you are unsure of the port number, contact yourBlackBerry® Enterprise Server administrator.

• destination is the recipient email address, BlackBerry device PIN, or BlackBerry user group name, to whom theBlackBerry MDS Connection Service should push the data. To specify multiple recipient addresses, include a separateDESTINATION parameter for each intended recipient email address or BlackBerry device PIN.

• client_port is the port number on which your client-side listening application listens. If you are pushing to the BlackBerryBrowser, the port number is 7847. Custom BlackBerry® Java Applications should each listen on a unique port number.

• 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

are pushing data to the BlackBerry Browser, you must also include the browser-specific HTTP headers.• data is a byte stream containing the data or content that the BlackBerry MDS Connection Service must deliver to the

recipient BlackBerry devices.

HTTP headers for the RIM 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

[email protected].

X-Rim-Push-Description Specifies a description for the push request. This header is optional.


22

Header Description

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 RIM push format result notificationIf you use the RIM push format, the response information is returned in the headers of the HTTP POST request.


23

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.

Your organization must have BlackBerry® Enterprise Server 4.1 or later for the BlackBerry

MDS Connection Service to include this header in the response.

Response codes for the RIM 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.

In BlackBerry® Enterprise Server 3.7 and earlier, this error code is also returned if the BlackBerry device is

not associated with the BlackBerry® Enterprise Server, or when push access control has been enabled on

the BlackBerry Enterprise Server and the server making the push request does not have permission to push

data.

403 The BlackBerry device is not associated with the BlackBerry® Enterprise Server, or push access control has

been enabled on the BlackBerry Enterprise Server and the server making the push request does not have

permission to push data.

This error code was introduced in BlackBerry Enterprise Server 4.0. In previous versions of the BlackBerry

Enterprise Server, the BlackBerry MDS Connection Service responds to this error with response code 400.

404 The push request was not received by the BlackBerry MDS Connection Service. Verify that you have supplied

the correct URL and port number 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.


24

Response code Description

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.


25

Pushing content to the BlackBerry Browser 5

Pushing content to the BlackBerry® Browser allows you to access the push technology that the BlackBerry® MDS ConnectionService provides without having to create your own client-side application. The BlackBerry Browser is designed with a listeningthread, which listens in the background for data to be delivered to the BlackBerry device. You can push any content that issupported by the target version of the BlackBerry Browser.

The BlackBerry Browser supports several push options, allowing you to choose the approach that is best suited to your needs.You can specify which option to use by using an HTTP header. Additional HTTP headers that are specific to a browser pushapplication can allow you to control how the content appears to the user. These browser-specific headers must be included inaddition to the PAP control entity or RIM push headers that are part of every push request.

There are four request types associated with a browser push:

Request type Description

Browser channel This request type pushes content to the browser cache and adds an icon on the Home

screen of the BlackBerry device as an entry point to the content. Clicking the icon opens

the BlackBerry Browser and displays the pushed content.

The browser channel remains on the Home screen until it is deleted. The user can delete

the channel, or you can send a channel delete request to delete the channel for the user.

Browser channel delete This request type removes a channel from the recipient BlackBerry devices. This request

includes no content, only headers, which inform the BlackBerry device to delete the

specified channel and remove the icon from the Home screen.

Browser message This request type delivers content to the message list, where it appears as an item in the

list. Clicking the item in the message list opens the BlackBerry Browser and displays the

pushed content.

Browser cache This request type delivers content directly to the browser cache, but provides no

notification to the user. The next time the user attempts to access the associated URL,

the browser retrieves and displays the updated content from the cache.


26

Pushing content to a browser channelYour server-side application can push content to the BlackBerry® device to create or update a browser channels. A browserchannel is an alternative entry point to the BlackBerry® Browser application that displays pushed content instead of the user-defined home page that typically appears when the user opens the BlackBerry Browser. Browser channels appear to the user asa unique application, with an icon on the BlackBerry device Home screen. When the user clicks the icon, the BlackBerry® Browseropens and pulls the content from the pushed content cache.

You must uniquely identify a browser channel by using a channel ID, specified by the X-Rim-Push-Channel-ID header. Ifa channel with the same channel ID already exists on the device, the associated content is replaced by the new content. Thechannel ID is also used to identify the channel in channel delete requests or delete notifications sent when the user deletes thechannel.

A browser channel can have two icons associated with it:• one to indicate that new content is available on the BlackBerry device (the unread icon)• one to indicate that the latest content has already been viewed (the read icon)

When the BlackBerry Browser receives a content that has been pushed to a channel, the BlackBerry device creates a new channel,or updates the channel if the specified channel ID already exists. When a channel is added or updated, the BlackBerry devicedisplays the unread icon on the Home screen to alert the BlackBerry device user that content is available. For example, the iconfor an order-tracking channel might change when product orders are entered. After the user clicks the icon and views the updatedcontent, the BlackBerry device displays the read icon on the Home screen, which remains until new content is delivered for thatchannel.

You must post these icons on your web server and specify the URLs for each icon in the push request by using theX-Rim-Push-Unread-Icon and X-Rim-Push-Read-Icon headers. When the BlackBerry® MDS Connection Servicereceives the browser channel push request, it retrieves the icons from the specified locations and delivers the to the recipientBlackBerry devices along with the pushed content. If you do not include these headers, the BlackBerry device uses the icons thatyou specified in a previous push request associated with that channel ID, if they exist, or the system default icon.

To push to a browser channelFor the X-Rim-Push-Type header, specify a value of browser-channel.

You must include the also include the X-Rim-Push-Channel-ID header to specify a unique identifier for the channel.

You can also choose to include one or more of the following optional HTTP headers:

• X-Rim-Push-Title, which specifies a title used to identify the push application on the Home screen.• X-Rim-Push-Unread-Icon-URL, which specifies the URL for the icon image that is displayed on the Home screen

when new content has arrived.• X-Rim-Push-Read-Icon-URL, which specifies the URL for the icon image that is displayed after the pushed content

has been viewed.• X-Rim-Push-Delete-URL, Which specifies the URL to which notifications are sent if the user deletes the channel from

the Home screen.


27

Deleting a browser channel from the BlackBerry device

There are two ways that a browser channel can be deleted from the Home screen:

• The server-side push application can submit a browser channel delete request to delete the browser channel.• The user can delete the browser channel manually.

The icon that is associated with the browser channel is removed from the Home screen, and the associated content is clearedfrom the pushed content cache. If the server-side push application pushes content to the same channel ID, the channel reappears.

Submitting a channel delete request

There might be instances when you want to remove a browser channel from a BlackBerry® device; for example, perhaps the pushservice is obsolete, or the data is time-sensitive and should only be available for a specific time period, or perhaps a specific userno longer needs to receive data pushed to that browser channel. The server-side push application can remove a browser channelfrom a BlackBerry device at any time by submitting a channel delete request.

The channel delete request only deletes the instance of the specified browser channel that is currently stored on the BlackBerrydevice. If the server pushes content to that browser channel again, it reappears on the device Home screen.

To delete a browser channelFor the X-Rim-Push-Type header, specify a value of browser-channel-delete.

If you specify a value of browser-channel-delete, you must include the also include the X-Rim-Push-Channel-IDheader indicate which channel should be deleted.

Requesting notification when a user deletes a browser channel

A BlackBerry® user can delete a browser channel at any time. However, when the BlackBerry device user deletes a channel onthe device, they only delete the instance of the specified browser channel that is currently stored on the BlackBerry device. If theserver pushes content to that browser channel again, the channel is reopened, and the icon once again appears on the Homescreen.

In most cases, when a user deletes the icon from the Home screen, the push application should be designed to remove that userfrom the list of recipients for future push requests.

You can construct your push request so that you receive a notification when the user has deleted the browser channel. Receivinga notification allows the push service administrator to either remove that user from the list of recipients, or whether the usershould continue to receive content that is pushed to that browser channel.


28

You can include the X-Rim-Push-Delete-URL to specify a URL to which a notification is sent when the user deletes thechannel. When the user deletes a browser channel, the browser sends a GET request to the Delete URL. The Delete URL is notopened for the user to view; instead, this URL is retrieved in the background. By retrieving the URL, the BlackBerry device notifiesthe push originator that the channel no longer exists on the device.

When the browser sends the GET request to the URL, it does not supply any parameters describing the channel being deleted.You must add parameters to the URL so that you can uniquely identify the push when the URL is requested.

X-Rim-Push-Delete-URL: http://myserver/deleteNotify.php?pushID=45&user=54

Pushing content to the messages applicationYour server-side application can push content pages to the messages application on the BlackBerry®device. A browser messagepush request can include a descriptive title, which appears as the subject of the message in the messages application. Otherwise,the browser message displays the URL of the associated content as the subject of the message. Users can click on the messagein the messages application to open the BlackBerry® Browser and view the content.

When you push content to the messages application, the pushed content is stored within the browser message item, not in theBlackBerry Browser push content cache. When the user deletes the message, the pushed content is deleted with it.

When a browser message arrives on the BlackBerry device, a notification icon appears in the BlackBerry device banner. If theuser has configured it to do so, the BlackBerry device issues an alert. By default, the BlackBerry device provides no notificationwhen a browser message arrives.

To push content to the messages applicationFor the X-Rim-Push-Type header, specify a value of browser-message.

You can also choose to include the X-Rim-Push-Title header, which specifies a title used as the subject of the messagewhen it appears in the messages application.

Pushing content to the browser cacheYour server-side application can push content directly to the BlackBerry® Browser cache. The user receives no notificationindicating that new content is available, but the next time that the user visits the specified URL, the browser retrieves the contentfrom the cache.

Browser cache push requests can be used in conjunction with browser channel push requests or browser message push requeststo preload the cache with external resources, such as images or style sheets, that might be referenced by other pushed contentbut are not included. If these resources are pushed to the cache, users can display the content quickly, even if they are notconnected to a wireless or Wi-Fi® network. Otherwise, the BlackBerry Browser must make an HTTP request to retrieve referencedresources from the server, which reduces the benefit of a push application.


29

You can include the X-Rim-Push-Channel-ID header with a browser cache push to associate the cached content with anexisting browser channel. For example, if a channel identifier is specified in the request, when the content is pushed to the cache,the URL of the content is added to the appropriate channel (if the channel is already active on the device).

To push to the BlackBerry Browser cacheFor the X-Rim-Push-Type header, specify a value of browser-content.

You can also choose to include the X-Rim-Push-channel-ID header, which specifies the channel ID of the browser channelwith which to associate the content.

Additional considerations when pushing content to the BlackBerry Browser

Defining cache control properties

When you push content to the BlackBerry® Browser, the default length of time the content remains in the pushed content cachevaries based on the version of the BlackBerry® Device Software the recipient BlackBerry device is running:

• In BlackBerry Device Software 3.7 or earlier, the BlackBerry Browser clears the cache after 29 days.• In BlackBerry Device Software 3.8 or later, the BlackBerry Browser clears the cache after 12 hours.• In BlackBerry Device Software 4.2 or later, if the content URL has a query, the content is not cached.

Expired content is cleared from the pushed content cache, even if the user has not viewed it.

You can use the Cache-Control or Expires caching directive to increase or decrease the amount of time the content isstored. The BlackBerry Browser respects any caching directives included with pushed content, whether specified in the contentheader, or within HTML <meta> tags.

Using the Cache-Control header, you can use the max-age control to specify the time, in seconds the time the content waspushed by the BlackBerry® MDS Connection Service, before the cached content expires. For example,

Cache-Control: max-age=3600

Using the Expires header, you can specify an explicit date and time, in HTTP format, at which the content expires. For example:

Expires: Wed, 07 Oct 2009 08:00:00 GMT

The effect of either method is essentially the same. If you use the Cache-Control header, you can define a static value, sincethe expiration time is relative to the time the BlackBerry MDS Connection Service pushed the content. If you use theExpires header, you should define the value as a variable and set it appropriately with each push request. However, if you arepushing static resources directly to the cache, such as a style sheet, or an image that is unlikely to change, it is better to use theExpires header, so you can specify an expiry date that is far into the future to keep the component fresh longer.


30

Transcoding content

If it has been configured to do so, the BlackBerry® MDS Connection Service automatically transcodes pushed content before itsends it to the BlackBerry® Browser. When the BlackBerry MDS Connection Service transcodes content, it changes the pushedresources into formats that are more suitable for sending over the wireless network and for rendering in the BlackBerry® Browser.

Push requests can override the transcoding rules configured for the BlackBerry MDS Connection Service using theX-Rim-Transcode-Content header. This header can be used to specify a list of MIME types that the BlackBerry MDSConnection Service should transcode, should it encounter them. For example, if the HTTP headerX-Rim-Transcode-Content: application/xhtml+xml is set, then the BlackBerry MDS Connection Servicetranscodes XHTML content before pushing it to the BlackBerry devices.

You can also specify a value of none to prevent the BlackBerry MDS Connection Service from transcoding any content. For bestresults, you should typically allow the BlackBerry MDS Connection Service to transcode all your content.

Although most often used with browser content, the X-Rim-Transcode-Content header can also be used in conjunctionwith a BlackBerry® Java Application, if a transcoder exists on the BlackBerry MDS Connection Service for the data format youare sending.

HTTP headers used by the BlackBerry BrowserIf you push content to the BlackBerry® Browser, you must include a set of headers that define the browser behavior when itreceives the pushed content. For example, you can specify whether the content is delivered to the messages application or to abrowser channel, and if necessary, specify URLs to icons. These BlackBerry Browser push headers are required in addition towhatever delivery parameters you specified in the PAP control entity or RIM push headers.

When using the PAP push format, the browser headers must be included in the content portion of the multipart message. Whenusing the RIM push format, these headers are simply added to the RIM push headers included in the HTTP POST request.

When the BlackBerry® MDS Connection Service encounters the browser push headers, it forwards these headers to the BlackBerrydevice untouched.

The BlackBerry Browser supports the following headers:

Header Description

X-Rim-Push-Type Specifies the browser push type. This header is required for all browser push

requests.

This header may have one of the following values:


31

Header Description

• browser-channel: Pushes content to the Home screen, where it is

added as an icon. When the user clicks the icon, the browser opens and

displays the pushed content.

If you specify this value, you must also specify a channel ID using the

X-Rim-Channel-ID header. You can also use the

X-Rim-Push-Read-Icon-URL and

X-Rim-Push-Unread-Icon-URL headers to specify icon images to

use for the home screen icon.

If the specified channel ID already exists, that channel is updated with the

new content.

• browser-channel-delete: Deletes an existing channel. If you

specify this option, you must also specify a channel ID using the

X-Rim-Channel-ID header. The browser deletes the channel with the

given channel ID.

• browser-content: Pushes content directly to the browser’s pushed

content cache. The next time that the user visits the specified URL, the

browser retrieves the updated content from the cache.

• browser-message: Pushes content to the message list, where the

message is identified as a browser message.

X-Rim-Push-Title Specifies a text string that is used to identify the push application on the Home

screen, in the message list, or in the browser bookmarks.

X-Rim-Push-Channel-ID Specifies a string that uniquely identifies a new or existing channel. This header

is required when X-Rim-Push-Type has a value of browser-channel or

browser-channel-delete. It is optional when X-Rim-Push-Type has

a value of browser-content.

X-Rim-Push-Read-Icon-URL Specifies the URL of the icon image that is used to identify the push application

on the Home screen after the BlackBerry device user has viewed the content.

The BlackBerry MDS Connection Service retrieves the image at the specified

URL and delivers it to the recipients along with the pushed content.

This header is valid only when X-Rim-Push-Type has a value of

browser-channel.


32

Header Description

X-RIM-Push-Unread-Icon-URL Specifies the URL of the icon image that is used to identify the push application

on the Home screen before the BlackBerry device user has viewed the content.

The BlackBerry MDS Connection Service retrieves the image at the specified

URL and delivers it to the recipients along with the pushed content.


browser-channel.

X-RIM-Push-Delete-URL Specifies a URL that the BlackBerry Browser retrieves when the user deletes the

channel from the Home screen of the BlackBerry device. The browser retrieves

the URL in the background. By retrieving the URL, the BlackBerry device notifies

the push originator that the channel has been deleted from the device.

The BlackBerry Browser does not add any parameters to the specified URL. You

must therefore include any parameters yourself so that you can uniquely identify

the push when the URL is requested. For example:

X-Rim-Push-Delete-URL: http://myserver/deleteNotify.php? pushID=45&user=54


browser-channel.

Additional HTTP headers you can use with browser pushesWhen pushing content to the BlackBerry® Browser, you may also want to include the following headers to define additionalcontrols for the content:

Header Description

Expires Specifies an explicit date and time, in HTTP format, at which the content expires. For

example:

Expires: Wed, 07 Oct 2009 08:00:00 GMT

If you use the Cache-Control: max-age directive, there is typically no need to include

the Expires header.


33

Header Description

Cache-Control Specifies the caching directive for the pushed content. Use the max-age control to specify

the time, in seconds, before the cached content expires. For example:

Cache-Control: max-age=3600

If you use the Expires header, there is typically no need to include the

Cache-Control: max-age directive.

X-Rim-Transcode-Content Specifies which types of pushed content the server should transcode.

This header may have one of the following values:

• */*: Prompts the BlackBerry® MDS Connection Service to transcode all content for

which it has a transcoder. If you do not specify the

X-Rim-Transcode-Content header, the BlackBerry MDS Connection Service

transcodes all content by default.

• none: Forces the BlackBerry MDS Connection Service to send all content to the

BlackBerry Browser without transcoding it.

• list_of_MIME_types : Specifies a comma-separated list of MIME types which

the BlackBerry MDS Connection Service transcodes before sending the content to the

BlackBerry device.

Content-Location Specifies the URL location from which the content is downloaded, if the content is not

included.


34

Provide feedback 6

To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.


35

http://www.blackberry.com/docsfeedback

Legal notice 7

©2009 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType®, SurePress™ andrelated trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S.and countries around the world.

802.11a, 802.11b, and 802.11g are trademarks of the Institute of Electrical and Electronics Engineers, Inc. Bluetooth is a trademarkof Bluetooth SIG. Global System for Mobile communications is a trademark of the GSM MOU Association. iDEN is a trademarkof Motorola, Inc. Microsoft, ActiveX, Internet Explorer, and Windows are trademarks of Microsoft Corporation. Java is a trademarkof Sun Microsystems, Inc. UMTS is a trademark of European Telecommunications Standard Institute. Wi-Fi is a trademark of theWi-Fi Alliance. All other trademarks are the property of their respective owners.

The BlackBerry smartphone and other devices and/or associated software are protected by copyright, international treaties, andvarious patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318;D445,428; D433,460; D416,256. Other patents are registered or pending in the U.S. and in various countries around the world.Visit www.rim.com/patents for a list of RIM (as hereinafter defined) patents.

This documentation including all documentation incorporated by reference herein such as documentation provided or madeavailable at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition,endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in thisdocumentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation maydescribe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information thatis contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements,or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or servicesincluding components and content such as content protected by copyright and/or third-party web sites (collectively the "ThirdParty Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including,without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency,links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Servicesin this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDINGWITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OFDURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALINGOR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCEOF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, AREHEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONSMAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT


36

http://www.rim.com/patents

http://www.blackberry.com/go/docs

PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENTTHEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROMTHE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLEFOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCEDHEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY,INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES,FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OFBUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMSASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS,LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OFSUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARYLOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISEDOF THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHEROBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITYFOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THECAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE,TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHESOR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B)TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIMESERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIRRESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE,AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITYARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that yourairtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsingfunctionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roamingarrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and servicesmay require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third partyrights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licensesare required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products andServices until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM'sproducts and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions,endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relationthereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separatelicenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or otheragreement with RIM.


37

Certain features outlined in this documentation require a minimum version of BlackBerry® Enterprise Server, BlackBerry® DesktopSoftware, and/or BlackBerry® Device Software.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto.NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIESPROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

Research In Motion Limited295 Phillip StreetWaterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada


38

push applications - development guide

Documents