# Application Development Guide

# Parlay X 2.1 Interfaces

This chapter describes the supported Parlay X 2.1 interfaces and contains information that is specific for Oracle Communications Services Gatekeeper, and not found in the specifications. For detailed descriptions of the interfaces, methods and parameters, refer to the specifications.

See http://portal.etsi.org/docbox/TISPAN/Open/OSA/ParlayX21.html for links to the specifications.

- Parlay X 2.1 Part 2: Third Party Call

- Interface: ThirdPartyCall
- Error Codes

- Parlay X 2.1 Part 3: Call Notification

- Interface: CallDirection
- Interface: CallNotification
- Interface: CallNotificationManager
- Interface: CallDirectionManager
- Error Codes

- Parlay X 2.1 Part 4: Short messaging

- Interface: SendSms
- Interface: SmsNotification
- Interface: ReceiveSms
- Interface: SmsNotificationManager
- Error Codes

- Parlay X 2.1 Part 5: Multimedia messaging

- Interface: SendMessage
- Interface: ReceiveMessage
- Interface: MessageNotification
- Interface: MessageNotificationManager
- Error Codes

- Parlay X 2.1 Part 9: Terminal location

- Interface: TerminalLocation
- Interface: TerminalLocationNotificationManager
- Interface: TerminalLocationNotification
- Error Codes

- Parlay X 2.1 Part 14: Presence

- Interface: PresenceConsumer
- Interface: PresenceNotification
- Interface: PresenceSupplier
- Error Codes

- About notifications
- General error codes
- Code examples
- Code examples

## Parlay X 2.1 Part 2: Third Party Call

This set of interfaces is compliant to ETSI ES 202 391-2 V1.2.1 (2006-12) Open Service Access (OSA); Parlay X Web Services; Part 2: Third Party Call (Parlay X 2).

### Interface: ThirdPartyCall

The endpoint for this interface is: http://<host>:<port>/parlayx21/third_party_call/ThirdPartyCall

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### MakeCall

Sets up a call between two parties.

#### GetCallInformation

Displays information about a call.

#### EndCall

Ends a call.

#### CancelCall

Cancels a call setup procedure.

### Error Codes

See General error codes.

## Parlay X 2.1 Part 3: Call Notification

This set of interfaces is compliant to ETSI ES 202 391-3 V1.2.1 (2006-12) Open Service Access (OSA); Parlay X Web Services; Part 3: Call Notification (Parlay X 2).

### Interface: CallDirection

This interface is implemented by an application, and the consumer of this interface is Oracle Communications Services Gatekeeper. The WSDL that defines the interface can be downloaded from:

`http://<host>:<port>/parlayx21/call_notification/wsdls/parlayx_call_direction_interface_2_2.wsdl`

`http://<host>:<port>/parlayx21/call_notification/wsdls/parlayx_call_direction_service_2_2.wsdl`

`http://<host>:<port>/parlayx21/call_notification/wsdls/parlayx_call_notification_types_2_2.xsd`

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### HandleBusy

Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party is busy.

#### HandleNotReachable

Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party is not reachable.

#### HandleNoAnswer

Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party does not answer.

#### HandleCalledNumber

Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, prior to call setup.

### Interface: CallNotification

This interface is implemented by an application, and the consumer of this interface is Oracle Communications Services Gatekeeper. The WSDL that defines the interface can be downloaded from:

`http://<host>:<port>/parlayx21/call_notification/wsdls/parlayx_call_notification_interface_2_2.wsdl`

`http://<host>:<port>/parlayx21/call_notification/wsdls/parlayx_call_notification_service_2_2.wsdl`

`http://<host>:<port>/parlayx21/call_notification/wsdls/parlayx_call_notification_types_2_2.xsd`

#### NotifyBusy

Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party is busy.

#### NotifyNotReachable

Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party is not reachable.

#### NotifyNoAnswer

Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party does not answer.

#### NotifyCalledNumber

Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, prior to call setup.

### Interface: CallNotificationManager

The endpoint for this interface is: http://<host>:<port>/parlayx21/call_notification/CallNotificationManager

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### StartCallNotification

