|
|
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.
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).
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.
Sets up a call between two parties.
Displays information about a call.
Cancels a call setup procedure.
See General error codes.
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).
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.
Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party is busy.
Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party is not reachable.
Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party does not answer.
Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, prior to call setup.
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
Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party is busy.
Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party is not reachable.
Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, when the called party does not answer.
Oracle Communications Services Gatekeeper calls this method, which is implemented by an application, prior to call setup.
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.
Starts a subscription for call notifications.
Stops a subscription for call notifications.
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.
Starts a subscription for call direction notifications.
Stops a subscription for call direction notifications.
See General error codes.
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).
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:
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:
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:
Sends an SMS Ringtone to one or more destinations.
Ringtones can be in any of these formats:
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.
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.
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.
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 this interface is: http://<host>:<port>/parlayx21/sms/ReceiveSms
Where values for host and port depend on the Oracle Communications Services Gatekeeper deployment.
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.
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.
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. |
Ends a previously started notification.
See General error codes.
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).
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.
Sends a multimedia message. The content of the message is sent as a SOAP attachment. E-mail is not supported.
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. |
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.
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.
Gets a specific message that was received by Oracle Communications Services Gatekeeper and belongs to the application.
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.
Sends a notification to an application that an MMS destined for the application is received by Oracle Communications Services Gatekeeper.
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. |
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.
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. |
Ends a previously started notification.
See General error codes.
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).
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.
Gets the location for a terminal.
Gets the distance from a certain point to the location of a terminal.
Gets the location for one or more terminals.
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.
Initiates location notifications to the application when one or more terminal changes their location according to a criteria.
Initiates location notifications to the application on a periodic basis.
Ends a previously started notification.
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.
Notifies an application about a change of location for a terminal.
Notifies an application that the subscription for location notifications was cancelled by Oracle Communications Services Gatekeeper.
Notifies an application that no more location notifications are being sent to the application.
See General error codes.
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).
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.
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.
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.
Notifies an application about a change of presence attributes for a presentity.
Notifies an application that no more notifications will be sent to the application.
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 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. |
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. |
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. |
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 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. |
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.
See General error codes.
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.
This section describes the exception handling for the Parlay X 2.1 interfaces.
These exception types are defined:
Service Exceptions are related to the operation of the service itself. The following exceptions are general:
PolicyExceptions are thrown when a policy has been violated, including violations of a service level agreements. The following general PolicyExceptions are defined:
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:
Below are some code examples that illustrate how to use the Parlay X 2.1 interfaces.
Below is an example of sending an SMS.
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);Below is an example of using startSmsNotification.
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);
Below is an example of polling for SMSes using getReceivedSms.
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());
}
}
Below is an example of sending an MMS.
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);Below is an example of polling for a received MMS.
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);
}
}
Below is an example of getting the location of a terminal.
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());
|