Protocol for Simple Computer Telephony (PSCT) 

Contents
--------

PART I
     1.0 Overview
     1.1 Design Goals
     1.2 Intro to the PSCT Model
     1.3 Definitions
     1.4 PSCT Resources and Message Format
     1.5 Transaction Identifiers
     1.6 Types of Messages
PART II
     2.0 Session Related Transactions (Actions) and Events    
     2.1 Address Related Actions and Events     
     2.2 List of Standard Parameters
     2.3 Terminal Related Actions and Events
     2.4 Standard List of Terminal Related Parameters
     2.5 Call Related Actions and Events
     2.6 Line Related Actions and Events
     2.8 Standard List of Line-Related Parameters

1.0 Overview
------------

PSCT is an HTML/ASCII based, SSL optional, Platform Neutral protocol
for third party call control.  This will allow any application to
communicate with telephony servers to accomplish tasks such as:

* Make a phone call.
* Set or Get information about your Terminal.

History
01-03-2001 v0.0.2 reformat and typo edits, etc.. -rsb
08-24-2000 v0.0.1 overhaul of old SCTP spec. -rsb@ostel.com

NOTE:

Version 0.0.1 of the PSCT spec was a rewrite of the SCTP spec which was
written by:

Principal Authors
Paul Davidson, Nortel (pauldav@nortel.ca)
Brian McConnell, Pacific Telephony Design (brianm@phonezone.com)
Advisors
En-Kuang Lung, Altigen Communications (lunge@altigen.com)
Steve Gelbach, Nexpath Corp (steve@nexpath.com)
Jack Pines, Voysys (pjp@voysys.com)

The SCTP that we are referring to is not to be confused with the IETF
draft of SCTP, which is an unrelated protocol.  There have been a
number of SCTP's over the years, all telephony related, all unique.
In a fit of creativity, we have rotated to avoid this namespace,
yielding PSCT.  As noted in the history above, the first draft of
PSCT, 0.0.1, is a rewrite of the SCTP protocol specification written
by the above authors and advisors in 1997, so most of the credit for
it should go to them.

1.1 Design Goals
----------------

* To provide a simple and flexible interface which requires no
  third-party development tools or middleware.  A competent programmer
  should be able to build a working prototype of a client or server
  application within a few days. 
* To provide first and third party call control services typically
  offered by digital telephone handsets, and by client telephony APIs
  such as TAPI and TSAPI, and to facilitate multipoint conversations
  (i.e. conference calls).
* To enable clients to handle multiple calls simultaneously.
* To enable clients to connect to multiple servers simultaneously.
* To perform common voice mail management tasks (i.e. check for
  messages, indicate waiting messages to a client). Media control will
  be addressed in a addendum to this protocol or a separate protocol
  designed to address mixed media messaging.
* Capable of interacting with POTS, ISDN and proprietary digital phone
  line services, and of treating virtual telephone circuits as real
  circuits.
* To enable users to modify their station settings (i.e. Do Not
  Disturb, Call Waiting, Call Forwarding, etc).
* To enable agents to log into and out of ACD groups. 
* To be scalable from small key/intercom systems to large central
  offices and telephone networks. 

1.2 Introduction To PSCT Model
------------------------------

PSCT abstracts physical resources in such a way that a client can talk
to many different types of servers, from a small office intercom
system to a metropolitan telephone network. Care has been taken to
avoid making device or platform dependent assumptions, and to avoid
forcing developers to implement applications in a specific way beyond
defining a consistent addressing and messaging scheme.

PSCT deals with five different types of objects. Transaction and event
messages are used in reference to each of these objects. The key
concepts referred to by these messages are:

* Terminals - telephone handsets or client devices
* Addresses - individual users (a single user may use several devices,
* or many users may share a single device)
* Calls - individual telephone conversations or multi-party conferences
* Sessions - PSCT client/server socket connections. Each client
* establishes one session to each server it wishes to interact with or
* control. A client can set up multiple sessions (i.e. to multiple
* telephony servers) if desired.
* Lines - voice paths (circuit switched or packet switched) leading
* from the server to another server or outside telephone network.
* Groups - (for future use) this will refer to collections of
* addresses, such as are found in ACD (automated call distribution)
* applications. Not currently implemented in this revision of the
* protocol.

1.3 Definitions
---------------

Terminals

The term terminal is used to refer to any telephone instrument, communication device (i.e. telephone card, modem, etc) or other appliance which is connected to the server. The terminal is a peripheral through which a user can conduct a conversation. It is not permanent associated with a particular user (although developers are perfectly free to permanently bind addresses and terminal Ids in a fixed addressing system, as is typical with most PBX systems).

Addresses

The term address is used to refer to an individual user. A
corresponding analogy in the electronic messaging world would be an
email address. Many users could share the same email address, or many
email addresses could be mapped to a single workstation. In a typical
telephone system, an address will correspond to an extension number
or, in the case of public telephone network applications, a telephone
number.

Calls

The term call is used to refer to an individual voice path or
multi-party conversation (which is treated as a call which
encapsulates several other call paths, more on this later). A single
terminal can receive many calls simultaneously. A single address can
receive many calls simultaneously. 

Sessions

A session is used to refer to a data path between an PSCT client and
an PSCT server. A single client can maintain open sessions to multiple
servers, just as a server can talk to many clients simultaneously. 

Lines

Lines refer to physical or virtual circuits leading from the server to
another server, or to an external telephone network. We added this so
as to provide key system features to PBX and PSTN users (the ability
to observe and manipulate external line appearances, as well as to
monitor external network activity).

