API Description for Extended Web Services

Call Control

The following sections provide detailed information about the Call Control service capability:

• Web Service
• Address expressions
• Listener interface
• Network initiated call listener interface

 

---

Web Service

The call control Web Service provides an application with functions for call routing, call management, and call leg management. It also provides functions for registering listeners to application initiated and network initiated call sessions.

The service supports establishment of multiparty calls if supported by the underlying platform. Two main usage scenarios are identified; application initiated and network initiated calls.

This section covers application initiated calls.

When a call session has been created, a callTicket is returned. This callTicket is used to identify a given call session and manipulate it.

The following gives an outline of the the Call Control Web Service:

• Create a call
• Add and remove participants in the call
• Hang up all participants and end the call
• Get the originator of the call
• List participants in the call

addListener

Adds a call listener to a call-session initiated by an application. The listener must be a Web Service implemented by the application. The listener receives callbacks with information on the status of the call and error events.

Table 4-1 addListener(callTicket, endpoint)

Parameter Name	Type	Description
Input
callTicket	xsd:string	Identifier for the call as retrieved when createCall or createEmptyCall was invoked.
endpoint	xsd:string	The URL to the Web Service that implements the listener interface. See Listener interface. An example is http://www.acompany.com/axis/services/CallListener
Returns
Void.
Exceptions
CallException		See CallException.
GeneralException		See GeneralException.

addNetworkCallListener

Adds a call listener to call-session initiated from the network. The listener must be a Web Service implemented by the application.

The listener is triggered when:

• the originator address matches the criteria define in the aPartyAddressExpression parameter.
• the destination address matches the criteria define in the bPartyAddressExpression parameter.
• the status of the call matches the criterias given in the eventCriteria parameter.

The listener receives callbacks with information on A-number, B-number and so on in the methods processCallStatusEvent and processCallErrorEvent.

If there are more than one listeners registered for identical criteria, and those listeners are registered from the same application, the listener will be added to a High Availability and Load Balancing list. This means that the network initiated calls matching this criteria will be distributed using a round robin algorithm between the listeners with identical criteria.

If the above is false, and there already is a listener registered for an address that overlaps this listener, an exception is raised.

Table 4-2 addNetworkCallListener(endpoint, aPartyAddressExpression, bPartyAddressExpression, eventCriteria, serviceCode, requesterID)

Parameter Name	Type	Description
Input
endpoint	xsd:string	The URL to the Web Service that implements the listener interface. See Listener interface. An example is http://www.acompany.com/axis/services/CallListener
aPartyAddressExpression	xsd:string	Originator address in URI format (tel:<address>). See Address expressions for information on format.
bPartyAddressExpression	xsd:string	Originator address in URI format (tel:<address>). See Address expressions for information on format.
eventCriteria	ArrayOfCallEventCriteria	See ArrayOfCallEventCriteria.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
addNetworkCallListenerReturn	xsd:string	Ticket identifying the listener.
Exceptions
CallException		See CallException.
GeneralException		See GeneralException.

addParticipant

Adds a new participant to an ongoing call. The application execution continues without waiting for the participant to answer. Notifications when the participant has answered comes in the Web Service defined and registered by the application, see addListener.

The ongoing call is identified by the parameter callTicket.

Table 4-3 addParticipant(callTicket, participant, timeout)

Parameter Name	Type	Description
Input
callTicket	xsd:string	Ticket retrieved when the call was created. See createCall or createEmptyCall.
participant	xsd:string	Address to the new participant in URI format (tel:<address>). See Address expressions for information on format.
timeout	xsd:int	The time in seconds to wait for an answer from participant.
Returns
Void
Exceptions
CallException		See CallException. This exception is raised if the participant could not be added.
GeneralException		See GeneralException.

addParticipantWait

Adds a new participant to an ongoing call. The appplication execution holds until the participant answers or until the timeout expires.

The ongoing call is identified by the parameter callTicket.

Table 4-4 addParticipantWait(callTicket, participant, timeout)

