XML element reference

Element: <address>

The <address> element specifies the PIN or token of the BlackBerry device that is included in a push request, cancellation request, or status query request. The containing element can contain one or more <address> elements. For a push message request, you must include one <address> element for each BlackBerry device that you want to include in the request.

In a push message request, you can specify the attribute and value of address-value="push_all" to push the message to all of the devices that are subscribed to the push application.

In a cancellation request or a status query request, the <address> element is optional. If you do not include an <address> element, the request affects all of the BlackBerry devices that are associated with the corresponding push request.

Attributes

Attribute

Values

Description

address-value

device_PIN

device_token

push_all

This attribute specifies the PIN or token of the BlackBerry device that an action is performed on (for example, pushing data, cancelling a push request, or querying the status of a push request).

This attribute can have the following values:

  • device_PIN or device_token : This value specifies the PIN or token of the BlackBerry device.
  • push_all: This value specifies all of the BlackBerry devices that are subscribed to the push application.

Element: <badmessage-response>

Valid parent

<bpds>, <pap>

Valid children

The PPG sends a <badmessage-response> message to the push initiator when it receives a message that is not recognizable as a request that works in this context.

Attributes

Attribute

Value

Description

code

status_code

This attribute contains a status code that describes the status of the submission.

desc

description

This attribute contains a description of the outcome of the submission.

bad-message-fragment

text_fragment

This attribute contains a fragment of the bad message.

Element: <bpds>

The <bpds> element is the root element of RIM-specific messages and responses that extend the PAP standard.

Attributes

Attribute

Value

Descriptions

version

1.0

This attribute identifies the version of the extension.

Element: <cancel-message>

Valid parent

<pap>

Valid children

<address>

The content provider sends the <cancel-message> element to the PPG. It cancels a previously submitted push request. The PPG can cancel pending push requests; if the push request is still pending for one or more BlackBerry devices, the PPG accepts the cancellation request. However, the PPG does not attempt to recall data that was already delivered to the BlackBerry devices specified in the original push request.

You can include one or more <address> elements in the <cancel-message> element to indicate the BlackBerry devices for which you want to cancel the push request.

In a cancellation request, the <address> element is optional. If you do not include an <address> element, the request affects all BlackBerry devices associated with the corresponding push request.

Attributes

Attribute

Value

Description

push-id

unique_id

This attribute specifies a string that uniquely identifies the original push request.

Element: <cancel-response>

Valid parent

<pap>

Valid children

<cancel-result>

The PPG sends the <cancel-response> element to the content provider. The message is an acknowledgment from the PPG that it received the cancellation request from the content provider. This message does not indicate that the cancel request was processed—it simply acknowledges that the PPG accepted the cancellation request for processing.

Attributes

Attribute

Value

Description

push-id

unique_id

This attribute specifies a string that uniquely identifies the original push request.

Element: <cancel-result>

Valid parent

<cancel-response>

Valid children

<address>

The <cancel-result> element specifies a code that informs the content provider whether the PPG accepted or rejected the cancellation request.

Attributes

Attribute

Value

Description

code

status_code

This attribute specifies the code that indicates whether the PPG accepted or rejected the cancellation request.

desc

description

This attribute provides a textual description of the status of the cancellation request.

Element: <pap>

The <pap> element is the root element of all PAP messages and responses.

Attributes

Attribute

Value

Descriptions

product-name

product_name

This attribute identifies the product name of the entity that generated a PAP message or response. This can be either the push initiator or the PPG.

Element: <push-message>

Valid parent

<pap>

Valid children

<address>, <quality-of-service>

The content provider sends the <push-message> element to the PPG. This request assigns a unique ID to a push request, defines the delivery parameters, and can specify a URL to which acknowledgment notifications are sent.

You must include one or more <address> elements in the <push-message> element to indicate which BlackBerry devices the push request is sent to.

You must also include a <quality-of-service> element.

Attributes

Attribute

Value

Description

push-id

unique-id

This attribute specifies a string that uniquely identifies the push request. You can use this value to cancel or check the status of a push request.

The push-id value must be unique across all push requests for your push application. If the push-id value is not unique, the PPG might return an error. There are circumstances where the BlackBerry Infrastructure cannot detect duplicates.