1.4 PSCT Resources and Message Format
-------------------------------------

This section describes the general form (semantics) of PSCT.

Session 

A session is a link between a PSCT client application and a PSCT
server over a serial communications transport. The purpose of the
connection is to transfer recognized PSCT messages.

* Messages are transferred via standard sockets using port 9006 when
  using BSD Sockets transport.
* Client initiates a connection.
* Connection remains open until closed by Client, Server or fault.

Clients are encouraged to first attempt to make an SSL connection, and
fallback to an insecure connection if this fails.  Clients are also
encouraged to close the connection when not in use for prolonged
periods of time.

Messages

Form 1

PSCT messages are formatted using the same string formatting rules as
those employed in HTTP. These formatting rules make messages easy to
parse, and to transport through TCP interfaces from many vendors. This
format also permits the addition of additional parameters to messages
without creating backward compatibility problems for existing
applications.
All messages are composed of ASCII (lower 126) characters.
All messages are terminated with a <CR> delimiter
There is no pre-defined limit to message length
Messages take the following form:
  parm1=value1&parm2=value2&...<CR>
  ex. action=transfer&cid=1234&destination=301<CR>
Note: standard HTTP escape sequences are used to denote characters
such as &, esc, <CR>, etc within the body of a PSCT message.

Form 2

PSCT messages are composed of a group of strings each terminated with
a carriage return, line feed sequence.  Three types of lines are
defines:
    Protocol: PSCT <SP>xx.xx<CR>
The protocol line appears once per message.  It is used to identify
the protocol and the version.  The xx.xx denotes the major and minor
version number
    Content: param:<SP>value<CR>
Content lines contain a single parameter and value pair.  An example
of the differences is given below.  Note that the <CR> are omitted in
this example.
  Form 1:
action=hello&address=4155551212&password=xyz&version=1.1&tid=123
  Form 2:
    PSCT 01.10
    action: hello
    address: 4155551212
    password: xyz
    tid: 123

    Terminator: <CR>
The terminator is an empty line.  It signifies the end of a message.
Form 2 syntax differs only from Form 1 in that Form 2 uses the
traditions 'header' format used by many other TCP application
protocols.

1.5 Transaction Identifiers
---------------------------

When issuing a transaction of any type, the sender will include a
serialized transaction id number (tid) in the message. This number
need only be unique for the sender, and not system-wide. The
transmitted tid is included in subsequent responses from the recipient
to facilitate sorting multiple replies, or replies received out of
order. The protocol does not care how you select transaction ids, and
if you don't include one, the server should still accept the
request. However, if you plan on having your client doing more than
one thing at a time, it is strongly recommended that you include
serialized tids with your transaction messages.

1.6 Types Of Messages
---------------------

There are three basic types of messages used in PSCT: session related
messages (i.e. login/logout), transaction messages and responses, and
asynchronous events. All messages observe the same formatting scheme,
and so this distinction only applies to the context of the messages
themselves.

Session Messages

Session messages include login/logout procedures, protocol version
identification messages, heartbeat (stay-alive) messages, and other
messages related to the maintenence of a connection from a client to a
server.

Ex.   action=hello&address=4155551212&password=xyz&version=1.1&tid=123<CR>
    action=hello&tid=123&result=ok&session=1121&text="Login
    Accepted"<CR>


Transaction Messages (Actions)

Transaction related messages may be sent by either the client or
server, and are typically interpreted as a command or action. The
recipient of one of these messages will typically be expected by the
client to respond with a success, status or error message. Call
control commands would be issued as transaction messages, as
illustrated in the example below.

Ex.    action=hold&status=on&cid=15622&tid=124<CR>
    action=hold&tid=124&result=ok&text="Call 15622 On Hold"<CR>

Note in the example above, the client is requesting that the server
place call #15622 on hold. The call ID is an arbitrary number assigned
by the server to uniquely identify a particular call in the system. A
transaction ID (tid) is used so that the client can identify replies
to a particular transaction if responses to two or more requests are
returned out of order. Upon receiving the initial request (first
line), the server responds with the command issued and transaction ID,
along with an indication of success or failure. 

Asynchronous Events

Asynchronous events are used to notify either the client or server of
a change of state (i.e. telephone handset going offhook, call ringing
to an extension, etc). Either the client or server may issue an
asynchronous event. 

