|
|
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.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
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.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
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 traffic path 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 provisioning step in Network Gatekeeper.
Shortcode translation 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.
If a backwards-compatible traffic path is used:
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. |
If a backwards-compatible traffic path is used:
Ends a previously started notification.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
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.
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 Network Gatekeeper.
The priority parameter 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. I 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. The priority parameter is not supported.
The format of the parameter registrationIdentifier is tel:<mailbox ID>\<mailbox password>
Mailbox ID and password are defined as a part of the provisioning steps by the Network Gatekeeper administrator.
"tel:50000\apassword"
Received message are stored in Network Gatekeeper only for a configurable period of time.
Gets a specific message that was received by WLNG 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.
The format of the parameter MessageServiceActivationNumber is
tel:<mailbox ID>;mboxPwd=<mailbox password>
Mailbox ID and password are provisioned by the Network Gatekeeper administrator.
"tel:50000;mboxPwd=apassword"
Ends a previously started notification.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
This set of interfaces is compliant to ETSI ES 202 391-6 V1.2.1 (2006-12), Open Service Access (OSA); Parlay X Web Services; Part 6: Payment (Parlay X 2).
Network Gatekeeper does not manage Payment operations, it passes on the requests to a network node that performs these operations.
The endpoint for this interface is: http://<host>:<port>/parlayx21/payment/AmountCharging
Where the values for host and port depend on the Network Gatekeeper deployment.
Charges an amount from an account.
Refunds an amount to an account.
The endpoint for this interface is: http://<host>:<port>/parlayx21/payment/VolumeCharging
Where the values for host and port depend on the Network Gatekeeper deployment.
Charges a volume from an account.
Converts a volume to an amount.
Refunds a volume to an account.
The endpoint for this interface is: http://<host>:<port>/parlayx21/payment/ReserveAmountCharging
Where the values for host and port depend on the Network Gatekeeper deployment.
Reserves an additional amount.
The endpoint for this interface is: http://<host>:<port>/parlayx21/payment/ReserveVolumeCharging
Where the values for host and port depend on the Network Gatekeeper deployment.
Converts a given volume to an amount.
Reserves an additional volume.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
This set of interfaces is compliant to ETSI ES 202 391-8 V1.2.1 (2006-12), Open Service Access (OSA); Parlay X Web Services; Part 8: Terminal Status (Parlay X 2).
Network Gatekeeper does not hold status information, it passes on the requests to a network node that performs these operations.
The endpoint for this interface is: http://<host>:<port>//parlayx21/terminal_status/TerminalStatus
Where values for host and port depend on the Network Gatekeeper deployment.
Gets the status of a terminal.
Gets the status of a group of terminals.
The endpoint for this interface is: http://<host>:<port>/parlayx21/terminal_status/TerminalStatusNotificationManager
Where the values for host and port depend on the Network Gatekeeper deployment.
Initiates status notifications to the application for a given address and criteria. Only status changes matching the criteria are notified to the application.
Group URIs are not supported in the parameter Addresses.
The parameters Frequency and Duration are not supported.
When the number of notifications is equal to the number given in parameter Count, the subscription for notifications is removed.
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_status/wsdls/parlayx_terminal_status_notification_interface_2_2.wsdl
http://<host>:<port>/parlayx21/terminal_status/wsdls/parlayx_terminal_status_notification_service_2_2.wsdl
http://<host>:<port>/parlayx21/terminal_status/wsdls/parlayx_terminal_status_types_2_2.xsd
Where values for host and port depend on the Network Gatekeeper deployment.
Notifies an application about a change of status for a terminal.
Notifies an application that the subscription for status notifications was cancelled by network Gatekeeper.
Notifies an application that no more status notifications are being sent to the application.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
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.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
This set of interfaces is compliant to ETSI ES 202 391-10 V1.2.1 (2006-12), Open Service Access (OSA); Parlay X Web Services; Part 10: Call Handling (Parlay X 2).
The endpoint for this interface is: http://<host>:<port>/parlayx21/call_handling/CallHandling
Where values for host and port depend on the Network Gatekeeper deployment.
Sets call handling rules for the destination of a call.
Sets call handling rules for multiple destinations of a call.
Gets call handling rules for a given destination.
Clears all call handling rules for a the given destinations.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
This set of interfaces is compliant to 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 this interface is: http://<host>:<port>/parlayx21/audio_call/AudioCall
Where values for host and port depend on the Network Gatekeeper deployment.
Plays a message to the given destination address. The message is given as a text.
Plays a message to the given destination address. The message is given as an audio file.
Plays a message to the given destination address. The message is given as an VoiceXML file.
Gets the status of a message, that is, if the message is currently being played, if it is has finished playing and more.
Cancel or stops the playing of the message.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
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.
The following error codes are defined for SVC0001: Service error:
The following error codes are defined for POL0001: Policy error:
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 or logs out, the notification is still registered and matching notifications are sent to the application when it connects to Network Gatekeeper.
The following are general error codes for SVC0001: Service error:
The following are general error codes for POL0001: Policy error:
Below are some code examples that illustrate how to use the Parlay X 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 on 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 on 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 on 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 on 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());
|
