# Push Access Protocol

Push Access Protocol (or PAP) is a protocol defined in WAP-164 of the Wireless Application Protocol (WAP) suite from the Open Mobile Alliance. PAP is used for communicating with the Push Proxy Gateway, which is usually part of a WAP Gateway.
PAP is intended for use in delivering content from Push Initiators to Push Proxy Gateways for subsequent delivery to narrow band devices, including mobile phones and pagers. Example messages include news, stock quotes, weather, traffic reports, and notification of events such as email arrival. With Push functionality, users are able to receive information without having to request it. In many cases it is important for the user to get the information as soon as it is available.
The Push Access Protocol is not intended for use over the air.
PAP is designed to be independent of the underlying transport protocol. PAP specifies the following possible operations between the Push Initiator and the Push Proxy Gateway:
* Submit a Push
* Cancel a Push
* Query for status of a Push
* Query for wireless device capabilities
* Result notification
The interaction between the Push Initiators and the Push Proxy Gateways is in the form of XML messages.

## Operations
### Push Submission

The purpose of the Push Submission is to deliver a Push message from a Push Initiator to a PPG, which should then deliver the message to a user agent in a device on the wireless network. The Push message contains a control entity and a content entity, and MAY contain a capabilities entity. The control entity is an XML document that contains control information (push-message) for the PPG to use in processing the message for delivery. The content entity represents content to be sent to the wireless device. The capabilities entity contains client capabilities assumed by the Push Initiator and is in the RDF [RDF] format as defined in the User Agent Profile [UAPROF]. The PPG MAY use the capabilities information to validate that the message is appropriate for the client. The response to the push request is an XML document (push-response, section 9.3) that indicates initial acceptance or failure. At minimum the PPG MUST validate against the DTD [XML] the control entity in the message and report the result in the response. The PPG MAY indicate, using progress-note (if requested by the Push initiator in the progress-notes-requested attribute), that other validations have been completed. The contents and number of progress-notes are implementation specific. A typical response message may contain progress notes for each stage of internal processing. The processing stages used are implementation specific. There are provisions in the Push message to specify multiple recipients. The response message corresponds to the submit message, so there is one response message for one push message, regardless of the number of addresses specified. If the Push Initiator desires information related to the final outcome of the delivery, then it MUST request a result notification information in the push submission and provide a return address (e.g. URL).

#### Result Notification

This operation is used by the PPG to inform the initiator of the final outcome of a push submission, if requested by the Push Initiator. This notification (arrow 5, below) tells the Push Initiator that the message was sent (transmitted, as in arrow 3), delivered (confirmation received from wireless device, as in arrow 4), it expired, was cancelled, or there was an error. If there was a processing error, the notification SHOULD be sent immediately upon detection of the error to the Push Initiator and the message should not be sent to the client. Otherwise, the notification MUST be sent after the message delivery process has been completed. The delivery process is considered completed when the message is no longer a candidate for delivery, e.g. the message has expired. If the push submission is indicated as rejected in step two in figure 3, then no result notification will be sent. The Push Initiator MUST have provided a return address (e.g. URL) during the push operation for this notification to be possible.

### Push Cancellation

The purpose of the Push Cancellation is to allow the Push Initiator to attempt to cancel a previously submitted push message. The Push Initiator initiates this operation. The PPG responds with an indication of whether the request was successful or not.

### Status Query

The status query operation allows the Push Initiator to request the current status of a message that has been previously submitted. If status is requested for a message which is addressed to multiple recipients, the PPG MUST send back a single response containing status query results for each of the recipients.

### Client Capabilities Query

This operation allows the Push Initiator to query the PPG for the capabilities of a specific device. The response is a multipart/related document containing the ccq-response (section 9.11) element in an XML document and, in the second entity, the actual client capabilities information in RDF [RDF] as defined in the User Agent Profile [UAPROF]. The PPG MAY add to the capabilities reported if the PPG is willing to perform transformations to the formats supported by the client. For example, if a client has JPG support but not GIF and a PPG is willing to convert GIF files to JPG, then the PPG may report that the client can support JPG and GIF files. The capabilities reported may be the combined PPG and client capabilities and they may have been derived from session capabilities or retrieved from a CC/PP server. Capabilities may also be derived using implementation dependent means.

## Addressing