Clients are expected to register with the server to receive various
classes of events (more on this later). This provides server vendors
with an opportunity to implement security policies (i.e. deny attempts
to monitor someone else's telephone line), and is also intended to
prevent transmission of redundant or unnecessary data across the
network.

Ex.   event=call&cid=15622&action=drop<CR>

In this example, the server is informing the client that Call ID 15622
has ended.

Ex.    event=terminal&address=301&state=ringing<CR>

In this example, the server is informing a client that extension 301 is ringing
Clients can also use asynchronous events to communicate information to
the server which could then decide to relay this information to other
clients.

Ex.    event=terminal&address=201&state=away<CR>

In the example above, the client is telling the server that the owner
of extension 201 has walked away from his desk. No response is
expected from the server.

Events Versus Actions

The important difference between events and transactions is that no
response is expected to an event message, whereas one or more
responses will be expected to a transaction message.

-------
PART II
-------

2.0 Session Related Transactions (Actions) and Events
-----------------------------------------------------

Message: 
Hello
-----
Description: 
Establishes an PSCT session with a server. A session should be
established for each address associated with a particular terminal
-----
Message Type: 
Action
Parameters: 
address (req)
password (req)
tid (req)
terminal (req)
Expected Response: 
Server will return a message referencing the transaction ID (tid)
given by the client, included will be a parameter named result which
will have a value of "ok" or "error" In the case of an error
condition, a standard error code and description. If accepted, the
server will return a session ID which will be associated with this
session.

Message: 
Bye
---
Description: 
Manually closes an PSCT session. Can be invoked by either a client or
server. The server or client can also close the connection if more
than N heartbeat messages go unacknowledged within a specified period
of time.
---
Message Type: 
Action 
Parameters: 
session_id (req)
address (req)
tid (req)
Expected Response: 
Server responds with an acknowledgement (see example below). If there
is no response, the requesting party can probably assume the
connection has been lost.

Message: 
Heartbeat
---------
Description: 
Sends a heartbeat message to the client or server, which responds with
a short acknowledgement.
---------
Message Type: 
Action
Parameters:
none required
Expected Response: 
Receiving end responds with a short acknowledgement message, see example below.

Message: 
Time
----
Description: 
Telecommunications servers often receive highly accurate timebase
information from external sources. This event allows this data to be
relayed to client workstations for time synchronization purposes. Note
- due to latency in data transmission, this service should be used for
approximate (~1 sec) synchronization.
----
Message Type: 
Event
Parameters:
date - YYYYMMDD
time - HHMMSS *
* - Zulu time (Greenwich standard time)
Expected Response:
None

Examples

Hello (Action)
The example below illustrates a successful login procedure. -->
denotes a message sent from the client to a server, where <-- denotes
a message sent from the server to the client.

-->
   action=hello&address=201&terminal=41564799911.201&password=123&tid=1722<CR>

<--  action=hello&tid=1722&result=ok&session_id=128<CR>
The example below illustrates an unsuccessful login procedure. For a
list of standard error codes, consult the table at the end of this
document.
-->
action=hello&address=201&terminal=4156479911.201&password=123&tid=1722<CR>
<--
action=hello&tid=1722&result=error&error_code=504&error_text="Invalid
PW"<CR>

Bye (Action)

The example below illustrates how the bye transaction is used to close
an PSCT session. (Of course, instead of saying goodbye, you could use
the less polite "New York" procedure of simply closing the connection
<g>)

-->  action=bye&session_id=128&address=201&password=123&tid=1988<CR>
<--  action=bye&result=ok&tid=1988<CR>

Heartbeat (Action)

The example below illustrates how the heartbeat transaction is used to
poll the client or server on the far side of the socket
connection. Client and server timeout thresholds should be adjustable
by the user.

-->  action=heartbeat&session_id=128&tid=1788<CR>
<--  action=heartbeat&tid=1788&result=ok<CR>

Time (Event)

The following example illustrates how the time event is used to
deliver time base information to the client or server (although this
data will typically be relayed from the server to the client)

-->  evt_mask=session&event=time&date=970903&time=181615<CR>

These four basic procedures encapsulate all that is required to
establish, maintain and destroy a connection to a PSCT server. 

2.1 Address Related Actions and Events
--------------------------------------

As discussed in the introduction, addresses are analgous to user
accounts. Telephone systems differ significantly in how they map users
onto telephone handsets. Some used a fixed addressing scheme where the
user identity is synonymous with the handset address. Other systems,
particularly newer PC based systems, allow dynamic user/handset
mapping (the latter scheme being quite useful in situations where
people move around a lot, a phenomenon which is becoming increasingly
common in the workplace).

Most actions and events related to individual user's call management
settings, real-time status information, etc, are handled in this class
of messages.


Message: 
SetStatus
---------
Description: 
This action is used to set a user specific parameter such as call
forwarding, do not disturb, call waiting, etc. The list of supported
parameters will vary by system. A list of standard parameters is
provided below.
---------
Message Type: 
Action
Parameters: 
address (req)
parameter (req)
value (req)
tid (req)
Expected Response: 
Server replies with either a success or error condition. If an error
occurs, it will reply with a standard error code and optional
description of the error.

Message: 
GetStatus
---------
Description: 
This action is used to poll the server for the status of a particular
address. This action can be invoked in one of two ways. It can be used
to request a specific parameter, or it can request that the server
provide all available parameters for a given address. 
---------
Message Type: 
Action
Parameters: 
address (req)
parameter (optional)
tid (req)
Expected Response: 
If a parameter is specified, the server replies with the current value
of that parameter. If not specified, the server replies with a list of
parameters and their current values. (See example below)

Message: 
TestParm
--------
Description: 
This action is used to query the server to see if it recognizes a
particular parameter for a particular user. 
--------
Message Type: 
Action
Parameters: 
address (req)
parameter (req)
tid (req)
Expected Response: 
If the parameter is recognized by the server (or client, this can work
in both directions), it replies with result=ok. If not, it replies
with result=error, and can include explanatory information in addtion
to an error code if desired.

Message: 
MonitorAddress
--------------
Description: 
This action is used to register with the server to monitor address
related events for a particular address or address mask. It is up to
the server whether to accept or deny these requests based on its own
user policies.
--------------
Message Type: 
Action
Parameters: 
address (req)
tid (req)
Expected Response: 
If the request is accepted, the server replies with a result=ok
message, otherwise it replies with an error  code and message.

Message: 
StateChange
-----------
Description: 
This event is used to notify a listening client about a state change
on a monitored address. This can be used, for example, to notify users
that a particular person has gone on Do Not Disturb.
-----------
Message Type: 
Event
Parameters:
address (req)
parameter (req)
value (req)
Expected Response: 
None expected

Examples

SetStatus

Following is an example of how the SetStatus action is used to update
a particular user's station settings. 

-->  action=setstatus&address=201&tid=123&parameter=callwaiting&value=on<CR>
-->  action=setstatus&address=201&tid=124&parameter=dnd&value=off<CR>
-->  action=setstatus&address=201&tid=125&parameter=fwd_rna&value=vm<CR>
-->  action=setstatus&address=201&tid=126&parameter=fwd_busy&value=vm<CR>
-->  action=setstatus&address=201&tid=127&parameter=ring_timeout&value=4<CR>
<--  action=setstatus&tid=124&result=ok<CR>
<--  action=setstatus&tid=123&result=ok<CR>
<--  action=setstatus&tid=125&result=ok<CR>
<--  action=setstatus&tid=126&result=ok<CR>
<--  action=setstatus&tid=127&result=ok<CR>

GetStatus

Following is an example of how the GetStatus action is used to
retrieve the call waiting setting for a particular user.

-->  action=getstatus&address=201&tid=131&parameter=callwaiting<CR>
<--  action=getstatus&tid=131&value=on<CR>
Following is an example of how the GetStatus action is used to
retrieve all public parameters for a particular user (it is up to the
server to decide which information should be delivered to the client).
-->   action=getstatus&address=201&tid=132<CR>
<--  action=getstatus&tid=132&callwaiting=on&dnd=off&fwd_rna=vm&...<CR>

MonitorAddress

Following is are examples of how a client uses the MonitorAddress
action to ask the server to relay events pertaining to a specific
address, and to an address mask.

Ex. 1 - Monitor a specific address
-->  action=monitoraddress&address=201&tid=133<CR>
<--  action=monitoraddress&tid=133&result=ok<CR>
Ex. 2 - Monitor all addresses
-->  action=monitoraddress&address=*&tid=134<CR>
<--
action=monitoraddress&tid=134&result=error&error_code=505&error_text="Denied"<CR>
Ex. 3 - Monitor an address mask
-->  action=monitoraddress&address=4156476*&tid=135<CR>
<--  action=monitoraddress&tid=135&result=ok<CR>
Ex. 4 - Stop monitoring an address
-->  action=monitoraddress&address=201&stop=true&tid=136<CR>
<--  action=monitoraddress&tid=136&result=ok<CR>
Ex. 5 - Stop monitoring all addresses
-->  action=monitoraddress&address=*&stop=true&tid=137<CR>
<--  action=monitoraddress&tid=137&result=ok<CR>

While it may seem like unnecessary extra work to register with the
server for event notices, this is important as it eliminates the
unnecessary transmission of unneeded data, and also prevents servers
from saturating a network when monitoring large systems. 

Note: it is up to the server to decide which monitoring requests to
accept and deny. For example, a small key system may wish to allow
users to monitor all addresses on the system, while a central office
switch would not want to permit a single user to monitor every address
served by the CO. It is up to the server to decide what policies to
enforce with respect to event notification requests.

TestParm

Following is an example of how the TestParm action is used to ask the
server if it recognizes a particular parameter. (This can be used by
client applications to ask the server which features it recognizes for
user settings)

-->  action=testparm&address=201&parameter=autohold&tid=145<CR>
<--  action=testparm&tid=145&result=ok<CR>

StateChange

Following is an example of how the StateChange event is used to notify
a listening client that a user has set their station to Do Not
Disturb. 
Note: it is up to the server to decide which statechange events to
present to clients. 

-->
   evt_type=address&event=statechange&address=201&parameter=dnd&value=on<CR>
<--
   evt_type=address&event=statechange&address=201&parameter=dnd_msg&value="Out
   for lunch"<CR>

Implementation Notes

The GetStatus and SetStatus actions are intentionally open ended with
their parm=x, value=y syntax. This is due to the fact that while most
telephony servers offer a consistent set of basic features, many
vendors offer additional services that may be exposed through this
type of interface. If a client attempts to update a parameter which is
not recognized by the server, it will simply respond with a "parameter
not recognized" error. Likewise parameters which are not understood by
the client will simply be ignored. The list of standard parameters
below covers most of the basic user settings encountered on private
and public telephone networks.

2.2 List Of Standard Parameters 
-------------------------------

Parameter: autoanswer
Description: Automatically answer incoming calls to user
Syntax Notes: on, off

Parameter: autoanswerspk
Description: Automatically answer incoming calls in speakerphone mode to user
Syntax Notes: on, off

Parameter: autohold
Description: Automatically place calls on hold when user is in conversation
Syntax Notes: on, off

Parameter: autoholdcalls
Description: Maximum number of calls which can be placed on autohold
(if exceeded, this is a busy condition.
Syntax Notes: integer value

Parameter: autoholdmsg
Description: Filename or URL of message to be played when autoholding a caller
Syntax Notes: filename or URL

Parameter: callsholding
Description: Number of calls holding and/or camped for a given user
Syntax Notes: integer (0 or greater)

Parameter: callsparked
Description: Number of calls parked for a given user
Syntax Notes: integer (0 or greater)

Parameter: callwaiting
Description: Call waiting enabled for user
Syntax Notes: on, off

Parameter: callwaitingcalls
Description: Maximum number of calls which can be holding for a user
(default value if not specified is 2)
Syntax Notes: integer value

Parameter: dnd
Description: Toggle do not disturb feature
Syntax Notes: on, off

Parameter: dnd_msg
Description: Short text message displayed when dnd is activated
Syntax Notes: up to 80 char text message (lower ASCII chars only, no CR or LF)

Parameter: fm_newmsgs
Description: Number of new fax messages waiting for user (read-only)
Syntax Notes: integer (0 or greater)

Parameter: fm_oldmsgs
Description: Number of saved fax messages waiting for user (read-only)
Syntax Notes: integer (0 or greater)

Parameter: fwd_all
Description: Call forwarding (all calls)
Syntax Notes: off, any valid dialed number string or address
recognized by server

Parameter: fwd_busy
Description: Call forwarding (busy calls)
Syntax Notes: off, any valid dialed number string or address
recognized by server

Parameter: fwd_rna
Description: Call forwarding (ring no answer)
Syntax Notes: off, any valid dialed number string or address
recognized by server

Parameter: intercom
Description: Enable intercom (speaker) calls to user
Syntax Notes: on, off

Parameter: status
Description: Current status of terminal user is mapped to *
Syntax Notes: ringing, dialing, idle, talking, busy, dnd

Parameter: vm_newmsgs
Description: Number of new voice messages waiting for user (read-only)
Syntax Notes: integer (0 or greater)

Parameter: vm_oldmsgs
Description: Number of saved voice messages waiting for user (read-only)
Syntax Notes: integer (0 or greater)

* the status parameter is used to indicate the current handset status
  of a particular user. There is an important item that server side
  implementers need to be aware of. The server is responsible for
  keeping track of which users are mapped to which terminals. For
  example, if a terminal to which a user is assigned is on dnd, all
  users mapped to that terminal should indicate dnd. In another
  instance, a user is mapped to several terminals, one of which is
  marked dnd, the server may or may not wish to display the user as
  dnd. The rules applied to address-terminal mapping will vary
  depending on the type of system and upon policies implemented by the
  server software. This is a moot point on systems where the address
  and terminal identifiers are identical, but on systems which employ
  dynamic mapping schemes, you'll need to bear this in mind when
  writing the server side interface as there is no universal rule
  which will work for every situation. 

This set of actions and events enables user to manage their call
management settings, and enables applications throughout a network to
monitor the status of individual users (i.e. busy, calling someone, on
do not disturb, etc). This provides all of the necessary functionality
to implement personal call management settings, and to implement
status monitor applications such as a PC based busy lamp field. Note
that this set of actions does not address individual calls or
conferences. This is done with the call related actions and events.


2.3 Terminal Related Actions and Events
---------------------------------------

As discussed in the introduction, terminals are analgous to telephone
handsets or devices. It is important to understand that addresses and
terminals may or may not be the same, depending on the type of
server. Client software developers should never assume that these will
be the same since on some systems many users can share the same
terminal and vice versa.


Message: 
MapAddress
----------
Description: 
This action is used to map an address to a specific terminal on
dynamically mapped systems.
----------
Message Type: 
Action
Parameters: 
Terminal (req)
address (req)
tid (req)
password (opt)
name (opt)
text (opt)
Expected Response: 
Server will respond with a result=ok or a result=error
message. Additional information about error conditions may be provided
(i.e. address not authorized to use terminal, etc)

Message: 
UnmapAddress
------------
Description: 
This action is used to unmap a specific address from a terminal on a
dynamically mapped system.
------------
Message Type: 
Action
terminal (req)
address (req)
tid (req)
password (opt)
Expected Response: 
Server will respond with a result=ok or result=error message.

Message: 
MonitorTerminal
---------------
Description: 
This action is used to register to receive events pertaining to a
given terminal (i.e. to monitor the hookswitch state of a given
station)
---------------
Message Type: 
Action
Parameters: 
terminal (req)
stop (opt)
tid (req)
Expected Response: 
Server will respond with a result=ok or result=error message.

Message: 
TermState
---------
Description: 
This event is used to notify listening clients of a change of state in
a monitored terminal
---------
Message Type: 
Event
Parameters: 
parameter (req)
value (req)
Expected Response: 
None expected

Message: 
SetTermParm
-----------
Description: 
This action is used to set a terminal specific parameter (i.e. gain settings).
-----------
Message Type: 
Action
Parameters: 
parameter (req)
value (req)
tid (req)
Expected Response: 
Server replies with a result=ok or result=error message

Message: 
GetTermParm
-----------
Description: 
This action is used to query the server for terminal specific parameters
-----------
Message Type: 
Action
Parameters: 
parameter (opt)
tid (req)
Expected Response: 
If parameter is specified, server replies with contents of specific
parameter, otherwise it replies with a list of all public parameters
for that station.

Message: 
GetTermList
-----------
Description: 
This action is used to query the server for a list of active
terminals. Server may decide whether to make this information
available or not.
-----------
Message Type: 
Action
Parameters: 
Address (req)
tid (req)
Expected Response: 
returns result=ok if accepted, followed by a
list=x,y,z... string. Otherwise it returns a result=error message with
an optional error code.

Examples

MapAddress
Following is an example of how the MapAddress action is used to
associate a specific user with a terminal. 

-->  action=mapaddress&terminal=142&address=301&name=Brian
   McConnell&tid=145<CR>
<--  action=mapaddress&tid=145&result=ok<CR>

UnmapAddress
Following is an example of how the UnmapAddress action is used to
unmap a terminal/address assignment.

-->  action=unmapaddress&terminal=142&address=301&password=xyz&tid=146<CR>
<--  action=unmapaddress&tid=146&result=ok<CR>

SetTermParm
Following is an example of how the SetTermParm action is used to
update a terminal specific parameter setting.

-->  action=settermparm&terminal=142&parameter=rxgain&value=3&tid=147<CR>
<--  action=settermparm&tid=147&result=ok<CR>

GetTermParm
Following is an example of how the GetTermParm action is used to query
the server for the contents of a parameter setting.

-->  action=gettermparm&terminal=142&parameter=rxgain&tid=148<CR>
<--  action=gettermparm&tid=148&parameter=rxgain&value=3<CR>

GetTermList
Following is an example of how the GetTermList action is used to query
the server for a list of active terminals. 

-->  action=gettermlist&address=201&tid=149<CR>
<--
action=gettermlist&tid=149&result=ok&list=141,142,143,144,145,146,147,148,..<CR>

TermState
Following is an example of the TermState event message, and how it is
used to relay information about change of state in a specific
terminal.

-->  evt_type=terminal&event=termstate&parameter=status&value=ringing<CR>

TermUpdate
Following is an example of how the TermUpdate event is used to inform
a client that a new terminal has been added to the server. (This can
be used to drive real-time status displays of terminals/extensions on
a large telephone system).

-->
   evt_type=terminal&event=termupdate&active=yes&terminal=142&termtype=isdnbri<CR>

2.4 Standard List Of Terminal Related Parameters
------------------------------------------------

Parameter: Address
Description: Address(es) with which the terminal is associated. If
more than one address is associated with a terminal, a comma delimited
list is returned.
Values: One or more numeric strings. If more than one, comma
delimiting is used.

Parameter: Name
Description: Name(s) with which the terminal is associated. 
Values: One or more alphanumeric strings. If more than one, comma
delimiting is used.

Parameter: Status
Description: Status of a specific terminal
Values: idle, vacant, ringing, dialing, talking, holding, dnd, error

Parameter: TermType
Description: Short descriptor of terminal type (normally
read-only). This is used to indicate what kind of terminal is in use. 
Values: Short alphanumeric string describing the terminal type. There
is no pre-defined list of terminal types other than the following
generic classes, vendors may add their own descriptors for specific
telephone handset types etc.
* pots
* pots-centrex
* isdnbri
* h323
* [add your own types here]

Parameter: Text
Description: Shore (< 128 char) text message associated with a
specific terminal (i.e. "Equipment Room")
Values: Alphanumeric string up to 127 chars in length

2.5 Call Related Actions And Events
-----------------------------------

As discussed in the introduction, calls refer to individual calls
(point to point or conference type). Calls are treated independently
of users and addresses. This facilitates first and third party call
control operations, and also permits the creation of network based
real-time monitoring and reporting applications. However, the primary
purpose of this set of actions and events is call control.

Real-time station status information (i.e. for driving busy lamp
fields) is best accessed through the address related actions and
events.

Call Control Fundamentals

The basic unit of information which is used in querying and
manipulating conversations is the cid (call ID) parameter. Each call
should be assigned a unique ID by the server, this ID should be unique
throughout the system, not just for a specific user, since calls will
often be transferred from address to address.

The server should automatically destroy the cid upon completion of a
call (either via the PSCT hangup action, or via a telephone handset
hangup). Care should be taken to insure that resource ids are properly
disposed of once they are no longer needed.

Note: (req) denotes required parameter while (opt) denotes an optional
parameter.

Message: 
Accept
------
Description: 
Instructs server to accept call, create voice path
------
Message Type: 
Action
Parameters: 
cid (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error

Message: 
BlindTransfer
-------------
Description: 
Instructs server to blind transfer call to another destination (local
or remote)
-------------
Message Type: 
Action
Parameters: 
cid (req)
destination (req)
ringback (opt)
tid (req)
Expected Response: 
Server replies with result=ok or result=error. If ringback time is
specified, call returns to sender if not picked up within N seconds.

Message: 
Call
----
Description: 
Instructs server to place call to a destination address.
destination (req)
----
Message Type: 
Action
Parameters: 
supervise (req)
audio_cpa (opt)
network_cpa (opt)
timeout (opt)
Expected Response: 
Server replies with result=ok (completed call), result=error
(incomplete call), or result=? (call setup in progress). Detailed call
completion or failure data is provided in the response

Message: 
CampOn
------
Description: 
Instructs server to camp call to a destination. 
------
Message Type: 
Action
Parameters: 
cid (req)
destination (req)
ringback (opt)
tid (req)
Expected Response: 
Server replies with result=ok or result=error. If ringback time is
specified, call returns to sender if not picked up within N seconds.

Message: 
ConfCreate
----------
Description: 
Instructs server to create a conference resource to which calls can be joined
----------
Message Type: 
Action
Parameters: 
maxsize (req)
owner (opt)
privlevel (opt)
Expected Response: 
Server replies with result=ok or result=error. If a conference is
created, it will also return a cfid specifically for the conference
(not to be confused with a call id). Owner and privlevel parameters
can be used to assign moderation properties to conferences.

Message: 
ConfDelete
----------
Description: 
Instructs server to destroy a conference resource
----------
Message Type: 
Action
Parameters: 
cfid (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error. 

Message: 
ConfJoin
--------
Description: 
Instructs server to add a call to a conference resource
--------
Message Type: 
Action
Parameters: 
cid (req)
cfid (req)
duplex (opt)
owner (opt)
tid (req)
Expected Response: 
Server replies with result=ok or result=error. Duplex can be full or
listen. Owner can be yes or no (to indicate whether caller has owner
privileges)

Message: 
ConfLeave
---------
Description: 
Instructs server to remove a call from a conference
---------
Message Type: 
Action
Parameters: 
cid (req)
cfid (req)
tid (req)
Expected Response: 
Server replies with success or error message

Message: 
ConfList
--------
Description: 
Instructs server to return list of current conference members (can
request list by call id, address or terminal)
--------
Message Type: 
Action
Parameters: 
cfid (req)
listtype (req)
tid (req)
Expected Response: 
Server replies with comma delimited list, or with error
message. Listtype can be cid, address or terminal to indicate how to
return list.

Message: 
Fwd_RNA
-------
Description: 
Instructs server to treat call as ring no answer
Parameters: 
-------
Message Type: 
Action
cid (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error

Message: 
Fwd_Busy
--------
Description: 
Instructs server to treat call as busy
--------
Message Type: 
Action
Parameters: 
cid (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error

Message: 
FwdCall
-------
Description: 
Instructs server to forward call to specified target without answering
-------
Message Type: 
Action
Parameters: 
cid (req)
destination (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error

Message: 
Hangup
------
Description: 
Instructs server to hang up/terminate call
------
Message Type: 
Action
Parameters: 
cid (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error

Message: 
Hungup
------
Description: 
Server uses this event to inform the far side of call termination
------
Message Type: 
Event
Parameters: 
cid (req)
Expected Response: 
None expected, although the client may respond with an acknowledgement

Message: 
Hold
----
Description: 
Instructs server to place a call on hold
----
Message Type: 
Action
Parameters: 
audio (opt)
cid (req)
ringback (opt)
ringback_target (opt)
tid (req)
Expected Response: 
Server replies with result=ok or result=error. Audio can be used to
specify music port, filename or URL to play to caller. Ringback can be
used to specify ringback time which, if exceeded, causes call to ring
back to the address of the user who put the call on hold, or an
optional ringback target

Message: 
NewCall
-------
Description: 
Server uses this event to notify an address of a new call, or a call
which is ringing back from a hold condition
-------
Message Type: 
Event
Parameters: 
cid (req)
clid (opt)
dnis (opt)
line (opt)
name (opt)
sender1..n(opt)
Expected Response: 
Note re: sender1..n parm. This is an optional array which can be used
to transmit a call forwarding history for a specific call (i.e. so the
user can see who has already handled this call)

Message: 
Park
----
Description: 
Instructs server to park a call on hold for retrieval by a
user. Either server or client can specify parking address (behavior
will vary by system)
----
Message Type: 
Action
Parameters: 
cid (req)
parkaddress (opt)
ringback (opt)
tid (req)
Expected Response: 
Server replies with result=ok or result=error. If parkaddress is
specified, client attempts to specify park address, otherwise server
assigns it.

Message: 
CallState
---------
Description: 
Server uses this event to notify listening clients of a change in
state in a particular call.
---------
Message Type: 
Event
Parameters: 
cid (req)
status (req)
Expected Response: 
None expected

Message: 
TransferStart
-------------
Description: 
Instructs server to place call to destination, place current call on
hold. This is used to set up a supervised transfer.
-------------
Message Type: 
Action
Parameters: 
cid (req)
destination (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error. The TransferDrop action
is used to abandon the transfer attempt.

Message: 
TransferDrop
------------
Description: 
Instructs server to abandon transfer attempt, return to original call.
------------
Message Type: 
Action
Parameters: 
cid (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error.

Message: 
TransferComplete
----------------
Description: 
Instructs server to complete supervised transfer
----------------
Message Type: 
Action
Parameters: 
cid (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error

Message: 
Unhold
------
Description: 
Retrieves a call from hold. 
------
Message Type: 
Action
Parameters: 
cid (req)
tid (req)
Expected Response: 
Server replies with result=ok or result=error.

Examples

Accept

-->  action=accept&cid=1655&tid=178<CR>
<--  action=accept&tid=178&result=ok<CR>

BlindTransfer

-->  action=blindtransfer&cid=1656&destination=302&text="Bob on the
   line"&tid=179<CR>
<--  action=blindtransfer&result=ok<CR>

Call

-->
   action=call&destination=14156479911&supervise=yes&audio_cpa=yes&tid=127<CR>
<--  action=call&tid=127&result=ok&cid=1511<CR>

-->
   action=call&destination=14156479911&supervise=yes&network_cpa=yes&tid=128<CR>
<--  action=call&tid=128&result=?&text="Dialing"<CR>
<--  action=call&tid=128&result=?&text="Waiting for Answer"<CR>
<--  action=call&tid=128&result=error&error_code=551&error_text="Busy"<CR>

CampOn

-->  action=campon&cid=1657&destination=302&ringback=60&text="Bob
   Smith"&tid=180<CR>
<--  action=campon&tid=180&result=ok<CR>

ConfCreate

-->  action=confcreate&maxsize=4&owner=301&tid=190<CR>
<--  action=confcreate&tid=190&result=ok&cfid=192<CR>

ConfDelete

-->  action=confdelete&cfid=192&tid=191<CR>
<--  action=confdelete&tid=191&result=ok<CR>

ConfJoin

-->  action=confjoin&cfid=192&cid=1655&duplex=full&owner=no&tid=199<CR>
<--  action=confjoin&tid=199&result=ok<CR>

ConfLeave

-->  action=confleave&cfid=192&cid=1655&tid=200<CR>
<--  action=confleave&tid=200&result=ok<CR>

ConfList

-->  action=conflist&cfid=192&tid=201&listtype=cid<CR>
<--  action=conflist&tid=201&result=ok&list=1655,1712,1811,1813<CR>

FwdRNA

-->  action=fwdrna&cid=1656&tid=202<CR>
<--  action=fwdrna&tid=202&result=ok<CR>

FwdBusy

-->  action=fwdbusy&cid=1656&tid=203<CR>
<--  action=fwdbusy&tid=203&result=ok<CR>

FwdCall

-->  action=fwdcall&cid=1656&destination=305&tid=204<CR>
<--  action=fwdcall&tid=204&result=ok<CR>

Hangup

-->  action=hangup&cid=1656&tid=205<CR>
<--  action=hangup&tid=205&result=ok<CR>

Hungup

-->  evt_type=call&event=hungup&cid=1656&tid=206<CR>

Hold

-->  action=hold&cid=1656&ringback=90&music=1&text=Bob Smith&tid=177<CR>
<--  action=hold&tid=177&result=ok<CR>

Newcall

-->
   evt_type=call&event=newcall&cid=1657&clid=4156479911&dnis=4158212356&tid=189<CR>

Park

-->  action=park&cid=1657&destination=304&parkaddress=901&tid=209<CR>
<--  action=park&tid=209&result=ok<CR>

CallState

-->  evt_type=call&event=callstate&cid=1657&status=holding<CR>

TransferStart

-->  action=transferstart&cid=123&destination=123&tid=190<CR>
<--  action=transferstart&tid=190&result=ok<CR>

TransferDrop

-->  action=transferdrop&cid=123&tid=190<CR>
<--  action=transferdrop&tid=190&result=ok<CR>

TransferComplete

-->  action=transfercomplete&cid=123&tid=190<CR>
<--  action=transfercomplete&tid=190&result=ok<CR>

Unhold

-->  action=unhold&cid=123&tid=190<CR>
<--  action=unhold&tid=190&result=ok<CR>


2.6 Line Related Actions And Events
-----------------------------------

As discussed in the introduction, lines refer to physical or virtual
circuits leading to another telephony server or to an external
telephone network. On larger telephone networks, the status of
individual lines is generally considered to be irrevelant. However, on
small systems, particularily key systems and intercoms, it is very
useful to be able to monitor and manipulate individual lines. This set
of actions and events permits client applications to emulate the
behavior of a key system or intercom (even if the system is really a
PBX or group of Centrex telephone lines).

For the most part, this section of the protocol is used to monitor the
status of physical and virtual telephone circuits leading to other
servers or to the outside world. There are, however, a couple of
actions which can be used to directly retrieve a call associated with
an outside line and map it directly to an address. This is the
equivalent of picking a call off a trunk on a key telephone system.

Message: 
GetLineParm
-----------
Description: 
This action is used to request a parameter associated with a specific line.
-----------
Message Type: 
Action
Parameters: 
line (req)
tid (req)
parameter (opt)
Expected Response: 
If a parameter is specified, the server replies with its contents, or
an error code (i.e. parameter not recognized). If no parameter is
specified, it responds with a list of parameters and their respective
values.

Message: 
SetLineParm
-----------
Description: 
This action is used to set a parameter associated with a specific line
-----------
Message Type: 
Action
Parameters: 
line (req)
tid (req)
parameter (req)
value (req)
Expected Response: 
Server replies with result=ok or result=error.

Message: 
LineState
---------
Description: 
This event is used to notify a client of a change of state in a monitored line.
---------
Message Type: 
Event
Parameters: 
line (req)
state (req)
Expected Response: 
None expected

Message: 
MonitorLine
-----------
Description: 
This action is used to register with the server to receive line related events
-----------
Message Type: 
Action
Parameters: 
line (req)
stop (opt)
tid (req)
Expected Response: 
Server replies with result=ok or result=error

Examples

GetLineParm

Following is an example of how the GetLineParm action is used to query
the server for information about a specific line.

-->  action=getlineparm&line=12&parameter=linetype&tid=187<CR>
<--  action=getlineparm&tid=187&parameter=linetype&value=E1R2MFC<CR>

SetLineParm

Following is an example of how the SetLineParm action is used to set a
parameter associated with a specific line.

-->  action=setlineparm&line=12&parameter=status&value=block&tid=188<CR>
<--  action=setlineparm&line=12&tid=188&result=error&error_code=504&error_text=Denied<CR>

LineState

Following is an example of how the LineState event is used to deliver
real-time state change information to a listening client.

-->  evt_type=line&event=linestate&line=12&status=ringing<CR>

MonitorLine

Following is an example of how the MonitorLine action is used to
register to receive line related events.

-->  action=monitorline&line=12&tid=189<CR>
<--  action=monitorline&tid=189&result=ok<CR>

-->  action=monitorline&line=12&stop=yes&tid=190<CR>
<--  action=monitorline&tid=190&result=ok<CR>

2.8 Standard List Of Line-Related Parameters
--------------------------------------------

Following is a list of standard parameters to be used in conjunction
with lines. 

Parameter: linetype
Description: Type of telephone line, used to provide descriptive
information for monitoring application.
Expected Values: Short (<20 char) alphanumeric string. 

Parameter: Status
Description: Current status of line
Expected Values: idle, block, ringing, dialing, talking, holding (not
all states will be supported by all systems)

EOF