1.3 Overview

The Telephony Remote Protocol enables a client to control telephony devices on the server through TAPI, and manage or administer them. The server software can be modeled as:

• TAPI service, which is independent of device specifics and depends on device-specific software for actual device control.

• Telephony service provider (TSP), which is device-specific software (including the device driver software). For more information, see [MSDN-TAPI-SP].

The TAPI service and the TSP can communicate with each other according to a well-defined interface, the Telephony Service Provider Interface (TSPI).

An Automatic Call Distribution (ACD) server is a combination of hardware and software that classifies, queues, and distributes incoming calls to agents or outgoing calls to lines.

The Server ACD application is a TAPI proxy application, which runs on the same server as the TSP. With a traditional ACD switch, the proxy application would interface to the switch's internal ACD and expose its operation. A software-based or "virtual" ACD proxy application would be fully responsible for the tracking of calls, queues, groups, and agents and would use the standard TAPI interfaces to control the switching hardware. Agent client applications will typically run on the individual agent's workstations and make use of the TAPI Remote Service Provider to communicate with the TAPISRV on the server machine, and hence the proxy application.

The Agent object represents an agent that is capable of handling calls. This agent is usually a person but can be an interactive voice response (IVR) or some other combination of software and hardware. Agents are vital to a call center; they are responsible for receiving and processing incoming calls and at times, for making outgoing calls to customers or prospects.

An Agent Handler represents software or hardware that is capable of passing calls to a group of agents. Typically, this is a proprietary switch that connects outside lines to telephones at agent stations.

An Agent Session represents an agent who has logged on and is qualified to handle calls for a particular ACD Group. An agent session is a dynamically created object that relates an agent to an ACD group for which the group will provide service, and also to the address where they will receive calls (turret, station, phone, and so on). Applications can use the agent session object to track agent activity in a particular ACD group.

An ACD group represents a class of calls that requires a particular type of handling. An ACD group services one or more queues. As incoming calls are classified, they are passed to queues that are associated with the relevant ACD group. A call coming off the queue is passed to an agent who has created an agent session object, indicating the agent is able to handle calls from that ACD group.

The Queue object represents a point in the ACD system where calls are temporarily held pending action. Access to a queue object allows an application to read a variety of standard statistics that relate to queue usage; however, access does not give an application the ability to control calls on the queue. Only applications that have access to the associated addresses and lines are able to control the calls on the queue.

Monitoring and control of ACD agent status on stations is supported through these functions: GetAgentCaps, GetAgentStatus, GetAgentGroupList, GetAgentActivityList, SetAgentGroup, SetAgentState, and SetAgentActivity.

Architecturally, ACD functionality is implemented in a server-based application. The client functions mentioned above, rather than mapping to the telephony service provider, are conveyed to a server application that has registered (using an option of Open) as a handler for such functions.

A line device represents a physical device such as a modem, voice board, fax board, or an Integrated Services Digital Network (ISDN) card that is connected to a network. Line devices support communications capabilities by allowing applications to send information to, or receive information from, a network. A line device contains a set of one or more homogeneous channels that can be used to establish calls. In Plain Old Telephone Service (POTS), exactly one channel exists on a line, and the channel is used exclusively for voice. Other technologies, such as ISDN, can support more than one channel on a single line.

An address represents a location on a network. The address itself is a string that identifies a location on a network. In the case of a telephone network, the address is a telephone number. Each channel can have its own address, which means a line could have as many addresses as it has channels. The exact relationship between channels and addresses depends on the underlying TSP implementation.

A client can obtain the number of addresses that are present on a line by using the GetDevCaps packet, which also provides information that is specific to the line device and common to all addresses on that line. Different addresses have different features, capabilities, and states. The client can access this information by sending the GetAddressCaps packet to the server.

A phone device represents characteristics of the phone device hardware rather than the connection to the network itself. Thus, operations such as increasing or decreasing the volume of audio that is sent or received, changing the ring mode, and so on are carried out by using phone device operations.

Many TAPI operations take a device ID or address ID parameter. The device ID can range from 0 to one less than the total number of devices that are reported by the corresponding Initialize packet. The address ID can range from 0 to one less than the number of addresses on that line device. The number of addresses on a line is obtained by sending the GetDevCaps packet for that line device.

