This chapter describes the supported Parlay X 2.1 interfaces and contains information that is specific for Network Gatekeeper, and not found in the specifications. For detailed descriptions of the interfaces, methods and parameters, refer to the specifications.
See http://parlay.org/en/specifications/pxws.asp 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 Network 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 Network 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 Network Gatekeeper deployment.
Network Gatekeeper calls this method, which is implemented by an application, when the called party is busy.
Network Gatekeeper calls this method, which is implemented by an application, when the called party is not reachable.
Network Gatekeeper calls this method, which is implemented by an application, when the called party does not answer.
Network 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 Network 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
Network Gatekeeper calls this method, which is implemented by an application, when the called party is busy.
Network Gatekeeper calls this method, which is implemented by an application, when the called party is not reachable.
Network Gatekeeper calls this method, which is implemented by an application, when the called party does not answer.
Network 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 Network 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 Network 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 Network 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 Network Gatekeeper and the delivery status is not stored. If the delivery status is stored in Network Gatekeeper, it is stored for a configurable period of time.
This interface is implemented by an application, and the consumer of this interface is Network 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 Network Gatekeeper deployment.
Sends an SMS that is received by Network 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 Network 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 Network Gatekeeper deployment.
Gets messages that have been received by Network Gatekeeper. The SMSs are fetched using a registrationIdentifier used when the notification was registered using a provisioning step in Network Gatekeeper.
The endpoint for this interface is: http://<host>:<port>/parlayx21/sms/SmsNotificationManager
Where values for host and port depend on the Network 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 Network 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 Network 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 Network Gatekeeper and the delivery status is not stored. If the delivery status is stored in Network Gatekeeper, it is stored for a configurable period of time.
Note: | Network 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 Network Gatekeeper deployment.
Polls Network Gatekeeper for received messages.
The registrationIdentifier is required. Received message are stored in Network Gatekeeper only for a configurable period of time.
Gets a specific message that was received by Network Gatekeeper and belongs to the application.
This interface is implemented by an application, and the consumer of this interface is Network 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 Network Gatekeeper deployment.
Sends a notification to an application that an MMS destined for the application is received by Network Gatekeeper.
Sends a notification to an application that a previously sent MMS has been delivered to its destination.
Note: | Network 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 Network 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 Network 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 Network 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 Network 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 Network 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 Network 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 network 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 Network Gatekeeper deployment.
Subscription to get presence information about a presentity.
For the parameter presentity, only SIP URI can be used. Group-URI is not supported
Get 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 Network 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 Network 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.
This interface is not supported.
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 Network Gatekeeper.
This section describes the exception handling for the Parlay X 2.1 interfaces.
These exception types are defined:
Service Exception 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;mboxPwd=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());