Starts a subscription for call notifications.

#### StopCallNotification

Stops a subscription for call notifications.

### Interface: CallDirectionManager

The endpoint for this interface is: http://<host>:<port>/parlayx21/call_notification/CallDirectionManager

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### StartCallDirectionNotification

Starts a subscription for call direction notifications.

#### StopCallDirectionNotification

Stops a subscription for call direction notifications.

### Error Codes

See General error codes.

## Parlay X 2.1 Part 4: Short messaging

This set of interfaces is compliant to ETSI ES 202 391-4 V1.2.1 (2006-12) Open Service Access (OSA); Parlay X Web Services; Part 4: Short Messaging (Parlay X 2).

### Interface: SendSms

The endpoint for this interface is: http://<host>:<port>/parlayx21/sms/SendSms

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

If a backwards-compatible communication service is used:

- The parameter senderAddress is either of the format tel:<mailbox ID>\<mailbox password>\<Sender name> or just <sender name> depending on how the application was provisioned in Oracle Communications Services Gatekeeper.
- The priority parameter is not supported.

#### SendSms

Sends an SMS to one or more destinations.

#### SendSmsLogo

Sends an SMS Logo to one or more destinations.

Logos in SmartMessaging and EMS are supported. The image is not scaled.

Logos in the following raw image formats are supported:

- bmp
- gif
- jpg
- png

The logos are in pure black and white (gray scale not supported). Animated images are not supported. Scaling is not supported.

If the logo shall be converted to SmartMessaging format, the image cannot be larger than 72x14 pixels.

If the logo shall be is sent in EMS format, the following rules apply:

- If the image is 16x16 pixels, the logo is sent as an EMS small picture.
- If the image is 32x32 pixels, the logo is sent as an EMS large picture.
- If the image is of any other size, the logo is sent as an EMS variable picture.
- Images up to 1024 pixels are supported.

#### SendSmsRingtone

Sends an SMS Ringtone to one or more destinations.

Ringtones can be in any of these formats:

- RTX
- SmartMessaging
- EMS (iMelody)

#### GetSmsDeliveryStatus

Gets the delivery status of a previously sent SMS.

It is possible to query delivery status of an SMS only if a callback reference was not defined when the SMS was sent. If a callback reference was defined, NotifySmsDeliveryReceipt is invoked by Oracle Communications Services Gatekeeper and the delivery status is not stored. If the delivery status is stored in Oracle Communications Services Gatekeeper, it is stored for a configurable period of time.

### Interface: SmsNotification

This interface is implemented by an application, and the consumer of this interface is Oracle Communications Services Gatekeeper. The WSDL that defines the interface can be downloaded from:

`http://<host>:<port>/parlayx21/sms/wsdls/parlayx_sms_notification_interface_2_2.wsdl`

`http://<host>:<port>/parlayx21/sms/wsdls/parlayx_sms_notification_service_2_2.wsdl`

`http://<host>:<port>/parlayx21/sms/wsdls/parlayx_sms_types_2_2.xsd`

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### NotifySmsReception

Sends an SMS that is received by Oracle Communications Services Gatekeeper to an application given that the SMS fulfills a set of criteria. The criteria is either defined by the application itself, using startSmsNotification or defined using a provisioning step in Oracle Communications Services Gatekeeper.

Shortcode translation, if appropriate, is applied.

#### NotifySmsDeliveryReceipt

Sends a delivery receipt that a previously sent SMS has been received by its destination. The delivery receipt is propagated to the application given that the application provided a callback reference when sending the SMS.

### Interface: ReceiveSms

The endpoint for this interface is: http://<host>:<port>/parlayx21/sms/ReceiveSms

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### GetReceivedSms

Gets messages that have been received by Oracle Communications Services Gatekeeper. The SMSs are fetched using a registrationIdentifier used when the notification was registered using a provisioning step in Oracle Communications Services Gatekeeper.

### Interface: SmsNotificationManager

The endpoint for this interface is: http://<host>:<port>/parlayx21/sms/SmsNotificationManager

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### StartSmsNotification