Parameter Name	Type	Description
Returns
callTicket	xsd:string	Ticket retrieved when the call was created. See createCall or createEmptyCall.
participant	xsd:string	Address to the new participant in URI format (tel:<address>). See Address expressions for information on format.
timeout	xsd:int	The time in seconds to wait for an answer from participant.
Returns
Void.
Exceptions
CallException		See CallException. This exception is raised if the participant could not be added.
GeneralException		See GeneralException.

createCall

Create a call session with an originator. The originator is identified and the application execution holds until the originator goes off-hook or a timer expires.

Table 4-5 createCall(originator, timeout, serviceCode, requesterID)

Parameter Name	Type	Description
Input
originator	xsd:string	Address to the originator in URI format (tel:<address>). See Address expressions for information on format.
timeout	xsd:int	The time in seconds to wait for the originator to go off-hook.
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
createCallReturn	xsd:string	A CallTicket identifying the call.
Exceptions
CallException		See CallException.
GeneralException		See GeneralException.

createEmptyCall

Create a call session without an originator.

Table 4-6 createEmptyCall(serviceCode, requesterID)

Parameter Name	Type	Description
Input
serviceCode	xsd:string	Used for charging purposes. Defined by the operator.
requesterID	xsd:string	The application ID as given by the operator.
Returns
createEmptyCallReturn	xsd:string	A CallTicket identifying the call.
Exceptions
CallException		See CallException.This exception is raised when the underlying platform filed to create a call object.
GeneralException		See GeneralException.

deassign

When a call is deassigned the application will no longer receive events regarding call progress and the callTicket cannot be used for further processing of the call.

The control of the call is handed over to the underlying network.

Table 4-7 deassign(callTicket)

Parameter Name	Type	Description
Input
callTicket	xsd:string	The CallTicket identifying the call.
Returns
Void.
Exceptions
CallException		See CallException. This exception is raised when the call could be deassigned.
GeneralException		See GeneralException.

end

Hangs up all the participants and ends the call.

Table 4-8 end(callTicket)

Parameter Name	Type	Description
Returns
callTicket	xsd:string	The CallTicket identifying the call.
Returns
Void.
Exceptions
CallException		See CallException. This exception is raised when the call could not be ended.
GeneralException		See GeneralException.

getOriginator

Gets the owner, or originator of the call.

Table 4-9 getOriginator(callTicket)

Parameter Name	Type	Description
Input
callTicket	xsd:string	The CallTicket identifying the call.
Returns
getOriginatorReturn	xsd:string	Address of the originator of the call in URI format (tel:<address>). See Address expressions for information on format
Exceptions
CallException		See CallException. This exception is raised when the originator could not be retrieved.
GeneralException		See GeneralException.

getParticipants

Get a list of all participants in the call. The originator of the call is not included in the list.

Table 4-10 getParticipants(callTicket)

Parameter Name	Type	Description
Retuns
callTicket	xsd:string	The CallTicket identifying the call.
Returns
getParticipantsReturn	ArrayofxsdString	See ArrayOf_xsd_string. Array of addresses of the participants in the call. See Address expressions for information on format of each individual element in the array.
Exceptions
CallException		See CallException. This exception is raised when the participants could not be retrieved.
GeneralException		See GeneralException.

removeNetworkCallListener

Removes a previously registered network call listener. See addNetworkCallListener.

Table 4-11 removeNetworkCallListener(listenerTicket)

Parameter Name	Type	Description
Input
listenerTicket	xsd:string	The ticket retrieved when the network call listener was added.
Returns
Void.
Exceptions
CallException		See CallException.This exception is raised when the network call listener could not be removed.
GeneralException		See GeneralException.

removeParticipant

Remove an individual participant in an ongoing call session.

Table 4-12 removeParticipant(callTicket, participant)

Parameter Name	Type	Description
Input
callTicket	xsd:string	A CallTicket identifying the call.
participant	xsd:string	Address of the participant to remove from the call session in URI format (tel:<address>). See Address expressions for information on format.
Returns
Void.
Exceptions
CallException		See CallException.This exception is raised when the address of the participant could not be found among the participants in the call.
GeneralException		See GeneralException.

