A Real-Time Application Environment is a set of files that may include:
- CGPL files with Application code and code modules.
- Arbitrary service files - pre-recorded media files, for example.
- Language directories.
Environments are designed to support several human (spoken) languages. The default
Environment language is English. To support other languages, an Environment should
contain language directories, named as the languages they support
(french, russian, japanese, etc.)
A language directory can contain the same files as the Environment itself, but it
cannot contain language subdirectories.
Real-Time Application Tasks can select a language to be used. When a non-default
language is selected, and the application code tries to read a file
from the Application Environment, the selected language subdirectory is used. If the file
is not found in the language subdirectory, the file is retrieved from the Application Environment
itself (i.e. the default language file is used).
The CommuniGate Pro server comes with a built-in "Stock" Real-Time Application Environment.
This Environment contains some basic applications and all files required by those applications,
as well as some useful code section and media files.
Each CommuniGate Pro system has its Server-wide Application Environment. A
CommuniGate Pro Dynamic Cluster installation also has a Cluster-wide Application
Environment. To modify these Environments, open the WebAdmin Interface Domains section and follow
the PBX link.
Each CommuniGate Pro Domain has its own Application Environment.
To modify that Environment, open the WebAdmin Interface Domains section, open the Domain Settings
for the selected Domain and follow the PBX link.
Modifications of the Cluster-wide Environment, as well as
modifications of an Environment in any Shared Domain are automatically distributed
to all Cluster Members.
Since Domains have their own Application Environments, different applications in
different Domains can have the same name.
All Application Environment files should use the UTF-8 character set for non-ASCII symbols.
Real-Time Application Tasks are executed "on behalf" of a certain
CommuniGate Pro Account.
When an application requests an "environment file" and the default language is selected,
the Server looks for the file in:
- the Account Domain Environment.
- the Server-wide Environment or (if the Account belongs to a Shared Domain) the Cluster-wide Environment.
- the Stock Environment.
If a non-default language is selected, the Server first looks for the file in the language directories
of the Environments listed above. If the file is not found in any of those directories,
the listed Environments themselves are searched. So, if a language-specific file has not been created,
the default-language (English) file is used.
This hierarchy provides for simple Application customization. Accounts in all Domains
can use the same Stock or Server-wide applications, while Domain Administrators can customize
these applications by uploading custom files into their Domain Environments.
The WebAdmin Interface provides the Real-Time Application Environment Editor
pages to manage Server-wide, Cluster-wide, and Domain Application Environments.
To manage the Server-wide and Cluster-wide Environments, open the Users realm of the WebAdmin Interface, and
click the PBX link.
To manage the Domain Environment, open that Domain page in the Users realm of the WebAdmin Interface,
and click the PBX link. The Domain Administrator should have the CanModifyPBXApps Access Right to be able
to create and modify the Domain Application Environment.
The Environment Editor page contains the list of all files "visible" in this Environment: it
lists files directly uploaded to this particular Environment, as well as all files
uploaded to the Environments used as the "default files" source for this Environment:
Files directly uploaded to the Environment have a checkbox in the Marker column. Files from the other Environments "visible"
in this Environment have the word default in that column.
You can download any of the Environment files by clicking the file name.
You can upload a file to the Environment by clicking the Browse button and selecting a file on your workstation,
then clicking the Upload button.
You can delete any of the files uploaded to the Environment by selecting the checkboxes and clicking
the Delete Marked button.
If you are uploading a file with the .sppr or the .sppi extension,
the Editor assumes that the file contain some CG/PL program code, and it tries to compile that code.
If you are uploading a file with the .settings extension,
the Editor assumes that the file contain a dictionary, and it tries to parse it.
If the compiler or the parser detects an error, the file is not uploaded, and the file content
is displayed on the Editor page, with the red <--ERROR--> marker
indicating the location of the error.
The Server places used Real-Time Environment files into an internal cache.
When you upload a file to any Environment, that Environment cache is automatically cleared.
If you upload a file to a Shared Domain Environment or to the Cluster-wide Environment,
the updated file automatically propagates to all Cluster Members.
You can upload a set of files by uploading a TAR-archive (a file with .tar name extension). For example,
when you have a TAR-archive with a predesigned Real-Time Application you can open the Environment you want to modify,
and upload the .tar file. The
Server will unpack the archive and store each file individually, as if they were uploaded one-by-one.
The Editor page contains the list of all Language directories:
To create a new Variant, enter the language name, and click the Create Language button.
To open a Language directory, click its name. The Editor will display the Language name,
and it will provide the UP link to the list of the default language files.
CLI/API
The Command Line Interface/API can be used to manage Application Environments. See the Real-Time Application Administration section for the details.
Virtual File Storage Area
The Application Environments can be modified using FTP and HTTP clients, CG/PL applications, and any other
method that provides access to the Account File Storage.
Special $DomainPXBApp, $ServerPXBApp, and $ClusterPXBApp directories
provide access to the Domain and Server/Cluster-wide Application Environments.
Real-Time Applications run as Tasks. To start an Application,
the CommuniGate Pro Server starts a new Task and instructs it to execute the main
entry code section of the specified Application.
A Real-Time Application Task can run in the disconnected mode, or it can be a part of
exactly one Real-Time session (such as a phone call) with some peer. A peer
is any Real-Time entity, such as a SIP phone, a PSTN gateway, a remote Real-Time application
communicating via SIP, or a local Real-Time Application, i.e. some other Task.
If a Task is participating in a session with some peer, it can be in one of the following modes:
- incoming
- an incoming session (a call in the telephony terms, an INVITE request
in the SIP terms) has been directed to the Task, but the Task has not accepted the session (call) yet.
- provisioned
- an incoming session has been directed to the Task,
the Task has not accepted the session yet, but it has sent a provisional response to the caller.
- connecting
- the Task has initiated an outgoing session (call), but the session has not been established yet.
- connected
- the Task has accepted an incoming session, or the Task has established an outgoing session.
A Task can receive Signals from its peer, and it can send
Signals itself. Signals can be used to end the current session, to update the session parameters, etc.
Some of the Signals sent by the peer are processed by the Real-Time Application Environment itself,
while other Signals are passed to the Task for processing.
A Real-Time Application Task can have a Media Channel associated with it. When a session is
established, the Task Media Channel is connected to the peer's media channel.
A Task can use its Media Channel to send media (audio, video) to the peer, and to record
media sent by the peer.
A Task can switch the peer media somewhere else - for example, to a separate service
providing music on hold or other media services. When the peer media is switched away,
the Task Media Channel cannot be used, but the Task still can control the peer by sending Signals
to it and it still receives Signals from the peer. The Task can switch the peer media back to
its own Media Channel.
A Media Channel provides a conversation space. A Task can attach other peer media
to the Task own Media Channel. This operation creates a conversation space
(or a conference) that includes the Task own peer and all peers with media attached to
this Task. Media sent by any peer in a conversation space is relayed to all other peers
in that space, using the data mixing algorithms and parameters defined for that media type.
A Task with attached peer media can use its Media Channel to send media to its own peer
and to all attached peers at once.
Real-Time Application Tasks can automatically process Call Transfer requests.
When a Task receives a REFER request (from a remote client, or from a different Task),
it can:
- process it automatically (this is the default option)
- reject it
- pass it to the application
If a Task is instructed to processes REFER requests automatically, it creates a new INVITE request
and sends it to the address specified in the Refer-To: field. While this INVITE request is in progress,
the task informs the peer about the call progress by sending it NOTIFY requests.
If the INVITE request is completed successfully, the Task sends the BYE Signal request to the current peer
(unless it has already received the BYE Signal from the current peer),
and then it switches its Signal dialog and the Media Channel to the new peer:
The INVITE signal initiated with the REFER signal can contain authentication information.
The application program can instruct the Task:
- to authenticate the INVITE signal as coming from the current Account. This is the default option.
- to authenticate the INVITE signal as coming from the peer (the entity that has sent the REFER signal).
- to reject REFER signals.
To process "Assisted" Call Transfer, the Real-Time Application engine detects all INVITE signals with the Replaces field.
If the dialog data specified in the Replaces field matches an active dialog established in any Real-Time Task, the INVITE signal
is directed to that Task. The Task sends a BYE signal to the current peer, and it switches its Signal dialog to the
source of this INVITE signal, and it switches the Media channel to the entity specified in the INVITE signal.
This processing takes place automatically, transparently to the application program the Task is running.
A pair of Real-Time Application Tasks can build a Media Bridge. When a Media Bridge is built, the Tasks' peers
exchange media, while each Task stays in control of the peer signaling.
To build a bridge:
- an application program some Task A is running uses the StartBridge CG/PL function to send a special [bridgeStart] event
to some other Task B. The request contains the the current Task A peer media description.
- the application program the Task B is running receives this request.
- the Task B application program uses the AcceptBridge CG/PL function to build the bridge.
- the Real-Time Application engine sends a re-INVITE signal to the Task B peer, switching its Media to the Task A peer Media.
- the Real-Time Application engine sends a [bridgeResponse] event to Task A. This event contains the Task B peer media description.
- the AcceptBridge operation in Task B application program completes, and the Task B application program continues to run.
- when the Task A receives the [bridgeResponse] event, the Real-Time Application engine processes the event itself, and it does not deliver it to the Task A application program.
- the Real-Time Application engine sends a re-INVITE to the Task A peer, switching its Media to the Task B peer Media.
- the StartBridge operation in Task A completes, and the Task A application program continues to run.
When the Tasks A and B are in the "bridged" state, one of the Tasks (Task B here) can receive a re-INVITE signal from its peer.
The new media description in this signal request may ask the Task to change its media parameters (hold/resume, switching to a different media source, etc.).
This re-INVITE signal is processed automatically, without any involvement of the application programs the Tasks are running:
- the Real-Time Application engine sends a special [bridgeUpdate] event to the Task A. This event contains the new media description.
- the Real-Time Application engine processes the [bridgeUpdate] event itself, and it does not deliver it to the Application program the Task A is running.
- the Real-Time Application engine sends a re-INVITE signal to the Task A peer, switching it to the new Media source of the Task B peer.
- the Real-Time Application engine sends the new Peer A media description (received with the re-INVITE response) to the Task B as a special [bridgeResponse] event.
- when the Task B receives the [bridgeResponse] event, the Real-Time Application engine process it itself and does not deliver it to the Task B application program.
- the new Task A media descriptor received is sent to the Peer B as a response to the initial re-INVITE signal, switching the Task B peer to the new Task A peer media.
When the Tasks A and B are in the "bridged" state, one of the Tasks (Task A here) can receive a Call Transfer (REFER) signal from its peer:
- the the Real-Time Application engine composes the INVITE signal for the Task A, and sends it to the referred peer; the Signal contains the Task B peer media description.
- the INVITE signal succeeds and the new Task A peer (peer C) media description is received.
- the Real-Time Application engine automatically sends a special [bridgeUpdate] event to the Task B, with new peer media description.
- when the Task B received the [bridgeUpdate] event, the Real-Time Application engine processes the event itself, and it does not deliver it to the Task B application program.
- the Real-Time Application engine sends a re-INVITE signal to the Task B peer, switching it to the Media source of the new Task A peer.
When the Tasks A and B are in the "bridged" state, one of the Tasks (Task A here) can receive Call Transfer (INVITE with Replaces) signal (delivered to it by the Signal module based on the Replaces field content):
- the Real-Time Application engine automatically sends a special [bridgeUpdate] event to the Task B, with new Task A peer media parameters.
- the Real-Time Application engine sends a re-INVITE signal to the Task B peer, switching it to the Media source of the Task A new peer.
- the Real-Time Application engine sends the INVITE response to the new Task A peer with the Task B peer media parameters, connecting the new Task A peer and the Task B peer media.
When the Tasks A and B are in the "bridged" state, one of the Tasks (Task A here) can decide to break the Media Bridge:
- an application program the Task A is running uses the BreakBridge CG/PL function to break the Media bridge.
- the Real-Time Application engine automatically sends a special [bridgeClose] event to the Task B, and sends a re-INVITE signal
to the Task A peer, switching it to the Task A Media Channel.
- when the Task B receives the [bridgeClose] event, the Real-Time Application engine automatically sends a re-INVITE request
to the Task B peer switching it to the Task B Media Channel.
- the Real-Time Application engine delivers the [bridgeClose] event to the Task B application program.
When the Tasks A and B are in the "bridged" state, one of the Tasks (Task A here) can receive a disconnect (BYE) signal from its peer,
or it can quit for various reasons. In this case:
- the Real-Time Application engine automatically sends a special [bridgeClose] event to the Task B.
- when the Task B receives the [bridgeClose] event, the Real-Time Application engine automatically sends a re-INVITE request
to the Task B peer switching it to the Task B Media Channel.
- the Real-Time Application engine delivers the [bridgeClose] event to the Task B application program.
The Real-Time Application engine may choose to implement a Media Bridge using one Task Media Channel as a "media relay".
The Bridged Call functionality is used to implement the B2BUA (Back-to-Back User Agents) technology. A pair of Real-Time Tasks
in the Bridged Mode can work as a "smart proxy": while peers connected to these tasks can communicate directly, the
signaling is still controlled with the Tasks and the application programs these Tasks are running.
Real-Time Applications can be written using the CG/PL language.
When a Task is created to process an incoming call, the main entry of
the specified CG/PL application program is executed.
Real-Time Applications can use CG/PL external-declarations.
When a code section (a procedure or a function) declared as external is called,
a file with the code section name and the .sppi extension is loaded from the current
Environment. The program code in this file must contain the code section with the specified name
and of the proper type (a procedure or a function).
The program code in an .sppi file may contain other code sections as well.
Real-Time Applications can use the following built-in procedures and functions.
- ReadInput(timeOut)
- This function is used to receive external Task communications: DTMF symbol entered
by the peer, signals sent by the peer, and Events sent by other Tasks and by the system itself.
See the CG/PL Events section for the detail.
The timeOut value should be a number specifying the maximum wait period (in seconds).
If the timeOut value is zero, the function checks for pending digits and events, without any waiting.
The function returns:
- a string with the first DTMF symbol in the Task DTMF buffer.
The symbol is removed from the Task buffer.
- a dictionary with the first waiting Event. The Event is
removed from the Task Event queue.
- a null-value if no DTMF symbol and no Event was received during the specified time period.
When the peer disconnects, the Task receives a Disconnect Event from the system (this Event dictionary
does not contain the .sender element).
- IsDisconnectEvent(input)
- This function returns a true-value if the input value is a Disconnect Event.
//
// Sample: ReadInput()
// Accept an incoming call (stop if it's not possible).
// Play the PressPound media file.
// Wait for any input for up to 5 seconds.
// If the "pound" ("#") symbol was entered,
// play the Good media file.
// Otherwise,
// play the Bad media file.
// Stop.
//
entry Main is
if AcceptCall() != null then stop; end if;
PlayFile("PressPound");
PlayFile(ReadInput(5) == "#" ? "Good" : "Bad");
end entry;
- AcceptCall()
- This function accepts an incoming session, if there is one:
the Task should be in the incoming or provisioned mode.
This function returns a null-value if the session is accepted successfully, and the Task
is placed into the connected mode.
If a session cannot be accepted, this function returns an error code string,
and the Task is placed into the disconnected mode.
//
// Sample: AcceptCall()/RejectCall()
// If the current local time is not between 8:00 and 17:00,
// reject the call (with the 403 error code) and stop.
// Otherwise,
// accept the call (stop if it is not possible)
// play the Welcome media file and stop.
//
entry Main is
currentTime = TimeOfDay(GMTToLocal(GMTTime()));
currentHour = currentTime / 3600;
if currentHour < 8 or currentHour >= 17 then
RejectCall(403); stop;
end if;
if AcceptCall() != null then stop; end if;
PlayFile("Welcome");
end entry;
- RedirectCall(newURI)
- This procedure redirects an incoming session, if there is one:
the Task should be in the incoming or provisioned mode.
The newURI value should be a string, or an array of strings. The incoming
session is redirected to the URI(s) specified and the Task is placed into the disconnected mode.
- ForkCall(newURI)
- This procedure redirects an incoming session, if there is one:
the Task should be in the incoming or provisioned mode.
The newURI value should be a string, or an array of strings. The incoming
session is directed to the URI(s) specified, and the current Task remains in the same state,
so it can accept, reject, redirect, provision, or fork this call later.
- ProvisionCall(media,reliably)
- This function sends a provisional Response for an incoming session Request, if there is a pending one:
the Task should be in the incoming or provisioned mode.
If the media value is not a null-value, then a Task Media Channel is created,
the Task is placed into the provisioned mode and the Media Channel operations
(such as PlayFile) can be used to generate "ring-back tones".
If the reliably value is not a null-value, the response confirmation (SIP PRACK)
is requested, and the Task is suspended till a confirmation request arrives.
This function returns a null-value if the response is sent successfully.
If a provisional response cannot be sent, this function returns an error code string.
- ProvisionCall(parameters)
- This function is an extension of the ProvisionCall function shown above.
The function parameters are specified using the parameters dictionary, which can contain the following elements:
- media
- if this element is present, then it has the same effect as a non-null value of the media parameter of the ProvisionCall function.
- reliably
- if this element is present, then it has the same effect as a non-null value of the reliably parameter of the ProvisionCall function.
- responseCode
- if this element is present, its value should be a number in the 101..199 range (inclusive). It specifies the numeric Response code sent. If this element is not present, the 180 value is used.
- responseText
- if this element is present, its value should be a string. It specifies the textual Response code sent. If this element is not present, the default Response text is used.
- reasonCode
- if this element is present, its value should be a positive number. The Reason header field is added to the Response, using this element and the reasonText element values.
If the element value is less than 1000, the composed field contains SIP as the "protocol" value,
otherwise the protocol value is set to Q.850, and 1000 is substracted from the element value.
- reasonText
- if this element is present, its value should be a string. This element is used only when the reasonCode element is a positive number.
- RejectCall(responseCode)
- This procedure rejects an incoming session if there is one: the Task should be in the incoming or provisioned mode.
The responseCode value should be a numeric value between 400 and 699, or an error code string.
This number is sent back to the caller as the Signal Response code.
If the code 401 is sent back, and the request came from outside the CommuniGate Pro Server (via the SIP protocol), the
SIP server module adds the proper fields to the response to facilitate client Authentication.
Alternatively, the responseCode value can be a dictionary with the optional responseCode, responseText, reasonCode, reasonText
elements, which have the same meanings as the elements of the ProvisionCall() function parameter.
The Task is placed into the disconnected mode.
//
// Sample: RedirectCall()/ProvisionCall()
// Provision the call (stop if it is not possible).
// If the current local time is between 12:00 and 13:00,
// fork the call to user1 in the same domain.
// Play the "PleaseWait" media file.
// If the current local time is not between 8:00 and 17:00,
// redirect the call to user2 in the same domain, and stop.
// Otherwise,
// Accept the call (stop if it's not possible).
// Play the Welcome media file, and stop.
//
entry Main is
if ProvisionCall(true,true) != null then stop; end if;
currentTime = TimeOfDay(GMTToLocal(GMTTime()));
currentHour = currentTime / 3600;
if currentHour >= 12 and currentHour <= 13 then
ForkCall("sip:user1@" + MyDomain());
stop;
end if;
PlayFile("PleaseWait");
if currentHour < 8 or currentHour >= 17 then
RedirectCall("sip:user2@" + MyDomain());
stop;
end if;
if AcceptCall() != null then stop; end if;
PlayFile("Welcome");
end entry;
Note: if a pending incoming call has been canceled, the Task receives a Disconnect Event, and
the Task mode changes to disconnected.
- SetCallParameters(parameters)
- This procedure sets call (INVITE dialog) parameters.
The parameters value should be a dictionary with new call option parameters.
The existing parameter values are removed.
The following parameters are used for all dialog requests:
- Max-Forwards
- a positive number used to limit the number of "hops" a request can traverse.
- customIdentity
- a string or a dictionary to be used as the request P-Asserted-Identity header field.
This field is also added to the provisioning responses.
- Privacy
- a string or an array of strings to be used as the request Privacy header field.
- IPSource
- the IP Address object that overrides the Server rules and explicitly sets the source IP Address for outgoing SIP packets and locally generated media.
- allowedAudioCodecs
- if this parameter is an array, it lists the names of audio codecs that can be included into SDP documents sent with this task.
- allowedVideoCodecs
- if this parameter is an array, it lists the names of video codecs that can be included into SDP documents sent with this task. If this array is empty, the sent SDP does not include the "video" media, unless this SDP is an answer to an SDP offer that includes the "video" media.
- allowedSSRC
- if this parameter is "NO", all "ssrc" attributes are removed from SDP.
- allowedAttributes
- if this parameter is "nonCustom", all custom attributes (with names starting with x-) are removed from SDP.
if this parameter is "required", all attributes except the required ones are removed from SDP. The "phone", "info", "uri", "email", "time", "zone", "key", "bandwidth", "title" SDP elements are removed, too.
The following parameters are used when a call dialog is established:
- Session-Expires
- a non-negative number specifying the default session expiration (dialog refreshing) time period. If set to zero,
no dialog refreshing takes place.
Some parameters are used when a call is initiated (with the StartCall, StartBridgedCall functions)
or when a call is accepted (with the AcceptCall function) - see below.
- StartCall(destination)
- This function initiates an outgoing session. The Task should be in the disconnected mode.
The destination value should be a string containing the URI to send a session request to,
or a dictionary containing the following string elements:
- "" (empty string)
- the URI to send the request to.
- From (optional)
- an E-mail, URI, or field-data to use for the request From field. If not specified, the current Account data is used.
- To (optional)
- an E-mail, URI, or field-data to use for the request To field. If not specified, the request URI is used.
- Call-ID (optional)
- a string to use for the request Call-ID field. If not specified, a new Call-ID is generated.
The following optional parameters are taken from the destination dictionary. If they are absent
(or the destination is not a dictionary), they are taken from the current call parameters set with the
SetCallParameters procedure:
- authUsername, authPassword
- credentials (the authenticated name and password strings) to be used if an outgoing request is rejected with the 401 error code.
- Expires
- a number specifying the maximum calling (alerting) time (in seconds).
- Subject
- request Subject string.
- Remote-Party-Id
- an array of dictionaries, each used to compose request Remote-Party-Id fields.
- Privacy
- a string or an array of strings to compose the request Privacy field.
- Diversion
- an array to compose the request Diversion fields.
- P-CGP-Private
- a string to compose the request P-CGP-Private field. This field can be used to pass arbitrary parameters between
sending and receiving Tasks (on the same or different systems).
- P-CGP-Local
- a string to compose the request P-CGP-Local field. This field can be used to pass arbitrary parameters between
sending and receiving Tasks (only within the same single-server or Cluster systems).
- P-Billing-Id
- a string to compose the request P-Billing-Id field stored in the Call object. This string is added to the server-generated CDRs.
- Call-Info
- an array to compose the request Call-Info fields.
- Alert-Info
- a string to compose the request Alert-Info field.
- Replaces
- a string or a dictionary to compose the request Replaces field. If a dictionary is used, it should contain
the string values Call-ID, fromTag, toTag, and a boolean value early-only.
- Via
- if this string parameter is specified, it should contain a URI.
The URI is added to the request as its Route field, forcing the request to be sent via that URI.
- NoInitSDP
- if this parameter is specified, the call establishment request does not contain the local Media channel SDP.
- No100rel
- if this parameter is specified, the outgoing requests do not have the "100rel" SIP option advertised as supported.
- NoPrecondition
- if this parameter is specified, the outgoing requests do not have the "precondition" SIP option advertised as supported.
- mediaRelay
- if this parameter exists, a Media Proxy is always created for an outgoing call.
- TimerB
- if this parameter exists, its numeric value overrides the default "Timer B" value for an outgoing SIP transaction:
this is the number of seconds to wait till the remote site sends any response (such as 100-Trying).
- Relay
- if this parameter exists and its value is "NO", the outgoing SIP request cannot be relayed to non-client destinations.
- encryptMedia
- if this parameter exists and its value is "NO", SDP documents (offers) sent with this task will not include elements needed to enabled media encryption.
This function returns an error code string if an outgoing call cannot be initiated.
If an outgoing call has been initiated successfully, the function returns a null-value,
and the Task starts to receive call progress Events from the system:
zero or more provisional response Events, followed by exactly one final response Event.
If the outgoing session has been established successfully, the Task receives a final response Event without a parameter.
If the outgoing session has not been established, the Task receives a final response Event with a parameter - the error code string.
- IsCallProvisionEvent(input)
- This function returns a true-value if the input value is a call provisional response Event.
Otherwise the function returns a null-value.
- IsCallCompletedEvent(input)
- This function returns a true-value if the input value is a call final response Event.
Otherwise the function returns a null-value. When a Task receives a final response Event, the call
signaling process has completed. If the Event has a parameter, the call has failed, and the
parameter contains the error code string.
- CancelCall()
- If a Task has a pending outgoing call (initiated using the StartCall function), this procedure cancels that call (the Task will not receive a final response Event).
- Disconnect()
Disconnect(reasonCode,reasonText)
- This procedure ends the active session, if any, and the Task is placed into the disconnected mode.
If the reasonCode is specified, its value should be a positive number, and if the reasonText is specified, its value should be a string.
If the BYE signal is sent to the peer, the Reason header field with the reasonCode and reasonText values
is added to the signal request.
//
// Sample: StartCall()/Disconnect()
// Accept an incoming call (stop if it's not possible).
// Remember the caller URI.
// Play the CallBack media file.
// Disconnect();
// Call the caller back (stop if it's not possible).
// Play the IamBack media file, and stop.
//
entry Main is
if AcceptCall() != null then stop; end if;
fromWhom = RemoteURI();
PlayFile("CallBack");
Disconnect();
if StartCall(fromWhom) != null then stop; end if;
loop
input = ReadInput(3600);
exitif not IsCallProvisionEvent(input);
null;
end loop;
if not IsCallCompletedEvent(input) or else
input.parameter != null then stop; end if;
PlayFile("IamBack");
end entry;
- IsConnected()
- This function returns a true-value if the Task is in the connected mode.
- IsHalfConnected()
- This function returns a true-value if the Task is
in the connected or provisioned mode.
- RemoteURI()
- This function returns a string with the peer URI (taken from the dialog From/To addresses).
If there is no session in place, the function returns a null-value.
- LocalURI()
- This function returns a string with the Task URI.
- IncomingRequestURI()
- This function returns a string with URI of the pending incoming INVITE request. If there is no
pending incoming INVITE request, the function returns a null-value.
- RouteLocalURI(uri)
- This function tries to Route the E-mail address from
the specified URI. If the URI cannot be parsed, or the URI address cannot be routed,
or it routes to a non-local address (i.e an E-mail address hosted on a different system),
this function returns a null-value. Otherwise, the function returns the E-mail address
of the CommuniGate Pro user the original URI address is routed to.
This function allows you to correctly process all Forwarders,
Aliases, and other CommuniGate Pro Routing methods.
- RemoteIPAddress()
- This function returns an ip-address object the session establishment
request was received from or was sent to. This IP Address/port pair is the actual peer address
or the address of a proxy used to relay the peer signaling.
- RemoteAuthentication()
- This function returns a null-value if the session starting request was not authenticated,
or a string with the authenticated user E-mail address.
- PendingRequestData(fieldName)
- This function returns a data element of the pending incoming request.
If a request is pending, the function returns the following data, depending on the fieldName value, which should be a string:
- Call-ID
- the function returns a string with the request Call-ID value.
- From, To, Referred-By
- the function returns a dictionary if the field exists in the request. The dictionary contains the following elements:
- "" (and element with empty string key)
- the address (in the username@domain form)
- @realName
- a string with the "display-name" part of the address
- @schema
- a string with the URI schema (if absent, sip is assumed)
- @port
- a number with the "port" part of the URI
- @tag
- the "tag" field parameter
- @field-params
- a dictionary with other field parameters.
- @headers
- a dictionary with URI headers.
- anyOtherName
- a URI parameter.
All elements except the address element are optional.
- Remote-Party-Id, History-Info
- the function returns an array if the field or fields exist in the request.
Each array element is a dictionary with the same elements as in the From field dictionary.
- Foreign-Asserted-Identity
- the function returns an array of the request P-Asserted-Identity fields.
Each dictionary contains the same elements as the From field dictionary.
- Route, Record-Route, Diversion, Via, Path, Supported, Require, Proxy-Require, Privacy, Allow, Allow-Events
- the function returns an array containing one or more strings with field values. If no field value exists,
the function returns a null-value.
- CSeq
- the function returns a number - the value of the CSeq field numeric part.
- Max-Forwards
- the function returns a number - the value of the Max-Forwards field.
- User-Agent, Reason, P-CGP-Private, P-CGP-Local
- the function returns a string - the field value. If the field is absent, the function returns a null-value.
- Accept
- the function returns an array containing 2 strings for each field value: the accepted content type and the accepted content subtype.
If the field is absent, the function returns a null-value.
- xmlsdp
- the function returns an XML presentation of the pending request SDP.
If no request is pending, the function returns a null-value.
- PendingRequestExData(fieldName)
- This function returns a non-standard data element of the pending incoming request.
The fieldName value should be a string. It specifies the name of a non-standard request field.
If a request is pending, the function returns specified field data.
If no request is pending, the function returns a null-value.
- SetLocalContactParameter(paramName,paramValue)
- This procedure allows you to add "field" parameters to the Contact field data for this Task dialog(s).
The paramName value should be a string. It specifies the field parameter name.
If the paramValue value is a non-empty string, it specifies the field parameter value.
If the paramValue value is an empty string, a parameter without a value is set (such as isfocus).
If the paramValue value is a null-value, a previously set field parameter is removed.
Each Task has a DTMF buffer string. When a DTMF symbol is received either in an INFO Request
or as a media packet (via the Media Channel), the symbol is appended to this buffer.
- DTMF()
- This function returns a string with the current content of the DTMF buffer. The DTMF buffer
is not changed. Usually this function is not used, the ReadInput() function is used instead.
- ClearDTMF()
- This procedure empties the DTMF buffer.
- SetInterruptOnDTMF(arg)
- This function sets a flag controlling media playing and recording interrupts with received DTMF symbols.
The arg value specifies the new flag value:
if this value is a null-value, received DTMF symbols will not interrupt media playing or recording, otherwise received DTMF symbols will interrupt media playing and recording.
When a Task is created, this flag value is set to a true-value.
The function returns the previous value of this flag.
- SendDTMF(symbol)
- This function sends a DTMF symbol to the peer.
The symbol value should be a string containing 1 DTMF symbol.
The function returns a null-value if the symbol has been sent, or a string with an error code if sending failed.
//
// Sample: ReadInput()/SendDTMF()
// Accept an incoming call (stop if it's not possible).
// Wait for an input for 10 seconds. If no input - stop.
// If a digit is entered
// play that digit, and send it back.
// (using "0" ... "9" files)
// If a star ("*") is entered,
// wait for a digit (for 3 seconds)
// and play the digit number square (2 digits)
// If a pound ("#") is entered or the Peer
// has disconnected, or any Event was sent, stop.
//
entry Main is
if AcceptCall() != null then stop; end if;
loop
input = ReadInput(10);
if input == "*" then
input = ReadInput(3);
if IsString(input) and input != "#" then
input = "*" + input;
end if;
end if;
exitif not IsString(input) or input == "#";
if Substring(input,0,1) != "*" then
PlayFile(input);
void(SendDTMF(input));
else
input = Number(Substring(input,1,1);
product = input * input;
PlayFile(String(product/10));
PlayFile(String(product%10));
end if;
end loop;
end entry;
- PlayFile(fileName)
PlayFile(fileName,msec)
- This procedure retrieves a file from its Application Environment and plays it.
The string parameter fileName specifies the file name.
If the specified file name does not contain a file name extension, the supported extensions are added and tried.
The file should contain media data in one of the supported formats.
If the msec parameter is specified, its value should be a number.
Then the specified file is played for msec milliseconds, repeating
file in a loop if the file media playing period is shorter than the specified period.
If the msec parameter has a negative value, the file is played in an infinite loop.
Playing is suppressed or interrupted if the session ends, if the DTMF
buffer is not empty (unless DTMF Interruption is disabled), or if there is an Event enqueued for this Task.
- Play(waveData)
Play(waveData,msec)
- This procedure plays the waveData value which should be a datablock.
The datablock should contain media data in one of the supported formats.
If the msec parameter is specified, it works in the same way as it works for the PlayFile procedure.
Playing is suppressed or interrupted if the session ends, if the DTMF
buffer is not empty (unless DTMF Interruption is disabled), or if there is an Event enqueued for this Task.
- PlayTone(freq,msec)
PlayTone(freq,msec,freq2)
PlayTone(freq,msec,freq2,ratio)
- This procedure plays a "tone" (a sine wave).
The freq parameter value should be a non-negative number - the wave frequency (in Hz).
If the value is zero, audio silence is generated.
The msec parameter value should be a number, it works in the way as it works for the PlayFile procedure.
If the freq2 parameter is specified, the generated tone is a combination of two sine waves,
and the parameter value should be a positive number specifying the second wave frequency (in Hz).
If the ratio parameter is specified, its value should be a positive number in the 1..10000 range.
It specifies the relative amplitude of the second wave, the first wave amplitude being 100.
Playing is suppressed or interrupted if the session ends, if the DTMF
buffer is not empty (unless DTMF Interruption is disabled), or if there is an Event enqueued for this Task.
- GetPlayPosition()
- This function returns a number - the portion of the media (in milliseconds) played by the last
PlayFile or Play operation.
If the media was played in a loop, the length of the played portion in the last "loop" is returned:
if a 3-second sound was played in loop, and it was interrupted after 7.2 seconds, the function returns
1200.
If the last Play* operation did not play its sound (because the DTMF buffer was not empty or there was an enqueued Event),
the function returns either 0, or a negative value.
- SetPlayPosition(arg)
- This procedure instructs the very next Play* operation to start playing its sound not from its beginning.
The arg value should be a non-negative number. It specifies how many milliseconds of the media should
be skipped before the Play* operation starts to play the media.
- IsPlayCompleted()
- This function returns a true-value if the media played by the last Play* operation was played
in full. If media playing was interrupted, the function returns a null-value.
- Record(timeLimit)
- This function records incoming audio data. The timeLimit value should be a positive
number, it specifies the maximum recording time in seconds.
Recording is suppressed or interrupted if the session ends, if the DTMF
buffer is not empty, or if there is an Event enqueued for this Task.
The function returns a null-value if recording was suppressed, or a datablock with the
recorded sound in the WAV format.
- SetLocalHold(flag)
- This procedure sets the current call "on Hold" (if the flag is a true-value), or releases the call from hold (if the flag is a null-value).
This procedure can be used only when the Task is in the connected mode, and the Task peer media is not bridged.
- ReleaseMediaChannel()
- This procedure releases the Task Media Channel (releasing the associated system resources).
This procedure can be used only when the Task is in the disconnected mode, or when the Task peer media is bridged.
- MediaOption(optionName)
MediaOption(optionName,newValue)
- This function return the current value of a Task Media Channel option.
If the newValue is specified and its value is not a null-value, then it is set as the new option value.
The optionName value should be a string and it specifies the option name. The following options are supported:
- "preplay"
- this a numeric option, is specifies the amount of pre-recorded media (in milliseconds) sent to remote peers "ahead of time",
to pre-fill the peer jitter buffers.
- "mixerDelay"
- this a numeric option, it specifies the delay (in milliseconds) the Media Channel introduces before it reads Media Leg
audio and mixes it with other Media Leg audio when a Media Channel has more than 2 active Media Legs ("conferencing").
The larger the delay, the better the Media Channel mixer processes irregular media streams coming from conference participants
connected via sluggish networks.
- "inputSilenceLevel"
- this a numeric option, it specifies the minimum level of the incoming audio. If the level is lower than the specified value,
it is processed as a complete silence - it is not recorded and if there are more than 2 Media Legs ("conferencing"), this Media Leg
incoming audio is not used mixed.
- "skipSilence"
- this a numeric option, it specifies a time limit (in milliseconds). When the Media Channel is used to record the incoming
media and the incoming audio level is lower than the "silence level" (see above), and this silence lasts longer than the specified
time limit, recording is suspended. It resumes as soon as the incoming audio level increases above the "silence level".
- "stopRecordOnPause"
- this a numeric option, it controls recording of silence. When the Media Channel is used to record the incoming
media and the incoming audio level is lower than the "silence level" (see above), and this silence lasts longer than the time limit specified
with the "skipSilence" option (see above), recording is stopped if the value if this option is set to 1. The Task also receives special DTMF signal #15.
- "mixMOH"
- this a numeric option, it specifies if media from a peer sending MOH (Music-on-hold) should be processed or it should be ingnored.
If the value is 1, the MOH media is processed, if the value is 0 (default), the MOH media is ignored.
If there are not more than two peers connected to the Media Channel, MOH media is always processed.
//
// Sample: Record()/PlayFile()/Play()
// Accept an incoming call (stop if it's not possible).
// Play the GreetingIs file.
// Read the current prompt from
// the MyGreeting.wav file in the File Storage.
// Loop playing the greeting.
// if "1" is entered, rewrite the prompt file and quit
// if "2" is entered, play "Beep" and record the prompt.
//
entry Main is
if AcceptCall() != null then stop; end if;
PlayFile("GreetingIs");
prompt = ReadStorageFile("MyGreeting.wav");
loop
if IsData(prompt) then Play(prompt); end if;
input = ReadInput(10);
exitif not IsString(input) or else input == "#";
if input == "1" then
if WriteStorageFile("MyGreeting.wav",prompt) then
PlayFile("Goodbye"); stop;
end if;
PlayFile("Failure");
elif input == "2" then
PlayFile("Beep");
prompt = Record(30);
else
PlayFile("InvalidEntry");
end if;
end loop;
PlayFile("GoodBye");
end entry;
- StartBridge(taskRef)
- This function sends a special StartBridge Event to the specified Task asking it to
take over this Task peer media.
The taskRef value should be a task handle. It specifies the Task
to send the request to.
This function returns a null-value if the specified Task successfully
took over this Task peer media. Otherwise, the function returns an error code string.
The current Task should be in the incoming, provisioned, or connected mode.
The current Task is placed into the waiting state, and the target Task receives a special StartBridge Event.
- IsStartBridgeEvent(input)
- This function returns a true-value if the input value is a StartBridge Event.
Otherwise the function returns a null-value.
- RejectBridge(input,errorCode)
- This function rejects the StartBridge request.
The input parameter value should be a StartBridge Event to reject.
The errorCode parameter value should be a string.
The StartBridge function in the Task that has sent this StartBridge Event
exits the waiting state and it returns an error code string.
This function returns a null-value if the pending incoming call has been successfully rejected.
Otherwise, the function returns an error code string.
- AcceptBridge(input)
- This function builds a Media Bridge with the Task
that has sent it the StartBridge Event.
The input value should be the StartBridge Event to accept.
This function returns a null-value if the Media Bridge has been successfully established.
Otherwise, the function returns an error code string.
The StartBridge function in the Task that has sent this StartBridge Event
exits the waiting state. That function returns a null-value if the Media Bridge is established,
otherwise, it returns an error code string.
If that Task was in the incoming or provisioned mode, the call in accepted,
and the Task switches to the connected mode.
When a Media Bridge is successfully established between a pair of Tasks, their peer
media are connected to each other. Tasks Media Channels are disconnected from their peers
and the Media Channel operations (PlayFile, Record, etc.) cannot be used.
A Task cannot use the StartBridge, AcceptBridge, and AttachMixer
functions while a Media Bridge is active.
- BreakBridge()
- This function removes the Media Bridge established with a successful completion of the
StartBridge or AcceptBridge function.
The Task Media Channel is reconnected to the peer media.
A special BreakBridge Event is sent to the "bridged" Task.
This function returns a null-value if the existing media bridge has been broken.
Otherwise, the function returns an error code string.
- IsBreakBridgeEvent(input)
- This function returns a true-value if the input value is a BreakBridge Event.
Otherwise the function returns a null-value.
When a Task receives a BreakBridge Event, it does not have to use the BreakBridge()
procedure, as the Media Bridge has been already removed.
If a Task disconnects its peer, or the Task peer disconnects itself, or a Task
stops (normally, or because of an error), and there is an active Media Bridge, this
Media Bridge is automatically removed.
//
// Sample: StartBridge()/AcceptBridge()/BreakBridge()
// Accept an incoming call (stop if it's not possible).
// Create a new Task to run the Caller code,
// and send it an Event with the URI to dial.
// Play the PleaseWait media file.
// Wait for a StartBridge Event from the Caller Task.
// Accept it and loop till the user disconnects.
//
// The Caller code:
// Receive a URI to call as an Event from the parent Task
// Connect to the URI and play the YouGotACall media file
// StartBridge with the parent, loop till the user disconnects
//
entry Caller forward;
procedure ControlBridge() forward;
entry Main is
if AcceptCall() != null then stop; end if;
callerTask = spawn Caller;
if callerTask == null or else
SendEvent(callerTask,"dial","sip:internal@partner.dom") != null then
PlayFile("Failure");
stop;
end if;
PlayFile("PleaseWait");
input = ReadInput(30);
if not IsStartBridgeEvent(input) or else
AcceptBridge(input) != null then
PlayFile("Failure");
stop;
end if;
// we have established a bridge
ControlBridge();
PlayFile("GoodBye");
end entry;
//
// Caller Task code
//
entry Caller is
// wait for a "dial" event from the main task
input = ReadInput(30);
if input == null or input.what != "dial" then stop; end if;
mainTask = input.sender;
// Calling the URI specified as the Event parameter
// If connection failed, send an Event back to the
// main task and quit
resultCode = StartCall(startEvent.parameter);
if resultCode != null then
void(SendEvent(mainTask,"result",resultCode));
stop;
end if;
// wait for any Event other than provisional ones
loop
input = ReadInput(3600);
exitif not IsCallProvisionEvent(input);
end loop;
// the parent has sent us "stop" - then we'll die immediately
if IsDictionary(input) and then input.what == "stop" then stop; end if;
if not IsCallCompletedEvent(input) or else input.parameter != null then
void(SendEvent(mainTask,"result","generic error"));
stop;
end if;
if StartBridge(mainTask) != null then
PlayFile("Failure");
stop;
end if;
// we have established a bridge
ControlBridge();
PlayFile("GoodBye");
end entry;
//
// Controlling the peer signaling:
// while the media is bridged:
// exit if the peer hangs up, dials "#"
// or if the bridge is removed
//
procedure ControlBridge() is
loop
input = ReadInput(3600);
exitif IsBreakBridgeEvent(input) or else
IsDisconnectEvent(input) or else input == "#";
end loop;
void(BreakBridge());
end procedure;
- AttachMixer(input)
- The input value should be a StartBridge Event sent to this Task.
This function attaches the peer media of the sender Task to this Task Media Channel.
This function returns a null-value if the sender Task peer media is successfully
attached to this Task Media Channel. Otherwise, the function returns an error code string.
The StartBridge function in the sender Task exits the waiting state.
That StartBridge function returns a null-value if the sender Task peer media is attached successfully.
Otherwise, that function returns an error code string.
Note: If the AttachMixer function is used when the Task is in the disconnected mode,
and the Task does not have a Media Channel, a new Media Channel is created for this Task.
- DetachMixer(taskRef)
- This function detaches the peer media of the specified Task from this
Task Media Channel.
The taskRef value should be a task handle.
The function returns a null-value if the peer media of the specified Task
was attached to this Task Media Channel, and if that peer media is successfully
reconnected back to the specified Task.
The specified Task receives a BreakBridge Event.
The function returns an error code string if the other Task peer media cannot
be detached.
The taskRef value can be a null-value. In this case, all other
Tasks peer media are detached from this Task Media Channel.
- MixerAttached()
- This function returns an array of task handles for all Tasks that
attached their peer media to this Task Media Channel.
If this Task Media Channel does not have any other Task peer media attached,
this function returns a null-value.
- MuteMixer(taskRef,flag)
- This procedure tells the Task Media Channel if it should ignore input from the specified Task.
The taskRef value should be a Task handle. This Task should have its peer media attached to the current Task Media Channel.
The taskRef value can be a null-value, in this case the current Task peer media is controlled.
The flag value specifies the operation: if the flag is a true-value, the peer media is ignored, if it is a null-value, the Media Channel starts to process media from the peer.
If the flag value is the "special" string, the peer media is not distributed to other "normal" peers.
If the flag value is the "hearsSpecial" string, the peer mute mode is not modified, but the media from the "special" peers is distributed to it.
If the flag value is the "hearsMute" string, the peer mute mode is not modified, but the media from all peers (muted, special, or unmuted) is distributed to it.
If the flag value is the "hearsNormal" string, the peer mute mode is not modified, but the media from the "special" peers is not distributed to it.
When a Task has other Task peer media attached to its Media Channel, all media
are placed into one conversation space (or a conference).
This Task cannot use the StartBridge or AcceptBridge functions.
Note: in certain cases the system may decide to convert an AcceptBridge
function operation into an AttachMixer function operation.
As a result, the BreakBridge operation can be used by a Task that has exactly
one other peer media attached to its Media Channel.
If a Task disconnects its peer, or the Task peer disconnects itself, or a Task
stops (normally, or because of an error), and there are other Task peer media
attached to this Task Media Channel, the system automatically detaches all of them.
- StartBridgedCall(destination,event)
- This function works as the StartCall function, but the event value should be StartBridge Event sent to this Task by an ingress Task.
The Task initiates a call using the media descriptor from the Event data (describing the ingress Task peer media).
Provisional responses are delivered as Events to the current Task, and they are sent to the ingress Task (see below).
If the call is successful, a Media Bridge between the Tasks is built,the current Task receives a final response Event, and the StartBridge operation in the ingress Task completes successfully.
If the call fails, the current Task receives a final response Event, but no Event is sent to the ingress Task.
The current Task can either try a new StartBridgedCall operation, or it can use AcceptBridge/AttachMixer/RejectBridge operations to process the received StartBridge Event.
If the ingress Task quits, or if that Task had a pending incoming call and that call was canceled, the initiated outgoing call is canceled, and the current Task receives the BreakBridge event.
- TransferSupported()
- This function returns a true-value if the peer supports Transfer operations, otherwise the function returns a null-value.
- IsCallTransferredEvent(input)
- This function returns a true-value if the input value is a CallTransferred Event (this event can be sent when an external request has switched this Task to a different peer).
Otherwise the function returns a null-value.
- TransferCall(destination)
- This function attempts a "blind transfer" of the Task peer. The Task should be in the connected mode.
The destination value should be a string containing the URI or an E-mail address to transfer the call to.
If the call transfer fails, the function returns an error code string.
If the call transfer succeeds, the function returns a null-value.
When the operation is completed, the Task stays in the connected mode, unless the peer has disconnected explicitly (by sending the BYE request).
- StartTransfer(taskRef)
- This function sends a special StartTransfer Event to the specified Task asking it to connect Task peers directly.
The taskRef value should be a task handle. It specifies the Task to send the request to.
This function returns a null-value if the specified Task successfully connected the peers.
Otherwise, the function returns an error code string.
The current Task should be in the connected mode.
The current Task is placed into the waiting state, and the target Task receives a special StartTransfer Event.
- IsStartTransferEvent(input)
- This function returns a true-value if the input value is a StartTransfer Event.
Otherwise the function returns a null-value.
- RejectTransfer(input,errorCode)
- This function rejects the StartTransfer request.
The input parameter value should be a StartTransfer Event to reject.
The errorCode parameter value should be a string.
The StartTransfer function in the Task that has sent this StartTransfer Event
exits the waiting state and it returns an error code string.
- AcceptTransfer(input)
- This function connects the current Task peer with the peer of the Task
that has sent it the StartTransfer Event.
The input value should be the StartTransfer Event to accept.
This function returns a null-value if the peers have been successfully connected.
Otherwise, the function returns an error code string.
The StartTransfer function in the Task that has sent this StartTransfer Event
exits the waiting state. That function returns a null-value if the peers have been connected,
otherwise, it returns an error code string.
If the peers have been connected, both Tasks stay in the connected mode, unless
their peers explicitly send the disconnect Signals. The Tasks should either quit or
they should use the Disconnect procedure to fully disconnect from their peers.
Applications can receive and send INFO requests.
Certain INFO requests (such as DTMF event requests) are processed automatically and
this section does not apply to them.
INFO request data is presented as a dictionary, with the following elements:
- Content-Type
- This optional string element contains the request body Content-Type (such as application).
- Content-Subtype
- This optional string element contains the request body Content-Type subtype.
- "" (empty key)
- This optional string or datablock or XML element contains the request body content.
- SendCallInfo(params)
- This function sends an INFO request to the Task peer. The Task should be in the connected mode.
The params value should be a dictionary containing the INFO request data.
If the operation fails, the function returns an error code string.
If the operation succeeds, the function returns a null-value.
When an INFO request is sent to a Task, the Task receives a special CallInfo Event.
The Event parameter element contains a dictionary - the INFO request data.
- IsCallInfoEvent(input)
- This function returns a true-value if the input value is a CallInfo Event.
Otherwise the function returns a null-value.
Applications can send REGISTER requests to external SIP servers.
REGISTER request data is presented as a dictionary, with the following elements:
- targetDomain
- This string specifies the domain for registration.
- Via
- This optional element specifies the address of the remote server if it's different from the targetDomain value or can not be resolved from it.
- fromAddress
- This string specifies the Address Of Record (full account name) on the remote server.
- Call-ID, CSeq
- These string elements specify parameters for the registration dialog.
- authUsername, authPassword
- These string elements specify credentials for the registration.
- "" (empty key)
- This string should specify the value for the Contact URI of the REGISTER request. That URI should be used by the remote SIP server as the target for the
INVITE requests while processing calls coming in for the account on the remote system.
- SendCallRegister(params)
- This function sends an REGISTER request to a remote SIP server. The Task should be in the disconnected mode.
The params value should be a dictionary containing the REGISTER request data.
If the operation fails, the function returns an error code string.
If the operation succeeds, the function returns the TimeStamp when the requested registration expires.
Upon a successful REGISTER operation completion the function returns a TimeStamp value - the GMT time when the requested registration will expire. The task should re-schedule the next registration request for the time before that expiration time stamp, and for the next attempt use the same parameters, including Call-ID, and increment the CSeq value by 3.
- SendCallOptions(params)
- This function sends an OPTION request to the Task peer (if the dialog has been established and the Task is in the connected mode),
or to an arbitrary entity (if the Task is in the disconnected mode).
The params value is interpreted in the same way as the StartCall destination parameter value.
If the operation fails, the function returns an error code string.
If the operation succeeds, the function returns a null-value.
- SignalOption(optionName)
SignalOption(optionName,newValue)
- This function return the current value of a Task Signal option.
If the newValue value is specified and its value is not a null-value, then it is set as the new option value.
The optionName value should be a string and it specifies the option name. The following options are supported:
- "refer"
- this option specifies how the Task processes the REFER requests and INVITE/replaces requests.
The supported values are:
- "self"
- outgoing signals are authenticated as coming from the current Account; this is the default value
- "peer"
- outgoing signals are authenticated as coming from the Task peer (i.e. the sender of the REFER signal)
- "disabled"
- REFER and INVITE/replaces request processing is prohibited.
- "transferReport"
- this option specifies if call transfers are to be reported.
The supported values are:
- "NO"
- no event is sent when a Task is transferred to a different peer; this is the default value
- true-value ("YES")
- the Task receives a special CallTransferred Event when it is transferred to a different peer.
- "bridgeBreak"
- this option specifies how the Task reacts when a media bridge is broken by the other task.
The supported values are:
- "disconnect"
- the Task disconnects its current peer, and the Task enters the disconnected mode.
- "keep"
- if the Task does not have a Media channel, it is created. Then the Task peer is switched to that channel.
- "default"
- if the Task does not have a Media channel, the Task disconnects its current peer. Otherwise, the Task peer is switched to that channel. This is the default value.
- "bridgedProvisionRelay"
- this option specifies how the provisional responses generated with the StartBridgedCall function are delivered to the peer.
The supported values are:
- true-value ("YES")
- provisional responses are relayed to this Task peer, using the ProvisionCall function with the reliably parameter set to a null-value; this is the default value
- "reliably"
- provisional responses are relayed to this Task peer, using the ProvisionCall function with the reliably parameter set to a true-value
- "NO"
- provisional responses are not relayed to this Task peer
- "bridgedProvisionToTags"
- this option specifies how the provisional responses generated with the StartBridgedCall function are delivered to the peer.
The supported values are:
- "NO"
- all provisional responses contain the same To-tag, assigned to this Task; this is the default value.
- true-value ("YES")
- the provisional responses keep their original To-tags.
- "bridgedProvisionQueue"
- this option specifies the provisioning response FIFO queue size. This queue is used when
provisioning responses from the other task are received faster that they can be delivered to this Task peer.
The default queue length is 10.
- "callInfo"
- this is a read-only option; if specified, the newValue must be a null-value.
The function returns information about the system "call" object: time connected, proxies used, etc.
- SendCallNotify(params)
- This function sends a NOTIFY request to an arbitrary entity (the Task must be in the disconnected mode).
The params value must be a dictionary containing the following string elements:
- "" (empty string), From, To, Call-ID
- these elements are processed in the same way as the StartCall destination parameter elements.
- Event
- the event name string
- @Event-Params
- an optional dictionary with the parametes to put into the request Event field.
- Subscription-State
- an optional string to put into the request Subscription-State field.
- @Content
- an optional string or a datablock to send as the request body.
- Content-Type, Content-Subtype
- optional strings for the request Content-Type field.
If the operation fails, the function returns an error code string.
If the operation succeeds, the function returns a null-value.
A Task can receive Instant messages and XMPP requests. They are delivered to the Task as Events.
- IsInstantMessageEvent(input)
- This function returns a true-value if the input value is an Instant Message Event.
Otherwise the function returns a null-value.
The event parameter is a dictionary. It contains the same elements as the SendInstantMessage function content parameter,
with the following additional elements:
- From
- a string - the sender E-Mail address.
- peerName
- an optional string - the sender "real name".
- fromInstance
- an optional string - the sender "instance".
- To
- a string - the original recipient E-Mail address.
- toInstance
- an optional string - the recipient "instance".
- authName
- an optional string - the authenticated identity of the sender.
- redirector
- an optional string - the authenticated identity of the message redirector (the Account that redirected this message using its Automated Rules or other means).
- IsXMPPIQEvent(input)
- This function returns a true-value if the input value is an XMPP IQ/presence Event.
Otherwise the function returns a null-value.
The event parameter is a dictionary. It contains the same elements as the SendXMPPIQ function content parameter,
with the following additional elements: From, peerName, fromInstance, To, toInstance, authName, redirector,
which have the same meanings as in Instant Message Events.
The following audio file formats are supported:
- WAV (data starts with the RIFF tag)
- a file should contain a single data chunk with PCM 8-bit or 16-bit data, or GSM-encoded data.
- au (data starts with the .snd tag)
- a file should contain PCM 8-bit or 16-bit data, or 8-bit mu-Law data.
- gsm
- a file should contain a stream of 33-byte GSM 06.10-encoded frames.
|