Initiates notifications to the application for a given service activation number and criteria.

Note: | Service activation number may be provisioned to cater for a range of numbers via short code translations.

Note: | The equivalent to this operation may have been performed as an off-line provisioning step by the Oracle Communications Services Gatekeeper administrator.

#### StopSmsNotification

Ends a previously started notification.

### Error Codes

See General error codes.

## Parlay X 2.1 Part 5: Multimedia messaging

This set of interfaces is compliant to ETSI ES 202 391-5 V1.2.1 (2006-12) Open Service Access (OSA); Parlay X Web Services; Part 5: Multimedia Messaging (Parlay X 2).

### Interface: SendMessage

The endpoint for this interface is: http://<host>:<port>/parlayx21/multimedia_messaging/SendMessage

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### SendMessage

Sends a multimedia message. The content of the message is sent as a SOAP attachment. E-mail is not supported.

Table 9-1 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | WNG-000002 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | MMS-000001 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | MMS-000002 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | MMS-000003 | Address is utilizing an unsupported address type.
SVC0001 | MMS-000005 | Message could not be delivered to MMSC.

#### GetMessageDeliveryStatus

Gets the delivery status of a previously sent MMS.

It is possible to query delivery status of an MMS only if a callback reference was not defined when the message was sent. If a callback reference was defined, NotifyMessageDeliveryReceipt is invoked by Oracle Communications Services Gatekeeper and the delivery status is not stored. If the delivery status is stored in Oracle Communications Services Gatekeeper, it is stored for a configurable period of time.

Note: | Oracle Communications Services Gatekeeper may be configured not to store delivery status for MMS.

Table 9-2 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | WNG-000002 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.
SVC0002 | RequestIdentifier | Message is not found.

### Interface: ReceiveMessage

The endpoint for this interface is: http://<host>:<port>/parlayx21/multimedia_messaging/ReceiveMessage

Where the values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### GetReceivedMessages

Polls Oracle Communications Services Gatekeeper for received messages.

The registrationIdentifier is required. Received message are stored in Oracle Communications Services Gatekeeper only for a configurable period of time.

Table 9-3 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | WNG-000002 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.
SVC0002 | MMS-000002 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.

#### GetMessageURIs

Not supported.

#### GetMessage

Gets a specific message that was received by Oracle Communications Services Gatekeeper and belongs to the application.

Table 9-4 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | WNG-000002 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | MMS-000004 | Correlator does not exist, no notification corresponds to the correlator.

### Interface: MessageNotification

This interface is implemented by an application, and the consumer of this interface is Oracle Communications Services Gatekeeper. The WSDL that defines the interface can be downloaded from:

`http://<host>:<port>/parlayx21/multimedia_messaging/wsdls/parlayx_mm_notification_interface_2_4.wsdl`

`http://<host>:<port>/parlayx21/multimedia_messaging/wsdls/parlayx_mm_notification_service_2_4.wsdl`

`http://<host>:<port>/parlayx21/multimedia_messaging/wsdls/parlayx_mm_types_2_4.xsd`

Where the values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### NotifyMessageReception

Sends a notification to an application that an MMS destined for the application is received by Oracle Communications Services Gatekeeper.

#### NotifyMessageDeliveryReceipt

Sends a notification to an application that a previously sent MMS has been delivered to its destination.

Note: | Oracle Communications Services Gatekeeper can be configured to support delivery notifications or not.

### Interface: MessageNotificationManager

The endpoint for this interface is: http://<host>:<port>/parlayx21/multimedia_messaging/MessageNotificationManager

Where the values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### StartMessageNotification

Initiates notifications to the application for a given service activation number and criteria.

Note: | Service activation number may be provisioned to cater for a range of numbers via short code translations.

Note: | The equivalent to this operation may have been performed as an off-line provisioning step by the Oracle Communications Services Gatekeeper administrator.

Table 9-5 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | WNG-000002 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.

#### StopMessageNotification

Ends a previously started notification.

Table 9-6 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | WNG-000002 | Internal problem in Oracle Communications Services Gatekeeper. Contact Oracle Communications Services Gatekeeper administrator.
SVC0002 | Correlator | Correlator does not exist, no notification corresponds to the correlator.