The push-id can be up to 40 characters in length.

source-reference

psid

This attribute specifies the application ID from your confirmation email when you registered to use the Push Service.

The PPG uses the source- reference value to identify the content provider, the push application, and the port number on which the client application listens.

deliver-before-timestamp

timestamp

This attribute specifies the date and time that the PPG must deliver the pushed data to the BlackBerry device. Content that is not sent by this date and time is not delivered.

You must use 24-hour UTC format to set the time stamp using the following format:

YYYY-MM-DDThh:mm:ssZ

For example, a value of 2009-03-10T23:59:00Z specifies a delivery time and date of 11:59 on March 10, 2009.

The value for this attribute cannot be more than 8 hours from the time of the push request for Push Plus subscribers, or 30 days for Push Essentials subscribers.

ppg-notify-requested-to

URL

This attribute specifies the URL to which the acknowledgment notification message is sent. Optional.

If you include this attribute, the PPG sends an acknowledgment notification when the request reaches its final status. A separate result notification is sent for each address that is specified in the push request.

If you do not include this attribute, the PPG returns no result information for the push request.

A push request is considered successful when the value that you specify for the delivery-method attribute of the <quality-of-service> element is met.

When you register your service with Research In Motion, you specify a base URL for notification. The PPG sends the notification to a URL made by appending the value of this attribute to the base URL that you provided. For example, if you specified http://www.example.com/push as the base URL, and the value of ppg-notify-requested-to="/notifications" in the <push-message> element, the acknowledgment notification is sent to http://www.example.com/push/notifications.

Element: <push-response>

Valid parent

<pap>

Valid children

<response-result>

The PPG sends the <push-response> element to the content provider. The PPG sends the message as an acknowledgment after it receives the push request from the content provider. This message does not indicate that the push request was processed. The message acknowledges that the PPG has accepted the push request for processing.

The <response-result> child element provides a status code that informs the content provider whether the PPG accepted or rejected the push request.

Attributes

Attribute

Value

Description

push-id

unique_id

This attribute specifies a string that uniquely identifies the original push request.

sender-address

URL

This attribute specifies the URL of the server within the PPG that sends the response.

sender-name

text_name

This attribute specifies the name of the server within the PPG that sends the response.

reply-time

time_stamp

This attribute specifies the date and time at which the response is created.

The time stamp uses 24-hour UTC format, specified using the following format:

YYYY-MM-DDThh:mm:ssZ

For example, a value of 2009-03-10T23:59:00Z specifies a reply date 11:59 on March 10, 2009.

Element: <quality-of-service>

The <quality-of-service> element defines the delivery reliability level of the message.

Attributes

Attribute

Values

Description

delivery-method

confirmed

unconfirmed

preferconfirmed

notspecified

This attribute specifies the delivery reliability level of the message. The value you specify is the criteria for successful data delivery.

This attribute does not imply any notification from the PPG to the content provider about the success or failure of data delivery. To receive an acknowledgment notification, you must set the ppg-notify-requested-to attribute of the <push-message> element.

This attribute can have any of the following values:

  • confirmed: This value is equivalent to application-level acknowledgment. The BlackBerry device sends an acknowledgment notification message to the PPG only when the content reaches the push-enabled application on the device.

  • unconfirmed, preferconfirmed, notspecified: These values are equivalent to transport-level acknowledgment. The PPG treats these values identically.

    The BlackBerry device sends an acknowledgment notification message to the PPG when the data reaches the BlackBerry device.

Element: <response-result>

Valid parent

<push-response>

Valid children

The <response-result> element specifies a code that informs the content provider whether the PPG has accepted or rejected the push request.

Attributes

Attribute

Value

Description

code

status_code

This attribute specifies the code that indicates whether the PPG has accepted or rejected the push request.

desc

description

This attribute provides a textual description of the status of the push request.

Element: <resultnotification-message>

Valid parent

<pap>

Valid children

<address>, <quality-of-service>

The PPG sends the <resultnotification-message> element to the content provider. This notification message specifies the outcome of the push submission for a set of BlackBerry devices after the final result is known. This notification message is sent only if the original push request was accepted for delivery by the PPG.

