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.

StopCallDirectionNotification

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:

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.

Parlay X 2.1 Part 5: Multimedia messaging

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.

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.

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.