### Error Codes

See General error codes.

## Parlay X 2.1 Part 9: Terminal location

This set of interfaces is compliant to ETSI ES 202 391-9 V1.2.1 (2006-12), Open Service Access (OSA); Parlay X Web Services; Part 9: Terminal Location (Parlay X 2).

### Interface: TerminalLocation

The endpoint for this interface is: http://<host>:<port>/parlayx21/terminal_location/TerminalLocation

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### GetLocation

Gets the location for a terminal.

Table 9-7 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | TL-000007 | Communication problems between Oracle Communications Services Gatekeeper and the network node. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000010 | Communication problems between Oracle Communications Services Gatekeeper and the network node, unable to interpret response. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000009 | No location data received from network.
SVC0001 | TL-000011 | Unknown error received from network.
SVC0002 |  | Invalid parameter provided in request.
SVC0200 |  | Accuracy of location is not within acceptable limit.
POL0001 |  | General policy error.
POL0002 |  | Privacy error.
POL0230 |  | Requested accuracy not supported.

#### GetTerminalDistance

Gets the distance from a certain point to the location of a terminal.

Table 9-8 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | TL-000007 | Communication problems between Oracle Communications Services Gatekeeper and network node. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000010 | Communication problems between Oracle Communications Services Gatekeeper and network node, unable to interpret response. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000009 | No location data received from network.
SVC0001 | TL-000011 | Unknown error received from network.
SVC0002 |  | Invalid parameter provided in request.
SVC0200 |  | Accuracy of location is not within acceptable limit.
POL0001 |  | General policy error.
POL0002 |  | Privacy error.
POL0230 |  | Requested accuracy not supported.

#### GetLocationForGroup

Gets the location for one or more terminals.

Table 9-9 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | TL-000007 | Communication problems between Oracle Communications Services Gatekeeper and network node. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000010 | Communication problems between Oracle Communications Services Gatekeeper and network node, unable to interpret response. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000009 | No location data received from network.
SVC0001 | TL-000011 | Unknown error received from network.
SVC0002 |  | Invalid parameter provided in request.
SVC0004 |  | No valid addresses.
SVC0200 |  | Accuracy of location is not within acceptable limit.
POL0001 |  | General policy error.
POL0002 |  | Privacy error.
POL0230 |  | Requested accuracy not supported.

### Interface: TerminalLocationNotificationManager

The endpoint for this interface is: http://<host>:<port>/parlayx21/terminal_location/TerminalLocationNotificationManager

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### StartGeographicalNotification

Initiates location notifications to the application when one or more terminal changes their location according to a criteria.

Table 9-10 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | TL-000003 | Unable to start geographical notification due to a network error. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000004 | Unable to start geographical notification due to an internal error. Contact Oracle Communications Services Gatekeeper administrator.
SVC0002 |  | Invalid parameter provided in request.
SVC0004 |  | No valid addresses.
SVC0005 |  | Correlator already exists.
POL0001 |  | General policy error.

#### StartPeriodicNotification

Initiates location notifications to the application on a periodic basis.

Table 9-11 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | TL-000005 | Unable to start periodic notification due to a network error. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000006 | Unable to start periodic notification due to an internal error. Contact Oracle Communications Services Gatekeeper administrator.
SVC0002 |  | Invalid parameter provided in request.
SVC0004 |  | No valid addresses.
SVC0005 |  | Correlator already exists.
POL0001 |  | General policy error.

#### EndNotification

Ends a previously started notification.

Table 9-12 exceptions and error codes
Exception | Error code | Reason/Action
--- | --- | ---
SVC0001 | TL-000001 | Unable to start geographical notification due to a network error. Contact Oracle Communications Services Gatekeeper administrator.
SVC0001 | TL-000002 | Unable to start geographical notification due to an internal error. Contact Oracle Communications Services Gatekeeper administrator.
SVC0002 |  | Invalid parameter provided in request.
POL0001 |  | General policy error.

### Interface: TerminalLocationNotification