Exceptions

CallException

Exceptions of this type are raised when there are error conditions related to the call control Web Service. Other error conditions are reported using the exception GeneralExcepetion.

GeneralException

This exception is raised when the applications session has expired or there are communication problems with the underlying platform.

Complex data types

ArrayOfCallEventCriteria

Array of call criteria, see CallEventCriteria for information on the individual records in the array.

ArrayOf_xsd_string

Array of strings.

CallErrorCode

Defines errors that can occur during a call-setup or a call.

Enumeration with the following values:

• ERROR_UNKNOWN
• ERROR_NO_ANSWER
• ERROR_BUSY
• ERROR_NO_ROUTE
• ERROR_INVALID_ADDRESS
• ERROR_NO_LISTENER

CallEventCriteria

This data type contains two elements:

• event
• monitorMode

The event part of the CallEventCriteria type defines when and for which call-related events an application shall be notified.

The application can subscribe for notifications related to an originating number and a destination number, either one of them or a combination of both. Notifications can be subscribed for either when:

• An A-party calls a certain B-party.
• An A-party calls any B-party.
• Any A-party calls a certain B-party.
• An A-party goes off hook.

In addition, a set of notifications exists for events that occurs during a call:

• The B-party is busy.
• The B-party is not reachable.
• The B-party goes off-hook
• The B-party hangs up.
• No answer from the B-party.

See NetworkCallEvent for details on valid parameters for the event element.

The monitorMode part of the CallEventCriteria type defines how the application can affect a call. An application that has subscribed for notifications according to the criterias available are notified using either Interrupted mode or Notified mode. Calls that are triggered in Interrupted mode may affect the call, for example by routing the call to another destination or entering another participant in a multiparty conference call. Calls that are triggered in Notfication mode can only be surveilled. See CallMonitorMode for details on valid parameters for the monitorMode element.

CallMonitorMode

Enumeration with one of the following values:

• NOTIFY
• INTERRUPT

NetworkCallEvent

Defines valid call related events that an application can subscribe to during a call:

• ADDRESS_ANALYSED
• ORIGINATING_CALL_AUTHORISED
• TERMINATING_CALL_AUTHORISED
• ORIGINATING_CALL_ATTEMPT
• TERMINATING_CALL_ATTEMPT
• ALERTING
• BUSY
• NO_ANSWER
• CALL_FAILURE
• CALL_ANSWERED
• DISCONNECT

 

---

Address expressions

The following rules apply to the address expressions.

Two wildcards are allowed:

• *, which matches zero or more characters.
• ?, which matches exactly one character.

For E.164 addresses (normal telephone numbers), these wildcards are allowed at the beginning or the end of an address.

Examples of valid for E.164 addresses:

• "123" matches specific number.
• "123*" matches all numbers starting with 123 (including 123 itself).
• "123??*" matches all numbers starting with 123 and at least 5 digits long.
• "123???" matches all numbers starting with 123 and exactly 6 digits long.

The following address ranges are illegal:

• "1?3".
• "1*3"
• "?123*"
• "*"
• ""
• "*123*"
• "*123?"

Legal occurrences of the wildcards should be escaped by a '\' character. For example, to specify a '\' character, '\\' must be used.

 

---

Listener interface

The call control listener interface defines the methods that the underlying platform invokes on a Web Service that is implemented by an application. When an application performs asynchronous requests from the call control Web Service, the responses are delivered according to this interface.

callEnded

This method is invoked when the call session has ended. The call session ends when the last participant in the call goes on-hook, or when the application has ended the call. See method end.

Table 4-13 callEnded(callTicket)

Parameter Name	Type	Description
Input
callTicket	xsd:string	A CallTicket identifying the call.
Returns
Void.
Exceptions
-

deactivate

Used by the underlying system to inform the application that the call session identified by callTicket is no longer valid. The application can not use the call user session no more.