There are three addresses to be considered by the Push Initiator: the push proxy gateway address, the wireless device address, and the result notification address. The push proxy gateway address must be known by the Push Initiator. This address is needed at the layer below the push access protocol. The push proxy gateway is addressed using a unique address that depends on the underlying protocol. For example, when the underlying protocol is HTTP, a URL [RFC1738] is used. The device addressing information is included as part of the message content (XML tagged content). Any character allowed in an RFC822 address may appear in the device address field. In addition, a “notify-requested-to” address may be provided by the Push Initiator when required so that the push proxy gateway can later respond to the Push Initiator with result notification.

### Multiple Recipient Addressing

There are scenarios in which a Push Initiator may want to send identical messages to multiple recipients. Rather than submitting multiple identical push messages, one to each recipient, the Push Initiator may submit a single push message addressed to multiple recipients. This section is intended to clarify behaviour related to operations on multiple recipients. When the PPG returns the push-response message, after a push submission to multiple recipients, the response corresponds to the message, regardless of the number of recipients specified in the push submission (there is one response for each push submission). When a Push Initiator requests status (section 9.8) with multiple addresses specified, the PPG MUST reply with a single statusquery-response (section 9.9) containing the individual statuses. The same is true when only a push-id is specified (no address specified) in the query for status of a multiple recipient message. Result notifications (section 9.6) MUST be sent by the PPG for each individual recipient, if result notification is requested by the Push Initiator during the submission of a message to multiple recipients. In cases where a message is sent to multiple recipients and later a cancel is requested by the initiator, the PPG MAY send back individual responses related to each of the multiple recipients or it MAY send responses related to many or all of the recipients. Support of multiple addresses is OPTIONAL in a PPG.

### Multicast/Broadcast Addresses

There are scenarios in which a single address submitted by a PI may be expanded by a PPG into multiple addresses for delivery. In addition, a single address transmitted on a wireless network may be received by multiple devices (e.g. broadcast). This type of service is expected for the distribution of information of interest to a broad population (e.g. news, weather, and traffic). This section is intended to clarify behaviour related to operations involving multicast and broadcast addresses. Since the address expansion is done in the PPG or in the wireless network, the behaviour between the PI and the PPG is identical to behaviour as if the address were not expanded. The response contains the individual address as submitted by the PI.

## Message Format

The push access protocol is independent of the transport used. PAP messages carry control information, and in the case of a push submission, also content and optionally client capabilities information. Control information includes command/response messages between the PPG and the Push Initiator, and parameters passed to the PPG for use in sending content to the wireless device. Examples of this type of information include the wireless device address, the delivery priority of the message, etc. This information is not normally delivered to the wireless device. Content is information that is intended for the wireless device. This information might be intelligible only to the wireless device (e.g. may be encrypted by the Push Initiator or may be application data for an application unknown to the PPG) or it may be recognisable by the PPG (e.g. HTML or WML). The PPG may be configured to perform some transformation on recognisable content (e.g. HTML to WML) for certain wireless devices. The other category of information is client capability information as specified in the User Agent Profile [UAPROF]. When more than control is carried in a message, the format of the message is a MIME multipart/related [RFC2387] compound object. When only control information (e.g. for message responses) is carried in a message, the format of the message is a simple application/xml entity. All information is transported within a single message body. In the multipart messages, the first entity contains all push related control information in an XML document, the second entity contains the content for the wireless device, the third entity, if present, contains UAPROF client capabilities. The format of the content entity is specified in [PushMsg].

### Control Entity Format

The control entity is a MIME body part which holds an XML document containing one pap element as defined in section 9.1. The control entity MUST be included in every PAP request and response. The control entity MUST be the first entity in the MIME multipart/related message.

### Content Entity Format

The content entity is a MIME body part containing the content to be sent to the wireless device. The content type is not defined by the PAP, but can be any type as long as it is described by MIME. The content entity is included only in the push submission and is not included in any other operation request or response. The content entity MUST be the second entity in the MIME multipart/related message.

### Capabilities Entity Format

The capabilities entity is a MIME body part containing the Push Initiator's assumed subset of the capabilities of the wireless device/user agent. The capabilities format is specified in the User Agent Profile [UAPROF]. The capabilities entity, if present, MUST be the third entity in the Push Submission MIME multipart/related message and MUST be the second entity in a Client Capabilities Query response.