This interface is implemented by an application, and the consumer of this interface is Oracle Communications Services Gatekeeper. The WSDL that defines the interface can be downloaded from:

`http://<host>:<port>/parlayx21/terminal_location/wsdls/parlayx_terminal_location_notification_interface_2_2.wsdl`

`http://<host>:<port>/parlayx21/terminal_location/wsdls/parlayx_terminal_location_notification_service_2_2.wsdl`

`http://<host>:<port>/parlayx21/terminal_location/wsdls/parlayx_terminal_location_types_2_2.xsdl`

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### LocationNotification

Notifies an application about a change of location for a terminal.

#### LocationError

Notifies an application that the subscription for location notifications was cancelled by Oracle Communications Services Gatekeeper.

#### LocationEnd

Notifies an application that no more location notifications are being sent to the application.

### Error Codes

See General error codes.

## Parlay X 2.1 Part 14: Presence

This set of interfaces is compliant to ETSI ES 202 391-14 V1.2.1 (2006-12), Open Service Access (OSA); Parlay X Web Services; Part 14: Presence (Parlay X 2).

### Interface: PresenceConsumer

The endpoint for this interface is: http://<host>:<port>//parlayx21/presence/PresenceConsumer

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### subscribePresence

Requests a subscription for presence information about a presentity.

For the parameter presentity, only SIP URI can be used. Group-URI is not supported

#### getUserPresence

Gets presence information about a presentity.

For the parameter presentity, only SIP URI can be used. Group-URI is not supported

#### startPresenceNotification

Initiates presence notifications to the application when one or more presence attributes changes for a presentity.

For the parameter presentity, only SIP URI can be used. Group-URI is not supported

The parameter frequency is not supported. The application is notified when an update of presence information is received from the network.

#### endPresenceNotification

Ends a previously started notification.

### Interface: PresenceNotification

This interface is implemented by an application, and the consumer of this interface is Oracle Communications Services Gatekeeper. The WSDL that defines the interface can be downloaded from:

`http://<host>:<port>/parlayx21/presence/wsdls/parlayx_presence_notification_interface_2_3.wsdl`

`http://<host>:<port>/parlayx21/presence/wsdls/parlayx_presence_notification_service_2_3.wsdl`

`http://<host>:<port>/parlayx21/presence/wsdls/parlayx_presence_types_2_3.xsd`

Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

#### statusChanged

Notifies an application about a change of presence attributes for a presentity.

#### statusEnd

Notifies an application that no more notifications will be sent to the application.

#### notifySubscription

Notifies an application that the presentity has handled the request for presence information.

#### subscriptionEnded

Notifies an application that the subscription for presence information has ended.

### Interface: PresenceSupplier

The endpoint for this interface is: http://<host>:<port>//parlayx21/presence/PresenceSupplier where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.

Notes: | The Presence Supplier interface requires that a Presence Server be available in the underlying network. Oracle Communications Services Gatekeeper interacts with this server to provide this functionality to the application.

Note: | Because the Parlay X 2.1 interface does not provide parameters to identify the presentity URI but this information is required to interact with the network, Oracle Communications Services Gatekeeper by default maps the URI to the client’s Application Instance ID. The application can override this value using the Parameter Tunneling function. The <param> to use is key = “wlng.presence.parlay21.presentity.uri” and value = $the_desired_URI.

#### publish

Publishes presence data about a presentity

Note: | The Presence Server in the network must support http://tools.ietf.org/html/draft-ietf-simple-partial-publish-07#page-4 for this functionality to work.

#### getOpenSubscriptions

Gets a list of new watchers who wish to subscribe to this presentity’s data.

Note: | The Presence Server in the network must support http://tools.ietf.org/html/draft-ietf-simple-partial-pidf-format-10 and http://tools.ietf.org/html/rfc3857 (http://tools.ietf.org/html/draft-ietf-simple-winfo-package-05) for this functionality to work.

#### updateSubscriptionAuthorization

Adds new watchers and updates the permissions of existing watchers of this presentity’s data. This is the usual follow-up to the getOpenSubscriptions operation.