Table 4-14 deactivate(callTicket)

Parameter Name	Type	Description
Input
callTicket	xsd:string	A CallTicket identifying the call.
Returns
Void.
Exceptions
-

processCallErrorEvent

Errors related to call sessions are reported using this method.

Table 4-15 processCallErrorEvent(callTicket, error)

Parameter Name	Type	Description
Input
callTicket	xsd:string.	A CallTicket identifying the call.
error	CallErrorEvent	See CallErrorEvent. Type of error.
Returns
Void.
Exceptions
-

processCallStatusEvent

Table 4-16 processCallStatusEvent(callTicket, event)

Parameter Name	Type	Description
Input
callTicket	xsd:string	A CallTicket identifying the call.
event	CallStatusEvent	See CallStatusEvent. Type of event.
Returns
Void.
Exceptions
-

Complex data types

CallErrorEvent

Array of call error codes, see CallErrorCode for information on the individual records in the array.

CallErrorCode

Enumeration with one of the following values:

• ERROR_UNKNOWN
• ERROR_NO_ANSWER
• ERROR_BUSY
• ERROR_NO_ROUTE
• ERROR_INVALID_ADDRESS
• ERROR_NO_LISTENER

CallStatusEvent

Array of call status codes, see CallStatusCode for information on the individual records in the array.

CallStatusCode

Enumeration with one of the following values:

• EVENT_CALL_ANSWERED
• EVENT_CALL_HANGUP

 

---

Network initiated call listener interface

The network initiated call l listener interface defines the methods that the underlying platform invokes on a Web Service that is implemented by an application.

This listener interface is used for calls that originates from the network. Which phone numbers to survey are defined in the call control Web Service, see addNetworkCallListener.

deactivate

Used by the underlying system to inform the application that the call session identified by callTicket is no longer valid. The application can not use the call session no more.

Table 4-17 deactivate(listenerTicket)

Parameter Name	Type	Description
Input
listnenerTicket	xsd:string	A listenerTicket identifying the call. Retrieved when addNetworkCallListener was invoked.
Returns
Void.
Exceptions
-

processCall

Call session setup originating from the network, and supervised in monitor mode INTERRUPT, see addNetworkCallListener. These call sessions can be controlled by the call control Web Service.

Table 4-18 processCall(listenerTicket, callTicket, originator, participant, event)

Parameter Name	Type	Description
Input
listenerTicket	xsd:string	A listenerTicket identifying the call. Retrieved when addNetworkCallListener was invoked.
callTicket	xsd:string	A callTicket identifying the call. Used to control the call session using the call control Web Service.
originator	xsd:string	The address of the originator of the call in URI format (tel:<address>).
participant	xsd:string	The address of the destination number dialled by the originator in URI format (tel:<address>).
event	NetworkCallEvent	See NetworkCallEvent.
Returns
Void.
Exceptions
-

processNotification

Call session setup originating from the network, and supervised in monitor mode NOTIFY, see addNetworkCallListener. These call sessions can be controlled by the call control Web Service.

Table 4-19 processNotification(listenerTicket, originator, participant, event)

Parameter Name	Type	Description
Input
listenerTicket	xsd:string	A listenerTicket identifying the call. Retrieved when addNetworkCallListener was invoked.
originator	xsd:string	The address of the originator of the call in URI format (tel:<address>).
participant	xsd:string	The address of the destination number dialled by the originator in URI format (tel:<address>).
event	NetworkCallEvent	See NetworkCallEvent.
Returns
Void.
Exceptions
-

Complex data types

NetworkCallEvent

Enumeration with one of the following values:

• ADDRESS_ANALYSED
• ORIGINATING_CALL_AUTHORISED
• TERMINATING_CALL_AUTHORISED
• ORIGINATING_CALL_ATTEMPT
• TERMINATING_CALL_ATTEMPT
• ALERTING
• BUSY
• NO_ANSWER
• CALL_FAILURE
• CALL_ANSWERED
• DISCONNECT