This protocol consists of two interfaces: the tapsrv interface and the remotesp interface.

The tapsrv interface allows the client to send RPC packets to the server, causing TAPI operations to be executed on the server. The RPC packets in this specification are named for the specific TAPI operation that will be executed and are specified in section 2.2.

TAPI operations can complete either synchronously or asynchronously.

• Synchronous completion occurs when the requested TAPI operation is completely executed before the RPC function call returns to the client. This includes the case when the operation was not executed and an error is synchronously returned to the client.

  In Synchronous calls the client sends a TAPI32_MSG packet through the ClientRequest method with appropriate parameters in the packet. Depending on the request, the server fills the required values and sends back to client.

  For example, the client sends the GetDevCaps packet through the ClientRequest method to get the telephony capabilities of a specified line device. The GetDevCaps packet follows the structure of a TAPI32_MSG. The server fills the Req_Func field and VarData field of TAPI32_MSG with the result of the encapsulated telephony request and LINEDEVCAPS.

Figure 1: Synchronous Completion

• Asynchronous completion is when the RPC function call returns to the client while the request is still being executed (for example, the RPC function call returns while the client is dialing a number on a telephony device). A request ID is returned from the server when the asynchronous function call returns to the client. When the TAPI operation completes later, the server informs the client of completion along with the success or error status by using the same request ID to identify the operation being completed.

  In Asynchronous calls, the client sends a TAPI32_MSG packet through the ClientRequest method with the appropriate parameters in the packet. The server sends the request ID in the response to the ClientRequest method. On completion of the request the server sends back an ASYNCEVENTMSG through the RemoteSPEventProc method with same request ID. The server also calls the RemoteSPEventProc method with an ASYNCEVENTMSG to indicate any spontaneous event that is related to the TAPI operations on the server.

  For example, when the server offers an incoming call the client sends the Answer packet through the ClientRequest method to server for answering the call. The Answer packet follows the structure of the TAPI32_MSG. The server returns a positive number as the request ID for success. On completion of the requested operation the server calls the RemoteSPEventProc method with a LINE_REPLY packet which matches the request identifier previously returned for the Answer packet. LINE_REPLY follows the ASYNCEVENTMSG.

Figure 2: Asynchronous Completion

Section 2.2.4 specifies the packets that are sent as part of requests from client to server, asynchronous event packets from server to client indicating the completion of the requested operation or spontaneous event relating to TAPI operations on the server.

The remotesp interface, through the RemoteSPEventProc method, allows the server to notify the client of events that affect TAPI operations on the server. In RPC terminology, the server is acting as an "RPC client" on the remotesp interface because the server makes the RPC function call, and the client is acting as an "RPC server" on the remotesp interface. Unless otherwise mentioned, the term "server" is used to indicate a server in the TAPI sense in this specification. A server provides telephony devices that the client can use.

The events that are notified on the remotesp interface can be the completion of an asynchronous TAPI operation that is initiated earlier by the client or a spontaneous event that is related to TAPI operations on the server (for example, an incoming call on a telephony device).

The client can specify that the server use a mailslot mechanism instead of the remotesp interface for the server to notify the client of events. See the ClientAttach method for details. In this specification, a client that specifies a mailslot mechanism is called a connection-less client and a client that uses the remotesp interface is called a connection-oriented client.<1>

Connection-less clients use the Pull Model for getting events. In the pull model, the server informs the client that events are available for retrieval by writing a DWORD value to the client's mailslot, and the client retrieves events via the ClientRequest method.

Connection-oriented clients use the Push Model for getting events. In the push model, the server connects to the client on the remotesp interface by using the RemoteSPAttach method and calls the RemoteSPEventProc method on the client so that the client can process telephony events and completion notifications from the server.

Clients that connect to the server for administration of the telephony devices cannot be interested in events that occur on the telephony devices. These clients are called MMC clients in this specification and need not provide a mailslot mechanism or remotesp interface for the server to notify the client.

For more information about possible packet sequences to complete TAPI operations, see section 4.

For more information, see [MSDN-MSTelephonyOvw].