This chapter describes the Oracle Communications Services Gatekeeper interfaces in the supported Parlay X 2.1 facades and contains information specific to Services Gatekeeper. For detailed descriptions of the interfaces, methods, and parameters, see the ETSI OSA Parlay X website for links to the specifications:
http://www.etsi.org/deliver/etsi_es/202300_202399/20239102/01.02.01_60/es_20239102v010201p.pdf
This interface is compliant with 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).
The endpoint for the ThirdPartyCall interface is: http://host:port/parlayx21/third_party_call/ThirdPartyCall
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Sets up a call between two parties.
Displays information about a call.
Ends a call.
Cancels a call setup procedure.
See General Error Codes.
This set of interfaces is compliant with 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).
This interface is implemented by an application, and the consumer of this interface is Services Gatekeeper. The Web services Description Language (WSDL) file 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 are the host name and port of the system on which Services Gatekeeper is installed.
Services Gatekeeper calls this method, which is implemented by an application, when the called party is busy.
Services Gatekeeper calls this method, which is implemented by an application, when the called party is not reachable.
The CallNotification interface is implemented by an application, and the consumer of this interface is 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
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Services Gatekeeper calls this method, which is implemented by an application, when the called party is busy.
Services Gatekeeper calls this method, which is implemented by an application, when the called party is not reachable.
The endpoint for the CallNotificationManager interface is: http://host:port/parlayx21/call_notification/CallNotificationManager
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Starts a subscription for call notifications.
Stops a subscription for call notifications.
The endpoint for the CallDirectionManager interface is: http://host:port/parlayx21/call_notification/CallDirectionManager
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Starts a subscription for call direction notifications.
Stops a subscription for call direction notifications.
See General Error Codes.
This set of interfaces is compliant with 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).
The endpoint for the SendSms interface is: http://host:port/parlayx21/sms/SendSms
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
If a backwards-compatible communication service is used:
The senderAddress parameter is either of the format tel:mailbox ID\mailbox password\Sender name or just sender name depending on how the application was provisioned in Services Gatekeeper.
The priority parameter is not supported.
Sends an SMS to one or more destinations.
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 is converted to SmartMessaging format, the image cannot be larger than 72x14 pixels.
If the logo 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.
Sends an SMS Ringtone to one or more destinations.
Ringtones can be in any of these formats:
RTX
SmartMessaging
EMS (iMelody)
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 Services Gatekeeper and the delivery status is not stored. If the delivery status is stored in Services Gatekeeper, it is stored for a configurable period.
This SmsNotification interface is implemented by an application, and the consumer of this interface is Services Gatekeeper. The WSDL file 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 are the host name and port of the system on which Services Gatekeeper is installed.
Sends an SMS that is received by 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 Services Gatekeeper.
Shortcode translation, if appropriate, is applied.
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.
The endpoint for the ReceiveSms interface is: http://host:port/parlayx21/sms/ReceiveSms
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Gets messages that have been received by Services Gatekeeper. The SMS messages are retrieved using a registrationIdentifier used when the notification was registered using a provisioning step in Services Gatekeeper.
The maximum number of messages returned for one operation is controlled by the maxBatchSize attrribute of the SmsMBean. The default is 20. If you attempt to exceed the maxBatchSize value for an operation, Services Gatekeeper throws a policy exception. For details see SmsMBean in the ”All Classes” section of the Services Gatekeeper OAM Java API Reference documentation.
The endpoint for the SmsNotificationManager interface is: http://host:port/parlayx21/sms/SmsNotificationManager
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Initiates notifications to the application for a given service activation number and criteria.
Note:
A Service activation number may be provisioned to handle a range of numbers using short code translations.Note:
The equivalent of this operation may have been performed as an off-line provisioning step by the Services Gatekeeper administrator.Ends a previously started notification.
With Split and Submit Messaging enabled, short messages addressed to many recipients are split into multiple individually-addressed requests by Services Gatekeeper. For information on enabling Split and Submit Messaging, see the discussion on supportBulkRequest in Services Gatekeeper System Administrator's Guide. For an overview of Split and Submit Messaging, see Services Gatekeeper Communication Service Reference Guide.
You can provide custom content to be sent to particular addresses. To do this, specify the per-address content in a content attribute for each message element with custom content. Include an xparam DifferentContentForSingleAddressInBulk, set to true, with the SOAP request.
Each address in the bulk SMS request must have a content attribute if DifferentContentForSingleAddressInBulk is set to true.
For example:
<?xml version="1.0" encoding="UTF-8"?> <messages> <message address="1100" content="1100abc"/> <message address="1200" content="1200abc"/> <message address="2100" content="2100abc"/> <message address="3100" content="3100abc"/> </messages>
The schema is as follows:
<?xml version="1.0"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.oracle.com/ocsg/51/"
xmlns:wlng="http://www.oracle.com/ocsg/51/">
<xsd:complexType name="messages">
<xsd:sequence>
<xsd:element name="message" type="wlng:message" minOccurs="1"
maxOccurs="unbounded"/>
</xsd:complexType>
<xsd:complexType name="message">
<xsd:attribute name="address" type="xsd:string" use="required"/>
<xsd:attribute name="address" type="xsd:string" use="required"/>
<xsd:attribute name="content" type="xsd:string" use="required"/>
</xsd:complexType>
</xsd:schema>
Table 27-1 Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0002 |
n/a |
Invalid input value for message part %1 Log message: Parse bulk SMS XML message content failed: This log message indicates that xparam Bulk SMS XML message cannot find content for address dest_address: This log message indicates that xparam |
See General Error Codes.
This set of interfaces is compliant with 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).
See "Sending Custom Message Content for Split and Submit Messaging Requests" for instructions on how to split messages into multiple individually-addressed requests
The endpoint for the SendMessage interface is: http://host:port/parlayx21/multimedia_messaging/SendMessage
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Sends a multimedia message. The content of the message is sent as a SOAP attachment. Sending as email is not supported.
Table 27-2 Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0001 |
WNG-000002 |
Internal problem in Services Gatekeeper. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
MMS-000001 |
Internal problem in Services Gatekeeper. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
MMS-000002 |
Internal problem in Services Gatekeeper. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
MMS-000003 |
Address is utilizing an unsupported address type. |
|
SVC0001 |
MMS-000005 |
Message could not be delivered to MMSC. |
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 Services Gatekeeper and the delivery status is not stored. If the delivery status is stored in Services Gatekeeper, it is stored for a configurable period.
Note:
Storing delivery status for an MMS is configurable in Services Gatekeeper.The endpoint for this interface is: http://host:port/parlayx21/multimedia_messaging/ReceiveMessage
Where the values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Polls Services Gatekeeper for received messages.
The registrationIdentifier is required. Received message are stored in Services Gatekeeper only for a configurable period.
Gets a specific message that was received by Services Gatekeeper and belongs to the application.
This interface is implemented by an application, and the consumer of this interface is 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 are the host name and port of the system on which Services Gatekeeper is installed.
Sends a notification to an application that an MMS destined for the application is received by Services Gatekeeper.
When an application is notified about an incoming MMS message by an asynchronous call to NotifyMessageReception from Services Gatekeeper, the application receives a MessageReference structure containing information about the message.
If the MMS message contains only pure text, the <message> element of the MessageReference structure contains the entire text content as an ASCII string, and the message is not stored in Services Gatekeeper. If the message contains any content that is not pure text, such as an image, sound or video, the MessageReference structure does not include a <message> element, but instead includes a <messageIdentifer> element that contains a reference to the message stored in Services Gatekeeper. For more information about the MessageReference structure, see the Parlay X Web services Part 5: Multimedia Messaging specification.
Sends a notification to an application that a previously sent MMS has been delivered to its destination.
Note:
Supporting delivery notifications is optional for Services Gatekeeper.The endpoint for the MessageNotificationManager interface is: http://host:port/parlayx21/multimedia_messaging/MessageNotificationManager
Where the values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Initiates notifications to the application for a given service activation number and criteria.
Table 27-6 StartMessageNotification Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0001 |
WNG-000002 |
Internal problem in Services Gatekeeper. Contact your Services Gatekeeper administrator. |
Note:
A service activation number may be provisioned to handle a range of numbers using short code translations.Note:
The equivalent to this operation may have been performed as an off-line provisioning step by the Services Gatekeeper administrator.Ends a previously started notification.
See General Error Codes.
This set of interfaces is compliant with ETSI ES 202 391-8 V1.2.1, Open Service Access (OSA); Parlay X Web services; Part 8: Terminal Status (Parlay X 2).
The endpoint for the TerminalStatus interface is:
http://host:port/parlayx21/terminal_status/TerminalStatus
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
The endpoint for the TerminalStatusNotificationManager interface is:
http://host:port/parlayx21/terminal_status/TerminalStatusNotificationManager
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
The endpoint for the TerminalNotification interface is provided by the calling application.
Supplies the terminal status to the application. The status is sent by the Terminal Status communication service to the application.
See the General Exceptions and General Error Codes sections for most error information. Table 27-9 includes additional diagnostic information specific to the Terminal Status/MAP plug-in.
Table 27-9 Terminal Status Exception and Error Code Information
| Exception | Error code | Reason/Action |
|---|---|---|
|
POL0002 |
N/A |
A Terminal Status request was sent using a criteria of |
|
POL0003 |
N/A |
The number of Terminal Server addresses sent exceeded the |
|
POL0004 |
N/A |
An unlimited number of Terminal Status requests were sent, but the SLA |
|
POL0005 |
N/A |
The number of Terminal Status requests exceeded the |
|
POL0009 |
N/A |
The Terminal Status request frequency violated the |
|
POL0200 |
N/A |
Busy criteria not supported. |
|
SVC0001 |
MAP-000001 |
The Terminal Status communication service could not encode the |
|
SVC0001 |
SS7API-000001 |
The SS7 API failed to build and send a message to the SS7 stack. This usually means that the Terminal Status plug-in could not bind with the stack, or the bind was lost. Make sure that the stack is running and that the |
|
SVC0001 |
SS7-000001 |
The SS7 stack received no answer or an incorrect answer. The SS7 stack did not send an |
This set of interfaces is compliant with 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).
The Parlay X 2.1 Terminal Location specification complies with the ISO 6709 [7] specification, specifying decimal values for longitude and latitude locations. The decimals representing longitude are floating point numbers in the range -90.0000 to +90.0000. Positive values for locations North of the equator and negative values for South of the equator. Longitude values are floating point numbers in the range -180.0000 to +180.0000. Positive values are East of the prime meridian, and negative values are West of the prime meridian.
It is important to understand that Services Gatekeeper rounds these floating point values to 8 significant digits. For example, if Services Gatekeeper receives messages with these longitude (X) and latitude (Y) values from the network:
"latitude":"12.34567890", "longitude":"123.4567890",
Services Gatekeeper reports these rounded values to the application:
<X> 12.345679 </X> <Y> 123.45679 </Y>
The endpoint for the TerminalLocation interface is: http://host:port/parlayx21/terminal_location/TerminalLocation
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Gets the location of a terminal.
Table 27-10 Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0001 |
TL-000007 |
There is a communication problems between Services Gatekeeper and the network node. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000010 |
There is a communication problem between Services Gatekeeper and the network node, and Services Gatekeeper was unable to interpret the response. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000009 |
No location data was received from network. |
|
SVC0001 |
TL-000011 |
An unknown error was received from the network. |
|
SVC0002 |
N/A |
An invalid parameter was included in the terminal status request. |
|
SVC0200 |
N/A |
The location accuracy is invalid. |
|
POL0001 |
N/A |
General policy error. |
|
POL0002 |
N/A |
Privacy error. |
|
POL0230 |
N/A |
The requested accuracy is not supported. |
Gets the distance from a certain point to the location of a terminal.
Table 27-11 Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0001 |
TL-000007 |
There is a communication problems between Services Gatekeeper and the network node. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000010 |
There is a communication problem between Services Gatekeeper and the network node, and Services Gatekeeper was unable to interpret the response. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000009 |
No location data was received from the network. |
|
SVC0001 |
TL-000011 |
An unknown error was received from the network. |
|
SVC0002 |
N/A |
An invalid parameter was included in the terminal status request. |
|
SVC0200 |
N/A |
The location accuracy is invalid. |
|
POL0001 |
N/A |
General policy error. |
|
POL0002 |
N/A |
Privacy error. |
|
POL0230 |
N/A |
The requested accuracy is not supported. |
Gets the location for one or more terminals.
Table 27-12 Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0001 |
TL-000007 |
There is a communication problems between Services Gatekeeper and the network node. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000010 |
There is a communication problem between Services Gatekeeper and the network node, and Services Gatekeeper was unable to interpret the response. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000009 |
No location data was received from the network. |
|
SVC0001 |
TL-000011 |
An unknown error was received from the network. |
|
SVC0002 |
N/A |
An invalid parameter was included in the terminal status request. |
|
SVC0004 |
N/A |
No valid addresses were passed in on the request. |
|
SVC0200 |
N/A |
The location accuracy is invalid. |
|
POL0001 |
N/A |
General policy error. |
|
POL0002 |
N/A |
Privacy error. |
|
POL0230 |
N/A |
The requested accuracy is not supported. |
The endpoint for the TerminalLocationNotificationManager interface is: http://host:port/parlayx21/terminal_location/TerminalLocationNotificationManager
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Initiates location notifications to the application when one or more terminals change their location according to a criteria.
Table 27-13 Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0001 |
TL-000003 |
Unable to start the geographical notification due to a network error. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000004 |
Unable to start geographical notification due to an internal error. Contact your Services Gatekeeper administrator. |
|
SVC0002 |
N/A |
The request included an invalid parameter. |
|
SVC0004 |
N/A |
The request did not include any valid addresses. |
|
SVC0005 |
N/A |
The correlator used already exists. |
|
POL0001 |
N/A |
General policy error. |
Initiates location notifications to the application on a periodic basis.
Table 27-14 Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0001 |
TL-000005 |
Unable to start periodic notification due to a network error. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000006 |
Unable to start periodic notification due to an internal error. Contact your Services Gatekeeper administrator. |
|
SVC0002 |
N/A |
The request included an invalid parameter. |
|
SVC0004 |
N/A |
The request did not include any valid addresses. |
|
SVC0005 |
N/A |
The correlator used already exists. |
|
POL0001 |
N/A |
General policy error. |
Ends a previously started notification.
Table 27-15 Exceptions and Error Codes
| Exception | Error code | Reason/Action |
|---|---|---|
|
SVC0001 |
TL-000001 |
Unable to start geographical notification due to a network error. Contact your Services Gatekeeper administrator. |
|
SVC0001 |
TL-000002 |
Unable to start geographical notification due to an internal error. Contact your Services Gatekeeper administrator. |
|
SVC0002 |
N/A |
The request included an invalid parameter. |
|
POL0001 |
N/A |
General policy error. |
The TerminalLocationNotification interface is implemented by an application, and the consumer of this interface is 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 are the host name and port of the system on which Services Gatekeeper is installed.
This set of interfaces is compliant with ETSI ES 202 391-11 V1.2.1 (2006-12) Open Service Access (OSA); Parlay X Web services; Part 11: Audio Call (Parlay X 2).
The endpoint for the PlayAudio interface is: http://host:port/parlayx21/audio_call/AudioCall.
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
This set of interfaces is compliant with ETSI ES 202 391-14 V1.2.1 (2006-12), Open Service Access (OSA); Parlay X Web services; Part 14: Presence (Parlay X 2).
The endpoint for the PresenceConsumer interface is: http://host:port//parlayx21/presence/PresenceConsumer
Where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
Requests a subscription for presence information about a presentity.
For the parameter presentity, only SIP URI can be used. Group-URI is not supported.
Gets presence information about a presentity.
For the parameter presentity, only SIP URI can be used. Group-URI is not supported.
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.
Ends a previously started notification.
The PresenceNotification interface is implemented by an application, and the consumer of this interface is 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 are the host name and port of the system on which Services Gatekeeper is installed.
Notifies an application that the presentity has handled the request for presence information.
Notifies an application that the subscription for presence information has ended.
The endpoint for the PresenceSupplier interface is: http://host:port/parlayx21/presence/PresenceSupplier where values for host and port are the host name and port of the system on which Services Gatekeeper is installed.
The Presence Supplier interface requires that a presence server be available in the underlying network. Services Gatekeeper interacts with this server to provide this functionality to the application.
By default, Services Gatekeeper maps a presentity URI parameter to the client's Application Instance ID. This information is required to interact with the network and Parlay X 2.1 does not provide it by default.
The application can override the default presentity URI value by using ”wlng.presence.parlay21.presentity.uri” as the key and the desired URI for the value in value = $the_desired_URI. See "Understanding Parameter Tunneling" for more information.
Publishes presence data about a presentity.
Note:
The presence server in the network must support the "Publication of Partial Presence Information" IETF standard for this functionality to work. For the standards document, seehttp://tools.ietf.org/html/draft-ietf-simple-partial-publish-07#page-4 Gets a list of new watchers who wish to subscribe to this presentity's data.
Note:
The presence server in the network must supporthttp://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.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.
Returns an array of the watchers that are subscribed to the presentity's data.
Note:
The presence server in the network must support these IETF standards found at the IETF website for this feature to work: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) .
Not supported.
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.
After an application starts notification, the notification persists. If an application has started a notification and destroys the session, the notification remains registered and matching notifications are sent to the application when it connects to Services Gatekeeper.
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
Policy Exceptions are thrown when a policy has been violated, including violations of a service level agreements. The following general Policy Exceptions 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".
The following are general error codes for SVC0001: Service error:
Null sessionID (loginTicket) expired.
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.
MAP-000001 The Terminal Status plug-in failed to encode the anyTimeInterrorgation MAP message.
MMS-000001 Unable to perform action. Network error. Check that the incoming Parlay X address request is correct and that the NetworkSelection for the supplied address has the correct MAPApplicationContext and MAPDialogueAS values
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, which includes the status code and the status text in the following format: MMS-000005:StatusCode:StatusText.
For example, if the MMSC response were:
<rel:Status>
<rel:StatusCode>4000</rel:StatusCode>
<rel:StatusText>Hello</rel:StatusText>
</rel:Status>
the SVC0001 ServiceException error code would be:
"MMS-000005:4000:Hello".
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 Services Gatekeeper.
PLC-000001 Internal policy engine 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.
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.
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.
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.
SMS-000006 Could not send message. Message was not accepted by the network.
The status code and the status text are in the following format: SMS-000006:CommandStatus:Description
For example, if the SMSC commandstatus response is:
0x0000000B(ESME_RINVDSTADR)
the SVC0001 ServiceException error code is:
"SMS-000006:11:Invalid Dest Addr".
The description of the command status is taken from the SMPP Specification v3.4. If the command status in the response from the SMSC is not explicitly described in the SMPP Specification, the text of the error is No description available for CommandStatus.
SS7API-000001 The SS7 server failed to build and send the message to the SS7 stack. Make sure that the stack is running and that the CpUserId and SS7 host/port/instance are correct.
SS7-000001 No answer or an incorrect answer received from the SS7 stack.
TL-000001 Unable to end notification because of a network error.
TL-000002 Unable to end notification because of an internal error.
TL- 000003 Unable to start geographical notification because of a network error.
TL-000004 Unable to start geographical notification because of an internal error.
TL-000005 Unable to start periodic notification because of a network error.
TL-000006 Unable to start periodic notification because of an internal error.
TL-000007 Unable to get location because of a network error.
TL-000008 Unable to get location because of an internal error.
TL-000009 Unable to get location because no data was found.
TL-000010 Failed to parse response because of an internal error.
TL-000011 Failed to get location information because the MLP server returned an error.
TPC-000001 Unable to retrieve configuration because of an internal error.
TS-000001 Communication problems between Services Gatekeeper and the network node. Contact your Services Gatekeeper administrator. The GroupRequestTimeout attribute may be too low.
TS-000002 Could not find a network service route to match the address. Validate the network selection routes. You may want to add a default route (expression=DEFAULT) to capture any addresses that do not matched any other expression.
TS-000003 No result returned from a getStatusForGroup query. Update getGroupRequestTimeout to an appropriate value and check the status of network connection
TS-000004 Did not find the correlator when sending an end-status notification. The value of correlator in the endNotification request is incorrect, or the notification has already been terminated by the network.
TS-000005 Could not initialize the object. Check the instancemap configuration file.
TS-000006 Failed to access storage. Check the status of the storage service and database.
WNG-000000 No error.
WNG-000001 Unknown error.
WNG-000002 Storage service error.
The following code examples illustrate how to use the Parlay X 2.1 interfaces.
This is an SMS sending 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);
This is an example of how to use startSmsNotification.
Example 27-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);
This example shows how to poll for SMS messages using getReceivedSms.
Example 27-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());
}
}
This is an MMS sending example.
Example 27-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);
This is shows polling for a received MMS.
Example 27-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);
}
}
This example shows how to get the location of a terminal.
Example 27-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.nfo 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());