This chapter describes the operations in the WAP Push interface of the RESTful facade provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful WAP Push interface to send a Wireless Application Protocol (WAP) Push message. The content of the message is coded as a Password Authentication Protocol (PAP) message.
The message payload must adhere to the following:
WAP Service Indication Specification, as specified in Service Indication Version 31-July-2001, Wireless Application Protocol WAP-167-ServiceInd-20010731-a.
WAP Service Loading Specification, as specified in Service Loading Version 31-Jul-2001, Wireless Application Protocol WAP-168-ServiceLoad-20010731-a.
WAP Cache Operation Specification, as specified in Cache Operation Version 31-Jul-2001, Wireless Application Protocol WAP-175-CacheOp-20010731-a.
For links to the specifications, see:
http://www.openmobilealliance.org/tech/affiliates/wap/wapindex.html
.
The actual message is sent as an HTTP attachment. See "Headers for Multipart Messages with Attachments" for more information.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at
http://host:port/rest/push_message/index.html
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The Send Push Message operation sends a WAP Push message.
http://host:port/rest/push_message/messages
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request headers depend on the type of message:
If the message content is in the form of an attachment, the request will be multipart and the request header must contain the header fields that describe the parts of the message.
If the message does not contain an attachment, the special headers associated with the multipart messaged are not used.
The message part content for this operation accepts the following parameters:
destinationAddresses: String. Required. An array of terminal addresses.
Each of the addresses in this array should be formatted according to the Push Proxy Gateway Service Specification (WAP-249-PPGService-20010713-a).
pushId: String. Required. A unique identifier provided by the application. Supported types are PLMN and USER.
replaceMethod: String. Required. Valid entries are:
all
pendingOnly
replaceMethod is used in conjunction with the pushId parameter and defines how to replace a previously sent message. This entry will be ignored if replacePushId is NULL.
requesterId: String. Required. The application ID as given by the operator.
serviceCode: String. Required. A code for charging purposes.
additionalProperties. An array of JSON objects. Optional.
Each element in the array is a JSON object used to add additional properties with the following parameters:
name: String. Required if the additionalProperties
object is present. Valid entries include pap.priority, pap.delivery-method, pap.network-required, pap.bearer, and pap.bearer-required.
value
: String. Required if the additionalProperties object is present. The value associated with the property.
deliverAfterTimeStamp: String. Optional. The date and time after which the content should be delivered to the wireless device. This entry is in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss
.
If the network does not support this parameter, this entry will be rejected.
deliverBeforeTimeStamp: String. Optional. The date and time by when the content should be delivered to the wireless device. This entry is in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss
.
If the network does not support this parameter, this entry will be rejected.
progressNoteRequested. Boolean. Optional. If true, the application wishes to receive progress notes at the address specified by the resultNotificationEndpoint.
replacePushId: String. Optional. The Push Id of the message that is to be replaced. If it is set to NULL, the message is treated as a new message. If it is set to a valid ID, message replacement will occur for all currently pending messages. Messages that have already been delivered cannot be canceled, and therefore cannot.
Messages that have already been delivered cannot be canceled, and therefore cannot be replaced
resultNotificationEndpoint: String. Optional. The URI which represents the endpoint address to which the notification should be delivered. This string should be a Bayeux protocol channel name that begins with /bayeux/
appInstanceID
where appInstanceID is the client application's application instance account ID.
If the application does not wish to receive notifications, this value should be NULL.
sourceReference: String. Optional. The name of the service provider.
The message part content for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{ "destinationAddresses": ["String"], "pushId": "String", "replaceMethod": "all|pending-only", "requesterID": "String", "serviceCode": "String", "additionalProperties": [{ "name": "String", "value": "String" }], "deliverAfterTimestamp": "Calendar", "deliverBeforeTimestamp": "Calendar", "progressNotesRequested": "Boolean", "replacePushId": "String", "resultNotificationEndpoint": "URI", "sourceReference": "String" }
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The response body is a nested JSON object. It contains the result attribute with the following attributes and data objects:
pushId: String. Required. A unique identifier provided by the application. Supported types are PLMN and USER.
result: JSON object. This object contains the outcome code. It contains the following two entries:
code: String. The outcome code generated by the network node. Table 22-1 lists the possible values.
description: String. The textual description for the code.
additionalProperties: An array of JSON objects used to add additional properties.
Each element in the array is a JSON object with the following parameters:
name: String. The name of an additional property. One of: pap.stage, pap.note, pap.time.
value: String. The value associated with the property.
replyTime: String. The date and time for the reply in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss
.
senderAddress: String. Optional. The sender's address.
senderName: String. Optional. The sender's name.
Table 22-1 Possible Outcome Codes
Code | Description |
---|---|
1000 |
OK |
1001 |
Accepted for processing |
2000 |
Bad request |
2001 |
Forbidden |
2002 |
Address error |
2003 |
Address not found |
2004 |
Push ID not found |
2005 |
Capabilities mismatch |
2006 |
Required capabilities not supported |
2007 |
Duplicate Push ID |
2008 |
Cancellation not possible |
3000 |
Internal server error |
3001 |
Not implemented |
3002 |
Version not supported |
3003 |
Not possible |
3004 |
Capability matching not possible |
3005 |
Multiple addresses not supported |
3006 |
Transformation failure |
3007 |
Specified delivery method not possible |
3008 |
Capabilities not available |
3009 |
Required network not available |
3010 |
Required bearer not available |
3011 |
Replacement not supported |
4000 |
Service failure |
4001 |
Service unavailable |
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"result": { "pushId": "String", "result": { "code": "String", "description": "String" }, "additionalProperties": [{ "name": "String", "value": "String" }], "replyTime": "Calendar", "senderAddress": "String", "senderName": "String" }}
Result Notification Message Object
The resultNotificationMessage object delivered to the resultNotificationEndpoint address is a nested JSON object containing the following entries:
address: String. The address of the terminal to which this message is sent.
code: String. The final state of the message, one of the values listed in Table 22-1.
messageState: String. The state of the message. One of:
rejected
pending
delivered
undelivered
expired
aborted
timeout
cancelled
unknown
pushId: String. The unique identifier defined in the initial request, used for correlation.
additionalProperties. An array of JSON objects used to add additional properties.
Each element in the array is a JSON object with the following parameters:
name: String. The name of an additional property, dependent on the network node. One of: pap.priority, pap.delivery-method, pap.network-required, pap.bearer, and pap.bearer-required.
value: String. The value associated with the property.
description: String. A description of the notification provided by the network. (May not be provided).
eventTime: String. The date and time the message reached the destination in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss
.
receivedTime: String. The date and time the message was received at the network node in ISO 8601 extended format, as yyyy-mm-ddThh-mm-ss
.
senderAddress: String. Optional. The sender's address.
senderName: String. Optional. The sender's name.
The notification of the result for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type:
{"resultNotificationMessage": { "address": "String", "code": "String", "messageState": "rejected|pending|delivered|undeliverable|expired|aborted|timeout|cancelled|unknown", "pushId": "String", "additionalProperties": [{ "name": "String", "value": "String" }], "description": "String", "eventTime": "Calendar", "receivedTime": "Calendar", "senderAddress": "String", "senderName": "String" }}