Note: | This operation requires the presence of both a Presence Server and a Data Manipulation Server in the underlying network.

An SVC0220 service exception (NoSubscriptionRequest) is thrown if the presentity attempts to confirm the subscription of a watcher who has not asked to subscribe to the presentity’s data.

#### getMyWatchers

Returns an array of the watchers that are subscribed to the presentity’s data.

Note: | The Presence Server in the network must support http://tools.ietf.org/html/draft-ietf-simple-partial-pidf-format-10 and http://tools.ietf.org/html/rfc3857 (http://tools.ietf.org/html/draft-ietf-simple-winfo-package-05) for this functionality to work.

#### getSubscribedAttributes

Not supported.

#### blockSubscription

Blocks the flow of presence information to a subscribed watcher by cancelling the subscription. The watcher is notified using subscriptionEnded.

An SVC0221 service exception (Not a watcher) is thrown if the URI in the field watcher is not a watcher of the presentity.

### Error Codes

See General error codes.

## About notifications

When an application has started a notification, the notification is persisted. This means that if an application has started a notification and destroys the session, the notification is still registered and matching notifications are sent to the application when it connects to Oracle Communications Services Gatekeeper.

## General Exceptions

This section describes the exception handling for the Parlay X 2.1 interfaces.

These exception types are defined:

- Service Exceptions
- Policy Exceptions

Service Exceptions are related to the operation of the service itself. The following exceptions are general:

- SVC0001: Service error.
- SVC0002: Invalid input value
- SVC0003: Invalid input value with list of valid values
- SVC0004: No valid addresses
- SVC0005: Duplicate correlator
- SVC0006: Invalid group
- SVC0007: Invalid charging information
- SVC0008: Overlapping Criteria

PolicyExceptions are thrown when a policy has been violated, including violations of a service level agreements. The following general PolicyExceptions are defined:

- POL0001: Policy error
- POL0002: Privacy error
- POL0003: Too many addresses specified
- POL0004: Unlimited notifications not supported
- POL0005: Too many notifications requested
- POL0006: Groups not allowed
- POL0007: Nested groups not allowed
- POL0008: Charging not supported
- POL0009: Invalid frequency requested

Within the exception, an error code is defined. The error code details why the exception was thrown. See General error codes

## General error codes

The following are general error codes for SVC0001: Service error:

- Null sessionID (loginTicket) expired.
- WNG-000000 No error.
- WNG-000001 Unknown error.
- WNG-000002 Storage service error.
- PLG-000001 Could not find remote ejb home in access tier.
- PLG-000002 Could not create the ejb.
- PLG-000003 Could not access callback ejb.
- PLG-000004 Matching plug-in cannot be found because, for example, route has not been set up
- SIP-000001 Could not find remote ejb home.
- SIP-000002 Could not create the ejb.
- SIP-000003 Could not access remote ejb.
- SIP-000004 Could not create SIP session.
- SIP-000005 Failed to send SIP message.
- SIP-000006 Internal SIP stack error.
- CN-000001 Two requests for call direction overlap with each other
- CN-000002 Internal error when accessing the subscription storage
- CN-000003 Could not find the call-back plug-in
- CN-000004 The call direction routing address is not valid
- PRESENCE-000001 Failed to use the default 'duration' for a notification.
- PRESENCE-000002 Failed to use the default value for count for a notification.
- PRESENCE-000003 The application has no SIP-URI mapping configured.
- PRESENCE-000004 Internal error. Failed to put data in WorkContext.
- PLC-000001 Internal policy engine error
- OSA-000001 Invalid network state.
- OSA-000002 Invalid interface type.
- OSA-000003 Invalid event type.
- OSA-000004 Unsupported address plan.
- OSA-000005 Communication failure between OSA Gateway and Oracle Communications Services Gatekeeper.
- TL-000001 Unable to end notification, network error
- TL-000002 Unable to end notification, internal error
- TL- 000003 Unable to start geographical notification, network error.
- TL-000004 Unable to start geographical notification, internal error
- TL-000005 Unable to start periodic notification, network error.
- TL-000006 Unable to start periodic notification, internal error.
- TL-000007 Unable to get location, network error.
- TL-000008 Unable to get location, internal error.
- TL-000009 Unable to get location, no data found.
- TL-000010 Failed to parse response, internal error.
- TL-000011 Failed to get location information, error returned from MLP server.
- MMS-000001 Unable to perform action. Network error.
- MMS-000002 Unable to retrieve configuration, internal error.
- MMS-000003 The used address type is not supported.
- MMS-000004 An error occurred when an attachment was put into the request context.
- MMS-000005 The MM7 Relay server responded with an error code.
- SMS-000001 Unable to perform action. Network error.
- SMS-000002 Unable to retrieve configuration, internal error.
- SMS-000003 The used address type is not supported
- SMS-000004 Unable to encode message segments
- SMS-000005 GSM message format incorrect
- TPC-000001 Unable to retrieve configuration, internal error

