Internet Engineering Task Force F. M. Burg INTERNET-DRAFT A. Desimone draft-burg-pint-framework-00.txt K. T. Tewani AT&T Labs K. Vishwanathan Isochrone December 1997 An Architecture and Protocols for Initiation and Control of Telephone Calls From Terminals Connected to a CallBroker over a TCP/IP Connection Status of this Memo This document is an Internet-Draft. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." To view the entire list of current Internet-Drafts, please check the "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), ftp.nordu.net (Europe), munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast). Abstract This Internet Draft describes a framework, consistent with the model defined in the PINT group in the IETF, for controlling voice and voice-band data (e.g., FAX) calls on the PSTN from an IP Client. As such, it is solely concerned with call control and associated functions. It is not concerned with how to convert packetized voice into a form suitable for carriage over the PSTN. We introduce a logical entity (called CallBroker) that initiates and manages calls on the PSTN and controls the session on behalf of an IP Client to establish a telephone connection between two or more end points specified by the customer (i.e., IP Client). By way of this session, as mediated by the Call Broker, the customer can set up calls and receive notifications regarding the status of the calls and its participants. The interface between the CallBroker and the Service Control Function (as defined in the work on Intelligent Network Standards in ITU-T) in the Service Node (SN) in the PSTN will be defined and standardized as part of this activity. The interface between the IP client and the CallBroker also nees to be defined and standardized as part of this activity. This Internet Draft further advances the discussion on the issues involved Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 1] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 in interconnecting the Internet and the Public Switched Telephone Networks (PSTNs), focusing on potential interfaces between Internet-based entities and Intelligent Network (I.N.) entities. The services identified and discussed earlier (e.g., Click-to-Dial, Click-to-FAX, etc.) can be provided using the architecture identified here. Table of Contents 1. Introduction 2. Identification/definition of Services 3. High level architecture 4. IP Client to CallBroker Interface 5. CallBroker to IN Interface 1. Introduction This Internet Draft defines a framework, consistent with the model defined in the PINT Working Group in the IETF, for controlling voice and voice-band data (e.g., FAX), for providing Click-to-dial, etc. type of services identified in earlier drafts [1] and [2]. It is assumed here that the reader is familiar with the terminology defined in the Intelligent Network Standards [3] standardized by ITU-T. This document brings in the concept of a CallBroker as a logical entity that acts on behalf of a customer to set up sessions. The CallBroker acts as a mediator to make requests for PSTN resources. The sessions typically include initiation of calls between two or more end points specified by the user. In addition to its interactions with the PSTN/IN for call setup, the CallBroker is responsible for functions, as necessary, such as authentication, usage recording, etc. However, this Internet Draft is not concerned with the CallBroker's interactions with other entities to authenticate the user or pass usage information. This document discusses the API's at the two interfaces that need to be defined in order to provide the above services. The two interfaces are the Client-to-CallBroker and the interface between the CallBroker and the SCF Functional Entity (FE) in the Service Node (SN) in the PSTN. The architecture described in this document is consistent with the model defined in the PINT Working Group. The current scope of the PINT Working Group, however, is to define only the interface between the CallBroker (or Web Server as defined in [1]) and the SCF in the PSTN. As discussed earlier, this document is also proposing to define the interface between an IP Client and the CallBroker. The definition of such an interface will enable service providers to extend the architecture defined here to serve as a platform for other advanced/value added services (to be identified later). Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 2] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 In addition, the view to date in PINT is that the client is a Web browser, communicating via http with a Web server which in turn makes requests to establish connection(s) to a Service Control Function in the Service Node in the PSTN. The expanded view taken here is that the IP client is more general, and implements a protocol (described below) for communication with the CallBroker that allows full two-way communications, something lacking in the http/Web approach. For example, this is required for the cases where a called party hangs up and an indication may be necessary to be given to the IP Client about this status/progress. This is also necessary when conferencing to give an indication/status of various parties joining the call, etc. Thus, we believe that notification(s) from the network about the status/progress of the call (i.e., in general, asynchronous two-way communications) is necessary. and should be given to the IP Client. This, in turn, requires the functionality available on the CallBroker to PSTN interface be available to the IP client. 2. Identification/definition of Services Click to Dial: The premise here is that a user has generated a request at an IP Client, asking for a telephone call to be placed between two telephones connected to the PSTN. After receiving the IP Client's request, it is sent from the CallBroker to the SCF Functional Entity (FE) in the PSTN, and that FE instructs the Call Control Functional (CCF) Entity in the PSTN to place the call between the telephones whose number(s) were specified by the user. >From the customer perspective (i.e, the client), the request has been made; the implementation of that request is carried out by the CallBroker and the PSTN. Indications about the progress of satisfying that request shall be passed back to the IP Client. Conferencing: The premise here is that Client has requested a conference call be set up between three or more telephones. This request is sent from the CallBroker to the SCF Functional Entity (FE) in the PSTN, and that FE instructs the Call Control Functional (CCF) Entity in the PSTN to place the call between two or more telephones whose number(s) were specified by the user. From the customer perspective (i.e, the IP client), the request has been made; the implementation of that request is carried out solely by the CallBroker and the PSTN. One could consider the call between two telephones, as discussed above, is a specific case of a conference call between multiple telephones. Here, however, there would be more information to pass back to the IP Client regarding the status of participants on the call. Click to Fax:. The premise here is that Client has some data that it would like converted into a fax and sent to a fax machine connected to the PSTN. This service is more involved than Click to Dial, as it requires data to be collected from the IP Client, together with the fax number of the intended destination. The request and the data to be sent are passed to the PSTN in a form suitable for sending as a fax, which initiates the call to the destination fax machine, and sends the generated facsimile to it. In all of the examples above, it is necessary that indication(s) be given to the IP Client regarding the progress/status of the call. Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 3] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 3. High Level Architecture A high level architecture depicting various logical entities and the Interfaces among these logical Entities and the IP Client is shown in Figure 1. ________________ / 1 _____ / 2 _____ /|________________| |________| | PSTN |____| \ |____| Call \ / SCF\ Broker \ / SN \ \_____________ / \ / \ / \ __ __ /\ /\ Calling Participant Party (Called Party) *Interfaces Labeled 1 and 2 above are considered part of this activity. Figure 1: High Level Architecture of the various logical Entities of the Call Broker Model The CallBroker, in addition to the initiation and control of calls on behalf of the user, performs additional functions. These functions include authenticating the IP Client, usage recording, management of the session for the IP Client for the telephony call. The notion of the session requires that a client state machine be maintained in the CallBroker. This also helps in notifying the IP Client about the status/progress of the requests generated from the IP Client. >From the perspective of the IP Client, the logical entities needed for the above functions are within the CallBroker and are as shown in Figure 2 below. These correspond to the functions already discussed: Usage Recording Function, Session Management Function, Bridge, and the Authentication Function. The fact that some of these functions may be physically separate Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 4] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 from the CallBroker (such as the Bridge being in the PSTN), is not inconsistent witht the general view adopted here. Thus, the CallBroker Model mediates requests for network services and enables us to define various value added services in the future. llllllllllllllll l l l Call Broker l Authentication l Server l Function l ______ l Interface 2a ______ l | |x x xlx x x x x x x x x | | l |______|x l |____| l x x l l x xl Interface 2b lSession State lx l Mnmgt. x l x Usage Recording l Function l x Function l _______ x l x ______ l | | l x x x | | l |_____| xl |____| llllllllllllllll x x Interface 2c x _______ | | |_____| Bridge Figure 2: Functional Entities in the Call Broker Various interfaces (i.e., 2a, 2b, 2c in Figure 2) between different functional entities in the CallBroker may also be standardized. The Session State Management Function may be physically realized as part of the CallBroker Server. IP Client to CallBroker Interface Communication on the IP Client to CallBroker Interface (Interface 1 in Figure 1) is a simple ASCII based protocol running directly on TCP. The messages on this interface are primarily requests from the client to the CallBroker, responses from the CallBroker to the IP client responding to the requests and unsolicited events from the CallBroker to the IP client. Since the communication is not strictly transaction oriented, traditional encapsulation protocols like HTTP cannot be used. There has been some ongoing work attempting to use multiple concurrent HTTP POST requests to support event delivery but, without too much difficulty, the ASCII protocol specified here can easily be mapped to the POST payload of the HTTP protocol. Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 5] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 4. Protocol 4.1.1 Basic Format The basic format of the protocol is as follows. [header]< < [body]< < < The header and body of the protocol are separated by 2 line feed characters. The format of the header and the body is described below. Line feed characters in the header or body will be escaped using simple URL encoding. 4.1.2 Header [session-id | 0]< [message-id]< [version-info]< All CallBroker transactions are identified by sessions. A session is not necessarily governed by a TCP session. If the IP client is attempting to initiate a new session with the CallBroker the session-id field is populated with '0' to indicate session creation request. Every session request needs to be accompanied by sufficient information regarding authentication for the CallBroker to create the session. Message-id represents the operation of the message. An appendix is provided describing the different message-ids supported by the current release of the CallBroker system. Version-info contains optional version information of the protocol. This is to aid possible version mismatch detection and graceful error recovery. 4.1.3 Body The body of the protocol messages consist of name value pairs. These name-value pairs are interpreted with reference to the message-id which signifies the operation to be performed by the CallBroker. 4.2 APIs exposed to the IP client The APIs exposed to the IP client of the CallBroker are distinct and different from the APIs that the CallBroker uses from the different supporting subsystems including the authentication subsystem and the usage Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 6] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 recording subsystem. The IP client APIs enable clients to effectively control voice conferencing. The APIs described below is an initial set of APIs identified for the application in mind. The API is implemented as an asynchronous library which involves the user of the API to implement the callback interface to support asynchronous completion of the IP client requests. 4.2.1 Session creation CreateSession STATUS CreateSession (AuthInfo authinfo, Phonenumber host_`phone) ; CB_CreateSession void CB_CreateSession (String sessionId, ErrorMessage err) ; 4.2.2 Adding parties to an existing conference AddParty STATUS AddParty (String session_id, Phonenumber participant) ; CB_AddParty void CB_AddParty (String session_id, Phonenumber participant, ErrorMessage err) ; 4.2.3 Deleting participants from a conference DropParty STATUS DropParty (String session_id, Phonenumber participant) ; CB_DropParty void CB_DropParty (String session_id, Phonenumber participant, ErrorMessage err) ; 4.2.4 Destroying sessions DestroySession STATUS DestroySession (String session_id) ; CB_DestroySession void CB_DestroySession (String session_id, ErrorMessage err) ; 4.2.5 Events Currently the only event supported is the phone hangup event for any of the participants in the session. The current implementation reports this asynchronous event through the overloaded CB_DropParty callback function. Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 7] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 5. CallBroker to IN Interface 5.1 Voice-Bridge Control API The Voice Bridge Control API is used by CallBroker applications to access voice bridging functionality. The API distinguishes between sessions and calls. Calls represent actual voice calls placed from/to the voice bridge. These calls can be grouped together in sessions. All the calls that belong to a session are bridged. Calls have a significance outside the scope of sessions. Every call can be associated with multiple sessions with different weights at the same time. The advantage of this approach is the ability to support concepts like whispering in a conference call. Calls can also be dropped from a conference session and bridged together in a new session to give the notion of a sub-conference. These calls can later be re-added to the main conference session. The API functions of the voice bridge can be classified into five groups: initialization and termination routines, the control functions, the response callback functions, the event notification functions and the socket event interest request functions. The control functions are used to issue commands to the bridge for requesting a new session etc. We provide some examples of the control fucntions here: a complete description is being developed. 5.1.1 CreateSession CreateSession (SESSION_HANDLE* session_handle, void* param) ; Parameters session_handle handle to the new session to be created param a callback parameter that is passed back uninterpreted to CB_CreateSession Remarks Creates a new bridge session. If this call completes asynchronously, it returns pending and later completes the session creation and returns the new session through the function CB_CreateSession. At any time multiple session creation requests can be pending. The user can make use of the callback parameter param to identify the request that has completed. 5.1.2 DestroySession DestroySession (SESSION_HANDLE session_handle) ; Parameters session_handle handle of the session to be destroyed Remarks Destroys the bridge session specified by session_handle. This call returns synchronously. Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 8] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 5.1.3 CreateCall CreateCall (CALL_HANDLE* call_handle, void* param) ; Parameters call_handle handle to the new call to be created param a callback parameter that is passed back uninterpreted to CB_CreateCall Return Values SUCCESS on successful completion, PENDING if the operation is pending and FAILURE if the operation failed. If the operation fails the error code is included in the status code. Possible error codes: ERR_INSUFFICIENT_RESOURCES - insufficient resources to create new call. Remarks Creates a new voice call. If the function call returns pending the completion is signaled through the function CB_CreateCall. At any time multiple call creation requests can be active. The user can determine which of the identity of the completing request through the callback parameter param. The hardware port on the bridge is allocated but not yet in use. This call is used to reserve all the hardware resources necessary to make a voice call. The voice call is originated by the DialCall API function. 5.1.4 DestroyCall DestroyCall ( CALL_HANDLE call_handle ) ; Parameters call_handle handle to the call to be destroyed Return Values SUCCESS on successful completion and FAILURE if the operation failed. If the operation fails the error code is included in the status code. Possible error codes: ERR_INVALID_PARMS - the call handle specified is incorrect. Remarks Destroys the voice call specified by call_handle and all resources associated with it. 5.1.5 ConnectCall ConnectCall ( CALL_HANDLE call_handle, unsigned char use_caller_phone, PHONE_NUMBER caller_phone_number, PHONE_NUMBER callee_phone_number, unsigned int timeout, void *param ) ; Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 9] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 Parameters call_handle the call handle on which the dialing is to be done use_caller_phone If set to non-zero, the caller's phone number is made available to the callee, else the caller identification is not sent. caller_phone_number The phone number of the originator of the call callee_phone_number The phone number to be dialed, the callee. timeout the number of seconds to wait for an answer after the ringing has commenced param a callback parameter that is passed back uninterpreted to CB_ConnectCall Return Values SUCCESS on successful completion, PENDING if the operation is pending and FAILURE if the operation failed. If the operation fails the error code is included in the status code. Possible error codes: ERR_LINE_BUSY call could not complete since the line was busy. ERR_LINE_NO_ANSWER no answer after timeout seconds ERR_INVALID_PARMS the call handle or phone number specified is incorrect. Remarks This function is used to dial a phone number on a specific call handle. Until the phone number is actually dialed the hardware port on the bridge is allocated but not used. If the call does not complete synchronously, the bridge provider signals completion of this call by calling the callback function CB_ConnectCall. 5.1.6 DisconnectCall DisconnectCall ( CALL_HANDLE call_handle ) ; Parameters call_handle the call handle on which the call is to be disconnected. Return Values SUCCESS on successful completion, PENDING if the operation is pending and FAILURE if the operation failed. If the operation fails the error code is included in the status code. Possible error codes: ERR_INVALID_PARMS the call handle specified is incorrect. ERR_CALL_INACTIVE the call handle specified is not connected. Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 10] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 Remarks Used to disconnect an active call on a given call handle. The call handle itself is still valid and can be used to originate other calls. If the call does not complete synchronously, the bridge provider signals completion of this call by calling the callback function CB_DisconnectCall.. Note: The call_handle is valid even after the call has been disconnected. The user of the API is free to reuse the call_handle in another ConnectCall operation. 5.1.7 AddCallsToSession AddCallsToSession ( SESSION_HANDLE session_handle, unsigned int num_calls, CALL_HANDLE* call_handles, void *param ) ; Parameters session_handle session to which calls are to be added num_calls number of call handles to be added call_handles array containing num_calls call handles to be added to the session. param a callback parameter that is passed back uninterpreted to CB_AddCallsToSession Return Values SUCCESS on successful completion, PENDING if the operation is pending and FAILURE if the operation failed. If the operation fails the error code is included in the status code. Possible error codes: ERR_INVALID_PARMS the call handle or session handle specified is invalid. Remarks This function is used to add weighted call handles to a session. The significance of adding weights to a call handle is to permit bridging of different users with different characteristics. The weight controls the voice input from the particular call handle that it is associated with. Call handles with a weight of WEIGHT_ZERO cannot be heard by other members of a session while call handles with a weight of WEIGHT_MAX are heard more loudly than call handles with a weight of WEIGHT_HALF. All call handles belonging to a session at any point of time are 'bridged'. A call handle can be participating in multiple sessions with different weights at the same time. 5.1. 8 DropCallsFromSession DropCallsFromSession ( SESSION_HANDLE session_handle, UINT num_calls, CALL_HANDLE* call_handles, void *param ) ; Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 11] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 Parameters session_handle handle to the new call to be created num_calls number of call handles to be added call_handles array containing num_calls call handles to be dropped from the session. param a callback parameter that is passed back uninterpreted to CB_DropCallsFromSession Return Values SUCCESS on successful completion, PENDING if the operation is pending and FAILURE if the operation failed. If the operation fails the error code is included in the status code. Possible error codes: ERR_INVALID_PARMS the call handle or session handle specified is invalid. Remarks This function is used to drop voice calls from a bridged session. The calls themselves still remain active and can be made part of a new session to support the concept of whispering in a multi-party conference. References 1. Fayenberg, et. al., "A proposal for Internet and Public Switched Telephone Networks (PSTN) Internetworking", , March 1997. 2. Conroy, et. al., "Analysis of Services and Interfaces used when Interworking Between the Internet and the Intelligent Network (I.N.)", , July 1997. 3. ITU-T Q.12xx Series Recommendations, Geneva, 1995. 4. Petrack, "IP Access to PSTN Services: Basic Service Requirements, Definitions, and Architecture", , Nov. 1997. Author's Addresses F. M. Burg AT&T Labs Room 1N-117 307 Middletown Lincroft Road Lincroft, NJ 07738 USA email: fburg@hogpb.att.com Tel: +1 732 576 4322 FAX: +1 732 576 4317 Burg/Desimone/Tewani/Vishwanathan Expires 5/98 [Page 12] INTERNET-DRAFT draft-burg-pint-framework-00.txt Dec. 1997 A. DeSimone AT&T Labs Room 1N-113 307 Middletown Lincroft Road Lincroft, NJ 07738 USA email: tds@att.com Tel: +1 732 576 5655 FAX: +1 732 576 4317 Kamlesh T. Tewani AT&T Labs Room 1K-334 101, Crawfords Corner Rd. HOLMDEL NJ - 07733 USA email: tewani@att.com Tel: +1 732 949 5369 Fax: +1 732 949 8569 Kumar Vishwanathan Isochrone Tel: +1 732 544 5477 e-mail: kumar@isochrone.com