On rare occasions, the PPG returns an address of * in the result notification. This happens when the PPG no longer has address information for the original push message but does have the final status of the message. In that case, the addresses are unknown, so the PPG substitutes *.

The acknowledgment notification message includes a child <quality-of-service> element.

Attributes

Attribute

Value(s)

Description

push-id

unique_id

This attribute specifies a string that uniquely identifies the original push request.

sender-address

URL

This attribute specifies the URL of the server within the PPG.

sender-name

text_name

This attribute specifies the name of the server within the PPG.

received-time

time_stamp

This attribute specifies the date and time at which the original push request sent from the content provider was received by the PPG.

The time stamp uses 24-hour UTC format, which is specified using the following format:

YYYY-MM-DDThh:mm:ssZ

For example, a value of 2009-03-10T23:59:00Z specifies a reply time and date of 11:59 on March 10, 2009.

event-time

time_stamp

This attribute specifies the date and time at which the push request reached its final state (delivered or failed).

The time stamp uses 24-hour UTC format, specified using the following format:

YYYY-MM-DDThh:mm:ssZ

For example, a value of 2009-03-10T23:59:00Z specifies a reply date 11:59 on March 10, 2009.

message-state

delivered

rejected

undeliverable

expired

aborted

timeout

cancelled

unknown

This attribute specifies the final state of the push request message. This attribute can have one of the following values:

  • delivered: The message was successfully delivered to the specified BlackBerry device.
  • undeliverable: The message cannot be delivered to the specified device.
  • expired: The message reached its maximum age before it could be delivered to the specified device.
  • cancelled: The message was cancelled by the push initiator before being delivered to the specified device.
  • unknown: The PPG cannot determine the final state of the message for the specified device.

code

status_code

This attribute specifies the code that indicates the outcome of the push request.

desc

description

This attribute provides text describing the outcome of the push request.

Element: <resultnotification-response>

Valid parent

<pap>

Valid children

<address>

The content provider sends the <resultnotification-response> element from the push initiator to the PPG. This element confirms that the content provider received the acknowledgement notification message from the PPG.

Attributes

Attribute

Value

Descriptions

push-id

unique_id

This attribute specifies a string that uniquely identifies the original push request.

code

status_code

This attribute specifies the code that indicates whether or not the result notification was received successfully - usually a status code of 1000 (meaning success).

desc

description

This attribute provides a description of whether or not the result notification was received successfully - usually something like 'Result notification received'. Optional.

Element: <status>

Valid parent

<subscriptionquery-message>

Valid children

The <status> element can be included in a <subscriptionquery-message> element that the content provider sends to the PPG. The content provider specifies a status, and in response gets a message containing the PINs or tokens of all BlackBerry devices with that status on the subscriber list.

This element is an extension that is specific to RIM and is not included in the PAP standard.

Attributes

Attribute

Value(s)

Descriptions

status-value

active

suspended

This attribute specifies the status of the returned devices. BlackBerry devices that are neither active nor suspended are considered unsubscribed.

Element: <statusquery-message>

Valid parent

<pap>

Valid children

<address>

The content provider sends the <statusquery-message> element to the PPG. The message requests the status of the specified push request for each of the specified BlackBerry devices.

You can include one or more <address> elements in the <statusquery-message> element to indicate the BlackBerry devices for which you want to query the status of the push request.

In a status query request, the <address> element is optional. If you do not include an <address> element, the request affects all BlackBerry devices associated with the corresponding push request.

Attributes

Attribute

Value

Description

push-id

unique_id

This attribute specifies a string that uniquely identifies the original push request.

Element: <statusquery-response>

Valid parent

<pap>

Valid children

<statusquery-result>

The PPG sends the <statusquery-response> element to the content provider. The message returns the current status of the associated push request when the PPG received the status query request.

The <statusquery-response> element contains one or more <statusquery-result> elements. Each <statusquery-result> element identifies a message-state and contains a child <address> element for each of the BlackBerry devices for which that message-state applies.

Attributes

Attribute

Value

Description

push-id

unique_id

This attribute specifies a string that uniquely identifies the original push request.

Element: <statusquery-result>