## Code examples

Below are some code examples that illustrate how to use the Parlay X 2.1 interfaces.

### Example: sendSMS

Below is an example of sending an SMS.

Listing 9-1 SendSMS example

    org.csapi.schema.parlayx.sms.send.v2_2.local.SendSms request =

    new org.csapi.schema.parlayx.sms.send.v2_2.local.SendSms();

    SimpleReference sr = new SimpleReference();

    sr.setEndpoint(new URI("http://localhost:8111/SmsNotificationService/services/SmsNotification?WSDL"));

    sr.setCorrelator("cor188");

    sr.setInterfaceName("InterfaceName");

    ChargingInformation charging = new ChargingInformation();

    charging.setAmount(new BigDecimal("1.1"));

    charging.setCode("qwerty");

    charging.setCurrency("USD");

    charging.setDescription("some charging info");

    sendInf.setCharging(charging);

    URI[] uri = new URI[1];

    uri[0] = new URI("1234");

    request.setAddresses(uri);

    request.setCharging(charging);

    request.setReceiptRequest(sr);

    request.setMessage("we are testing sms!");

    request.setSenderName(“6001”);

    org.csapi.schema.parlayx.sms.send.v2_2.local.SendSmsResponse response =

    smport.sendSms(request);

    String sendresult = response.getResult();

    System.out.println("result: " + sendresult);

### Example: startSmsNotification

Below is an example of using startSmsNotification.

Listing 9-2 startSmsNotification example

    org.csapi.schema.parlayx.sms.notification_manager.v2_3.local.StartSmsNotification parameters =

    new org.csapi.schema.parlayx.sms.notification_manager.v2_3.local.StartSmsNotification();

    parameters.setCriteria("hello");

    SimpleReference sr = new SimpleReference();

    sr.setEndpoint(new URI("http://localhost:8111/SmsNotificationService/services/SmsNotification?WSDL"));

    sr.setCorrelator("cor189");

    sr.setInterfaceName("interfaceName");

    parameters.setReference(sr);

    URI uri = new URI("tel:6001");

    parameters.setSmsServiceActivationNumber(uri);

    port.startSmsNotification(parameters);

### Example: getReceivedSms

Below is an example of polling for SMSes using getReceivedSms.

Listing 9-3 getReceivedSms example

    org.csapi.schema.parlayx.sms.receive.v2_2.local.GetReceivedSms parameters =

    new org.csapi.schema.parlayx.sms.receive.v2_2.local.GetReceivedSms();

    parameters.setRegistrationIdentifier("1");

    org.csapi.schema.parlayx.sms.receive.v2_2.local.GetReceivedSmsResponse response =

    port.getReceivedSms(parameters);

    org.csapi.schema.parlayx.sms.v2_2.SmsMessage[] msgs =

    response.getResult();

    if(msgs != null) {

      for(org.csapi.schema.parlayx.sms.v2_2.SmsMessage msg : msgs) {

        System.out.println(msg.getMessage());

      }

    }

### Example: sendMessage

Below is an example of sending an MMS.

Listing 9-4 sendMessage example

    org.csapi.schema.parlayx.multimedia_messaging.send.v2_4.local.SendMessage request =

    new org.csapi.schema.parlayx.multimedia_messaging.send.v2_4.local.SendMessage();

    ChargingInformation charging = new ChargingInformation();

    charging.setAmount(new BigDecimal("1.1"));

    charging.setCode("qwerty");

    charging.setCurrency("USD");

    charging.setDescription("some charging info");

    sendInf.setCharging(charging);

    SimpleReference sr = new SimpleReference();

    if(getProperty("notification_mt").equalsIgnoreCase("true")) {

      sr.setEndpoint(new URI(getProperty(ClientConstants.NOTIFICATION_LISTENER_URL)));

      sr.setCorrelator(getProperty("correlator"));

      sr.setInterfaceName(getProperty("interfacename"));

    }

    URI[] uri = new URI[1];

    uri[0] = new URI("1234");

    request.setAddresses(uri);

    request.setCharging(charging);

    request.setPriority(MessagePriority.fromString("Default"));

    request.setReceiptRequest(sr);

    request.setSenderAddress("6001");

    request.setSubject("subject");

    org.csapi.schema.parlayx.multimedia_messaging.send.v2_4.local.SendMessageResponse response =

    smport.sendMessage(request);

    String sendresult = response.getResult();

    System.out.println("sendresult: " + sendresult);

## Example: getReceivedMessages and getMessage

Below is an example of polling for a received MMS.

Listing 9-5 getReceivedMessages and getMessage example

    org.csapi.schema.parlayx.multimedia_messaging.receive.v2_4.local.GetReceivedMessages parameters =

    new org.csapi.schema.parlayx.multimedia_messaging.receive.v2_4.local.GetReceivedMessages();

    parameters.setPriority(org.csapi.schema.parlayx.multimedia_messaging.v2_4.MessagePriority.fromString("Default"));

    parameters.setRegistrationIdentifier("2");

    org.csapi.schema.parlayx.multimedia_messaging.receive.v2_4.local.GetReceivedMessagesResponse result =

    port.getReceivedMessages(parameters);

    org.csapi.schema.parlayx.multimedia_messaging.v2_4.MessageReference[] refs =

    result.getResult();

    if(refs != null) {

      for(org.csapi.schema.parlayx.multimedia_messaging.v2_4.MessageReference ref : refs) {

        String id = ref.getMessageIdentifier();

        org.csapi.schema.parlayx.multimedia_messaging.receive.v2_4.local.GetMessage p2 =

        new org.csapi.schema.parlayx.multimedia_messaging.receive.v2_4.local.GetMessage();

        p2.setMessageRefIdentifier(id);

        port.getMessage(p2);

      }

    }

### Example: getLocation

Below is an example of getting the location of a terminal.

Listing 9-6 getLocation example

    org.csapi.schema.parlayx.terminal_location.v2_2.local.GetLocation parameters =

    new org.csapi.schema.parlayx.terminal_location.v2_2.local.GetLocation();

    parameters.setAcceptableAccuracy(5);

    parameters.setAddress(new URI("1234"));

    parameters.setRequestedAccuracy(5);

    TimeMetric maximumAge = new TimeMetric();

    maximumAge.setMetric(TimeMetrics.fromString("Hour"));

    maximumAge.setUnits(10);

    parameters.setMaximumAge(maximumAge);

    TimeMetric responseTime = new TimeMetric();

    responseTime.setMetric(TimeMetrics.fromString("Hour"));

    responseTime.setUnits(1);

    parameters.setResponseTime(responseTime);

    DelayTolerance tolerance = DelayTolerance.fromString("NoDelay");

    parameters.setTolerance(tolerance);

    org.csapi.schema.parlayx.terminal_location.v2_2.local.GetLocationResponse response =

    port.getLocation(parameters);

    org.csapi.schema.parlayx.terminal_location.v2_2.LocationInfo result =

    response.getResult();

    System.out.println("accuracy : " + result.getAccuracy());

    System.out.println("altitude : " + result.getAltitude().floatValue());

    System.out.println("latitude : " + result.getLatitude());

    System.out.println("longitude : " + result.getLongitude());

    System.out.println("timestamp : " + result.getTimestamp());