The <statusquery-result> element identifies a message-state and contains a child <address> element for each of the BlackBerry devices for which that message-state applies.

It also specifies a code that informs the content provider of whether the PPG accepted or rejected the status query request.

Attributes

Attribute

Value(s)

Description

code

status_code

This attribute specifies a code that indicates whether the PPG accepted or rejected the status query request.

desc

description

This attribute provides a textual description of the status query request.

message-state

delivered

pending

rejected

undeliverable

expired

aborted

timeout

cancelled

unknown

This attribute specifies the state of the push request message. This attribute can have one of the following values:

  • delivered: The message is successfully delivered to the specified BlackBerry devices.
  • pending: The message is in the process of being sent to the specified BlackBerry devices.
  • undeliverable: The message cannot be delivered to the specified BlackBerry device.
  • expired: The message reached its maximum age before it could be delivered to the specified BlackBerry devices.
  • cancelled: The message was cancelled by the push initiator before being delivered to the specified BlackBerry devices.
  • unknown: The PPG cannot determine the current state of the message for the specified BlackBerry devices.

Element: <subscriptionquery-detail>

Valid parent

<subscriptionquery-result>

Valid children

<address>

The PPG sends the <subscriptionquery-detail> element to the content provider as part of a <subscriptionquery-result> element. The element returns the status, time, and address of each PIN or token matching the original subscription query. The element is a RIM-specific extension and is not specified in the PAP standard.

Each <subscriptionquery-detail> element identifies a subscription state and contains a child <address> element for each of the BlackBerry devices that the subscription applies to.

Attributes

Attribute

Value

Description

event-time

time_stamp

This attribute specifies the time at which the subscription record in the BlackBerry Infrastructure was last modified. The time stamp uses 24-hour UTC format, specified using the following format:

YYYY-MM-DDThh:mm:ssZ

For example, a value of 2009-03-10T23:59:00Z specifies a reply time and date of 11:59 on March 10, 2009.

status

subscription-status

This attribute specifies the status of the subscriber with a value of active, suspended, unsubscribed, or unknown.

Element: <subscriptionquery-message>

Valid parent

<bpds>

Valid children

<address>, <status>

The content provider sends the <subscriptionquery-message> element to the PPG to determine the statuses of a specified set of PINs or tokens, or to determine what PINs or tokens have a specified status.

You can use a subscription query message to reconcile your recorded subscription information with the PPG's subscription information. To make sure the two are consistent with each other, you should reconcile the subscription information once a month.

There are two forms of subscription query request:
  • A Requested-PIN or token query returns all PIN or token values with a specified status of active or suspended.
  • A Supplied-PIN or token query lists the PINs or tokens for which subscription information is needed; a single subscription query is limited to 10,000 PINs or tokens.

To avoid overloading servers, you can send this message only 100 times in 10 minutes. Each call can contain up to 10,000 addresses, which means that up to 1,000,000 PINs or tokens can be synchronized in 10 minutes.

Attributes

Attribute

Value

Descriptions

pushservice-id

unique_id

This attribute specifies a string that uniquely identifies the push service.

Element: <subscriptionquery-response>

Valid parent

<bpds>

Valid children

<subscriptionquery-result>

The PPG sends a <subscriptionquery-response> element to the content provider after a <subscriptionquery-message> request. The <subscriptionquery-response> element contains one or more results.

This element is a RIM-specific extension and is not specified in the Push Access Protocol standard.

Attributes

Attribute

Value

Description

pushservice-id

unique_id

This attribute specifies a string that uniquely identifies the original push server.

Element: <subscriptionquery-result>

The <subscriptionquery-result> element indicates the status/outcome of the subscription query request sent to the PPG. The PPG sends this RIM-specific extension to the content provider.

Attributes

Attribute

Value

Description

event-time

time_stamp

This attribute specifies the time of the response. The time stamp uses 24-hour UTC format, specified using the following format:

YYYY-MM-DDThh:mm:ssZ

For example, a value of 2009-03-10T23:59:00Z specifies a reply time and date of 11:59 on March 10, 2009.

code

status_code

This attribute contains a status code associated with the subscription query response.

desc

description

This attribute contains text describing the status code.