Internet Engineering Task Force T. Kanai INTERNET DRAFT Fujitsu Laboratories of America, Inc. Expires: 25 Dec 1999 M. Morinaga N. Fukuyama M. Matsuda Fujitsu Laboratories, Ltd. 25 Jun. 1999 Simple Phone Control Protocol (SPCP) Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 except that the right to produce derivative works is not granted. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright Notice Copyright (C) The Internet Society (1999). All Rights Reserved. Abstract This specification defines Simple Phone Control Protocol (SPCP) as an application-level protocol, which allows network devices, such as PCs, to control IP telephones. This document explains the protocol specification, how to use SPCP, and how to configure a system that uses SPCP. Kanai/Morinaga/Fukuyama/Matsuda [Page 1] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 Terminology In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119. Table of Contents 1. Introduction ............................................ 5 1.1 Purpose .............................................. 5 1.2 Technical Terms ...................................... 5 1.3 Outline of protocol .................................. 5 1.4 Example of Telephony Services with SPCP .............. 6 2. SPCP General Specification .............................. 8 2.1 General Grammar ...................................... 8 2.1.1 Basic Rules ...................................... 8 2.1.2 SPCP Message ..................................... 8 2.1.3 SPCP Request ..................................... 9 2.1.4 SPCP Response .................................... 10 2.1.5 SPCP Notification ................................ 11 2.1.6 Information ...................................... 12 2.1.7 Message Length ................................... 12 2.2 Communication Sequence ............................... 12 2.2.1 Basic sequence ................................... 13 2.2.2 Notification sequence ............................ 13 2.2.3 In case of delaying on response .................. 13 2.2.4 Establish and Release Session .................... 14 2.2.5 Check Server Presence ............................ 16 2.2.6 Proprietary Message Sequence ..................... 16 3. SPCP Messages ........................................... 16 3.1 SPCP-REQUEST ......................................... 17 3.1.1 Logon ............................................ 17 3.1.2 Exit ............................................. 17 3.1.3 Call ............................................. 18 3.1.4 Dial ............................................. 19 3.1.5 Answer ........................................... 19 3.1.6 Drop ............................................. 20 3.1.7 Hold ............................................. 20 3.1.8 Park ............................................. 21 3.1.9 Transfer ......................................... 22 3.1.10 Forward ......................................... 22 3.1.11 Callreject ...................................... 23 3.1.12 Conference ...................................... 23 3.1.13 Data ............................................ 24 3.1.14 Indicate ........................................ 25 3.1.15 Qoscontrol ...................................... 26 3.1.16 Parma ........................................... 26 3.1.17 Do .............................................. 27 Kanai/Morinaga/Fukuyama/Matsuda [Page 2] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 3.1.18 Name ............................................ 28 3.1.19 Nop ............................................. 28 3.1.20 Selftest ........................................ 29 3.1.21 Proprietary Command ............................. 29 3.2 SPCP-NOTICE .......................................... 30 3.2.1 Opened ........................................... 30 3.2.2 Calling .......................................... 30 3.2.3 Connect .......................................... 31 3.2.4 Offering ......................................... 31 3.2.5 Busy ............................................. 32 3.2.6 Disconnect ....................................... 32 3.2.7 Indicate-info .................................... 33 3.2.8 Done ............................................. 33 3.2.9 Progress ......................................... 34 3.2.10 Proprietary Command ............................. 34 3.3 SPCP-RESPONSE ........................................ 35 3.3.1 2xx (OK) ......................................... 35 3.3.2 3xx (OK) ......................................... 35 3.3.3 4xx (Error) ...................................... 36 3.3.4 5xx (Fatal error) ................................ 36 3.3.5 9xx (Proprietary response) ....................... 36 3.4 INFORMATION .......................................... 37 3.4.1 ATTRIBUTE-LINE ................................... 37 3.4.2.1 media-type ..................................... 37 3.4.2.2 spcp-version ................................... 38 3.4.2.3 length ......................................... 38 3.4.2.4 timeout ........................................ 38 3.4.2.5 auth-code ...................................... 39 3.4.2.6 cp-addr ........................................ 39 3.4.2.7 call-reference ................................. 39 3.4.2.8 flag ........................................... 40 3.4.2.9 name-type ...................................... 40 3.4.2.10 function-detect ............................... 40 3.4.2.11 X- ........................................... 41 4. Implementation Example .................................. 41 4.1 System configuration example ......................... 41 4.1.1 IP telephone ..................................... 42 4.1.2 Internet Telephony Controller .................... 43 4.1.3 Directory server ................................. 44 4.1.4 DHCP server ...................................... 44 4.2 IP Telephone system implementation example ........... 45 4.2.1 Simplest implementation .......................... 45 4.2.2 LDAP server implementation ....................... 45 5. Security ................................................ 49 5.1 Authentication ....................................... 50 5.1.1 Password encryption method ....................... 50 5.1.2 Example of authentication sequence ............... 50 5.2 Security for data transmission ....................... 52 Kanai/Morinaga/Fukuyama/Matsuda [Page 3] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 5.2.1 Security in the transport or lower layer ......... 52 5.2.2 Security in the application layer ................ 52 6. Appendix A - Reference implementation of SPCP based on H.323 ................................................... 52 6.1 IP Telephone system based on a Gatekeeper ............ 52 6.2 Example of SPCP call control ......................... 54 6.2.1 Make a call ...................................... 54 6.2.2 Call transfer .................................... 55 6.2.3 Switch a held call and an ongoing call ........... 57 6.2.4 Call forward ..................................... 58 7. Appendix B - Network Information in IP Telephone ........ 59 7.1 IP address of itself ................................. 59 7.2 IP address of Gatekeeper ............................. 59 7.3 Alias of itself (Telephone Number) ................... 60 8. Appendix C - Reference of SPCP message .................. 60 8.1 SPCP-REQUEST ......................................... 60 8.2 SPCP-NOTICE .......................................... 62 8.3 SPCP-RESPONSE ........................................ 63 8.4 INFORMATION attribute type and value ................. 63 9. Appendix D - Example of Parameters and Values ........... 64 10. References ............................................. 66 11. Authors' Addresses ..................................... 67 Kanai/Morinaga/Fukuyama/Matsuda [Page 4] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 1. Introduction 1.1 Purpose This specification defines Simple Phone Control Protocol (SPCP) as an application-level protocol which allows network devices (such as PCs) to control IP telephones. Using this protocol, an user can control his/her IP telephone from his/her PC on which an Intellectual telephone control application runs. 1.2 Technical Terms The following technical terms are used in this specification: + Terminal: Network device or application program + Message: Data that is transferred between applications + Request message: Message for requesting another terminal to execute processing + Response message: Message used to respond to requested processing + Notification message: Message to report status to another terminal + Client: Terminal that starts connection establishment for sending a request message + Server: Terminal that receives a connection request in order to return a response message + IP telephone: Network device for voice communication which is connected directly to the IP network. Though such a device works like the legacy telephone it isn't based on the ordinary telephone proto- col but on the IP protocol. For details, see Section 4.1.1. 1.3 Outline of protocol Connecting a computer to an IP telephone can enhance telephony Kanai/Morinaga/Fukuyama/Matsuda [Page 5] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 services. The computer would control the IP telephone's basic func- tions such as making a call, receiving a call and so on. SPCP is a means of connecting the IP telephone and the computer and exchanging data for enhanced services. Interaction between the IP telephone and the computer is client- server and IP based. There are two types of communication. One is a request message sequence initiated by on the client side. The other is a notification message sequence initiated on the server side. In the request message sequence, the client composes a message based on its request and sends it to the server. The server executes the requested process and then composes a return message with the result to the client. Unlike the request message sequence, the notification message sequence is one way. The server composes a message reflecting a state change and sends it to the client. In this document, the term 'client' corresponds to the computer and the term 'server' corresponds to the IP telephone. However, this definition does not restrict the actual protocol usage. It is up to users of the protocol to decide their system configurations. Before establishing a session for SPCP communication, a specific client - server interchange is necessary. This interchange, including user certification, terminal information exchange, and so on, can resolve security and connectivity issues -- even through a network with complicated topology. SPCP consists of dozens of message sets which are based on an abstract model of the call process in the IP telephone. Various IP telephone services are available by combining these message sets. All SPCP messages are described in a text-based HTTP/1.1 (RFC 2068 [1]) like syntax. Each message contains a data-representing part for- matted like MIME (RFC 1521 [2]) This enables the message to carry various types of data. However, it is not necessarily compliant with those protocols. 1.4 Example of Telephony Services with SPCP Various telephony services could be made available by using SPCP. Here are some examples: + Call control services: Services, in which the computer operates a call on the IP Kanai/Morinaga/Fukuyama/Matsuda [Page 6] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 telephone. (-) The computer commands the IP telephone to place an out- going call or receive an incoming call. (-) The IP telephone provides notification of call events to the computer. (-) Call control is linked to a scheduling service (-) Call control is linked to a directory service + Configuration control services Services, in which the computer operates the IP telephone confi- guration. (-) The computer modifies a short dial list in the IP tele- phone. (-) The computer modifies a response message in the IP telephone voice message module. (-) The computer modifies key configurations in the IP telephone. + Data transaction services Services, in which the computer exchanges some data with the IP telephone. (-) The computer records a conversation taking place on the IP telephone. (-) The computer retrieves a voice message in the IP tele- phone voice message module. (-) The computer receives FAX data coming through the IP telephone. + Device control services Services, in which the computer controls devices on the IP tele- phone. (-) The computer adjusts receiver/microphone/speaker volume on the IP telephone. Kanai/Morinaga/Fukuyama/Matsuda [Page 7] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 (-) The computer controls lamps on the IP telephone. (-) The computer controls startup and shutdown of the IP telephone. 2. SPCP General Specification 2.1 General Grammar SPCP message is text-formatted so that the user can easily compose and issue messages online with Telnet. SPCP messages are described in the following syntax, which is compliant to Augmented BNF (ABNF) (RFC 2234 [3]). 2.1.1 Basic Rules The following rules are used throughout this specification to describe basic parsing constructs. OCTET = CHAR = UPALPHA = LOALPHA = ALPHA = UPALPHA | LOALPHA DIGIT = HEXDIGIT = "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f" | DIGIT CTL = CR = LF = CRLF = CR LF SP = HTAB = WSP = 1* DELIMITER = ":" WSP <"> = PCHAR = > STRING = 1*PCHAR | <">*<"> PHRASE = * 2.1.2 SPCP Message SPCP messages are classified into three types; Request, Response and Notification. Kanai/Morinaga/Fukuyama/Matsuda [Page 8] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 SPCP-MESSAGE = SPCP-REQUST ; Request / SPCP-RESPONSE ; Response / SPCP-NOTIFICATION ; Notification 2.1.3 SPCP Request (SPCP-REQUEST) The client issues an SPCP request to the server to request operation. An SPCP request consists of a command line and an information part. The command line part contains a command method and a parameter. The command method is extensible by pre-pending "X-", as in "X-my com- mand". SPCP-REQUEST = REQUEST-LINE ; Request command line *INFORMATION ; Information CRLF REQUEST-LINE = REQUEST *(WSP PARAM) CRLF REQUEST = "logon" ; authentication / "exit" ; release a session / "call" ; make a call / "dial" ; send dialed digits / "answer" ; answer an incoming call / "drop" ; hung up a call / "hold" ; hold a call / "park" ; park a call / "transfer" ; transfer a call / "forward" ; forward an incoming call / "callreject" ; reject an incoming call / "conference" ; establish a conference call / "data" ; send/receive data / "indicate" ; inquire notification / "qoscontrol" ; control QoS / "param" ; set/get parameter / "do" ; order function / "name" ; inquire product name / "nop" ; check presence / "selftest" ; self-test / "X-" 1*PCHAR ; (extensible command) PARAM = STRING + Example (1) : Authentication "logon 1111 6c4afb8f1579edb2b2d27e3646fee09f " Kanai/Morinaga/Fukuyama/Matsuda [Page 9] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 + Example (2) : Parameters "param put key-data media-type: text/plain length: 46 : 031 speaker on/off 032 receiver on/off " + Example (3) : Hung up "exit " 2.1.4 SPCP Response (SPCP-RESPONSE) The server issues an SPCP response to a client to notify the client of the result of an operation. An SPCP response consists of command line and information parts. The command line part contains a response method and a comment. A comment part allows users to add an explana- tion of the command. The response method is extensible by pre- pending "9". SPCP-RESPONSE = RESPONSE-LINE ; Response command line *INFORMATION ; Information CRLF RESPONSE-LINE = RESPONSE DELIMITER [COMMENT] CRLF RESPONSE = ("2" DIGIT DIGIT) ; success / ("3" DIGIT DIGIT) ; success (needs additional command) / ("4" DIGIT DIGIT) ; error / ("5" DIGIT DIGIT) ; error (fatal) / ("9" DIGIT DIGIT) ; (extensible response) COMMENT = PHRASE + Example (1): success (authentication) "200: OK (authentication is successful.) " Kanai/Morinaga/Fukuyama/Matsuda [Page 10] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 + Example (2): success (get data) "201: OK (you got data) length: 46 media-type: text/plain : 031 speaker on/off off 032 receiver on/off on " + Example (3): error (authentication, illegal parameter) "415: need parameter (user-id) " 2.1.5 SPCP Notification (SPCP-NOTIFICATION) The server issues an SPCP notification to the client to provide notification of an event. An SPCP notification consists of notice line and information parts. The notice line part contains a notice method and a comment. The comment part allows users to add an expla- nation of the notice. The notice method is extensible by pre-pending "X-", as in "X-my notice". SPCP-NOTIFICATION = NOTICE-LINE ; Notice command line *INFORMATION ; Information CRLF NOTICE-LINE = NOTICE DELIMITER [COMMENT] CRLF NOTICE = "opened" ; session established / "calling" ; calling a recipient / "connect" ; recipient answered / "offering" ; incoming call received / "busy" ; recipient is busy / "disconnect" ; call disconnected / "indicate-info" ; information notice / "done" ; key/lamp data notice / "progress" ; progress of process notice / "X-" 1*PCHAR ; (extensible notice method) COMMENT = PHRASE + Example (1): key input notice Kanai/Morinaga/Fukuyama/Matsuda [Page 11] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 "keydetect: key is pushed. key-identifier: 001 done-operation: push " + Example (2): recipient answer a call "connect: the line is connected. call-id: 1031 " 2.1.6 Information (INFORMATION) An information part transmits object data. The information part con- sists of attribute line and data parts. The attribute line part con- tains an attribute type method and an attribute type value. The type method is extensible by pre-pending "X-", as in "X-my type". INFORMATION = *ATTRIBUTE-LINE ; Attribute line ":" CRLF *DATA ; Data ATTRIBUTE-LINE = ATTR-TYPE DELIMITER ATTR-VALUE CRLF ATTR-TYPE = "media-type" ; media type / "spcp-version"; SPCP version / "length" ; data length / "timeout" ; time limit / "auth-code" ; challenge code for authentication / "cp-addr" ; calling party address / "call-reference" ; call reference number / "command" ; current process information / "flag" ; repeat indicator (start/stop) / "name-type" ; product name / "function-detect" ; key/lamp information / "X-" 1*PCHAR ; (extensible attribute type) 2.1.7 Message Length Length of REQUEST-LINE, RESPONSE-LINE, NOTICE-LINE, and ATTRIBUTE- LINE must not exceed 256 bytes. 2.2 Communication Sequence Kanai/Morinaga/Fukuyama/Matsuda [Page 12] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 2.2.1 Basic sequence The most basic SPCP sequence is as follows; the client issues an SPCP-REQUEST to the server, then the server processes the request and responds with an SPCP-RESPONSE to the client. Client Server | SPCP-REQUEST | |==============================>| | | | SPCP-RESPONSE | |<==============================| | | 2.2.2 Notification sequence The server notifies the client of the server's status by using an SPCP-NOTICE. The client need not respond to the SPCP-NOTICSE. Client Server | SPCP-NOTICE | |<==============================| | | 2.2.3 In case of delaying on response If the server takes a long time to process an SPCP-REQUEST, it must notify the client midway through the process by using an SPCP-NOTICE. When the process completes, the server must issue an SPCP-RESPONSE to the client. Chapter 3 explains this sequence in detail. Client Server | SPCP-REQUEST | |==============================>| | | | SPCP-NOTICE | |<==============================| | . | | : | | | | SPCP-NOTICE | |<==============================| | | | SPCP-RESPONSE | |<==============================| | | Kanai/Morinaga/Fukuyama/Matsuda [Page 13] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 2.2.4 Establish and Release Session Before sending and receiving SPCP messages, the server and client must establish an SPCP session. The SPCP transport layer uses a TCP connection. Once the session is established, the client and server process user authentication and exchange terminal information. The sequence to establish and release a session is as follows; + Open a well-known TCP port The server must execute the LISTEN command to open a "well- known" TCP port. + Establish a TCP connection When the server receives a CONNECT request from the client through the well-known port using the LISTEN command, it must establish a TCP connection immediately. Once the server sends back an ACCEPT in response to the client's CONNECT request, a TCP connection is established. A server should be able to main- tain multiple simultaneous SPCP sessions. + Provide information Right after the SPCP session is established, the server must provide its information, such as SPCP version, product name, and a character string for user certification, to the client with an SPCP-NOTICE Open message (see Section 3.2.1). + Authentication Next the client must process user authentication. User authenti- cation must be compliant with CRAM-MD5 (RFC 2195 [4]). (This is a challenge-response authentication method.) The client issues an SPCP-REQUEST Logon message (see Section 3.1.1) with the char- acter string, which was contained in the previous SPCP-NOTICE Open message, and a password, which is given by an end user. If the user authentication is unsuccessful, the server doesn't pro- cess other messages except for the SPCP-REQUEST Exit message (see Section 3.1.2). + Register client information Following successful user authentication, the client must regis- ter its information, such as a product name and an SPCP version, with the server using an SPCP-REQUEST Name message (see Section 3.1.19). Once the registration is successful an SPCP session is established and then the main SPCP sequence will start. + Release the session After the main SPCP sequence, the client issues an SPCP-REQUEST Exit message to release the SPCP session. When the server receives the SPCP-REQUEST Exit message, it must immediately stop Kanai/Morinaga/Fukuyama/Matsuda [Page 14] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 processing requests. Once the session is successfully released , any SPCP message is invalid. + Release TCP connection Finally the client must release the TCP connection. The SPCP session establishment and release sequence is as fol- lows: Client Server | | | Listening well-known port | | | (TCP:connet) | |------------------------------>| | | | (TCP:accept) | |<------------------------------| | | | SPCP-NOTICE(opened) | |<==============================| | | | SPCP-REQUEST(logon) | |==============================>| | | | SPCP-RESPONSE(OK) | |<==============================| | | | SPCP-REQUEST(name) | |==============================>| | | | SPCP-RESPONSE(OK) | |<==============================| | | ~~~ ~~~ (SPCP session is valid) ~~~ ~~~ | SPCP-REQUEST(exit) | |==============================>| | | | SPCP-RESPONSE(OK) | |<==============================| | | | (TCP:close) | |------------------------------>| | | Kanai/Morinaga/Fukuyama/Matsuda [Page 15] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 | (TCP:close) | |<------------------------------| | | 2.2.5 Check Server Presence The client can check whether the server is working or not with the SPCP-REQUEST Nop message (see Section 3.1.18). If the server is available, it must respond it with the SPCP-REQUEST OK message immediately. If the server is not available, it does not send any response to the client. Using this command the client can know if the server is present by requesting a response. Note that the client should allow enough of an interval for the network delay. The sequence used to check server presence might be as follows; Client Server | SPCP-REQUEST(NOP) | |==============================>| | | | SPCP-RESPONSE(OK) | |<==============================| | | 2.2.6 Proprietary Message Sequence Implementers can define their proprietary messages by generating an SPCP-REQUEST or SPCP-NOTICE with a pre-pended "X-", or generating an SPCP-RESPONSE with a pended "9". Since these messages are proprietary for a particular implementation, implementers must be responsible for the process that is followed by the messages. If a recipient doesn't know the meaning of the messages, it need not do anything with those messages, but it is still must respond to them by sending an SPCP-RESPONSE message. Terminal Terminal | SPCP-MESSAGE(X-***) | |<==============================| | | | SPCP-RESPONSE | |==============================>| | | 3. SPCP Messages Kanai/Morinaga/Fukuyama/Matsuda [Page 16] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 This chapter defines the details of formating and processing the con- tent of SPCP messages. 3.1 SPCP-REQUEST SPCP-REQUEST is a message which a client sends a server to request a particular process. 3.1.1 Logon (SPCP-LOGON-REQUEST) [MUST] The "logon" command is used for user authentication. Here the syntax of this message is described in detail: + Message format SPCP-LOGON-REQUEST = "logon" [WSP USER-NAME [WSP AUTH-RESPONSE]] CRLF CRLF USER-NAME = STRING ; Character string indicating user name AUTH-RESPONSE = 1*HEXDIG ; Response to CHALLENGE CODE (See Chapter 5.) + Response message SPCP-LOGON-RESPONSE = "200" ; OK (Authorized) = "430" ; Error (Unauthorized) + Necessary process When a server receives an SPCP-LOGON-REQUEST message, it executes the process required to check the authenticity of the client with the USER-NAME and the AUTH-RESPONSE part in of message. Then, the server sends back a result with an SPCP-LOGON-RESPONSE message. The actual authentication mechanism is up to implementers. So, depending upon the implementation, the server might not care about USER-NAME and AUTH-RESPONSE. 3.1.2 Exit (SPCP-EXIT-REQUEST) [MUST] The "exit" command is used for releasing an SPCP session. Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: + Message format Kanai/Morinaga/Fukuyama/Matsuda [Page 17] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 SPCP-EXIT-REQUEST = "exit" CRLF CRLF + Response message SPCP-EXIT-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-EXIT-REQUEST message, it executes the process required to release the SPCP session, then sends back a result with an SPCP-EXIT-RESPONSE message. 3.1.3 Call (SPCP-CALL-REQUEST) [MUST] The "call" command is used for making an outgoing call. When han- dling multiple calls, call reference numbers (CALL-REFERENCE) are used to identify calls. A client generates a unique call reference number for any particular call. Call reference numbers are reusable after the call is released Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: + Message format SPCP-CALL-REQUEST = "call" WSP DEST-ADDR [WSP CALL-REFERENCE] CRLF CRLF DEST-ADDR = STRING ; calling party address CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-CALL-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-EXIT-REQUEST message, it executes the process required to make an outgoing call to the destination which is indicated by the DEST-ADDR, then sends back a result with an SPCP- CALL-RESPONSE message. Kanai/Morinaga/Fukuyama/Matsuda [Page 18] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 3.1.4 Dial (SPCP-DIAL-REQUEST) [MUST] The "dial" command is used for sending out the digits that have been dialed to the network. Here the syntax of this message is described in detail: + Message format SPCP-DIAL-REQUEST = "call" WSP DIAL-NO [WSP CALL-REFERENCE] CRLF CRLF DIAL-NO = 1*PCHAR ; dialed digits CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-DIAL-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-DIAL-REQUEST message, it executes the process required to send out the dialed digits (DIAL-NO ) for the call which is indicated by the CALL-REFERENCE, then sends back a result with an SPCP-DIAL-RESPONSE message. 3.1.5 Answer (SPCP-ANSWER-REQUEST) [MUST] The "answer" command is used for answering an incoming call. Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: + Message format SPCP-ANSWER-REQUEST = " answer " [WSP CALL-REFERENCE] CRLF CRLF CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-ANSWER-RESPONSE = "200" ; OK = "400" ; Error Kanai/Morinaga/Fukuyama/Matsuda [Page 19] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 + Necessary process When a server receives an SPCP-ANSWER-REQUEST message, it executes the process required to answer the incoming call which is indicated by the CALL-REFERENCE, then sends back a result with an SPCP-ANSWER- RESPONSE message. 3.1.6 Drop (SPCP-DROP-REQUEST) [MUST] The "drop" command is used for hanging up a call. Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: + Message format SPCP-DROP-REQUEST = "drop" [WSP CALL-REFERENCE] CRLF CRLF CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-DROP-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-DROP-REQUEST message, it executes the process required to hang up the call which is indicated by the CALL- REFERENCE, then sends back a result with an SPCP-DROP-RESPONSE mes- sage. 3.1.7 Hold (SPCP-HOLD-REQUEST) [MAY] The "hold" command is used for holding a call or retrieving a held call. It can also be used for switching between an ongoing call and a held call. Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: + Message format SPCP-HOLD-REQUEST = "hold" [WSP HOLD-SET [WSP CALL-REFERENCE]] CRLF CRLF Kanai/Morinaga/Fukuyama/Matsuda [Page 20] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 HOLD-SET = "on" ; hold a call / "off" ; retrieve a held call CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-HOLD-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-HOLD-REQUEST message, it executes the process required to hold or retrieve the call which is indicated by the CALL-REFERENCE, then sends back a result with an SPCP-HOLD- RESPONSE message. 3.1.8 Park (SPCP-PARK-REQUEST) [MAY] The "park" command is used for parking a call or retrieving a parked call. Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: + Message format SPCP-PARK-REQUEST = "park" WSP PARK-SET WSP PARK-REFERENCE [WSP CALL-REFERENCE] CRLF CRLF PARK-SET = "set" ; park a call / "answer" ; retrieve a parked call PARK-REFERENCE = 1*DIGIT ; call park reference number CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-PARK-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-PARK-REQUEST message, it executes the process required to get a call parked or retrieve a parked call. The call is indicated by the PARK-REFERENCE and the CALL-REFERENCE. Then sends back a result with an SPCP-PARK-RESPONSE message. Kanai/Morinaga/Fukuyama/Matsuda [Page 21] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 3.1.9 Transfer (SPCP-TRANSFER-REQUEST) [MAY] The "transfer" command is used for transferring a call. Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: + Message format SPCP-TRANSFER-REQUEST = "transfer" [WSP CALL-REFERENCE1 WSP CALL-REFERENCE2] CRLF CRLF CALL-REFERENCE1 = 1*HEXDIT ; call reference number CALL-REFERENCE2 = 1*HEXDIT ; call reference number + Response message SPCP-TRANSFER-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-TRANSFER-REQUEST message, it executes the process required to transfer the call which is indicated by the CALL-REFERENCE1 to the destination as indicated in the CALL- REFERENCE2, then sends back a result with an SPCP-TRANSFER-RESPONSE message. 3.1.10 Forward (SPCP-FORWARD-REQUEST) [MAY] The " forward " command is used for forwarding an incoming call. Here the syntax of this message is described in detail:Here the syn- tax of this message is described in detail: + Message format SPCP-FORWARD-REQUEST = "forward" [WSP FWR-ADDR [WSP CALL-REFERENCE]] CRLF CRLF FWR-ADDR = STRING ; destination address CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message Kanai/Morinaga/Fukuyama/Matsuda [Page 22] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 SPCP-FORWARD-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-FORWARD-REQUEST message, it executes the process required to forward the incoming call which is indicated by the CALL-REFERENCE to the destination which is indicated by the FWR-ADDR, then sends back a result with an SPCP-FORWARD-RESPONSE mes- sage. 3.1.11 Callreject (SPCP-CALLREJECT-REQUEST) [MAY] The " callreject " command is used to reject an incoming call. Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: + Message format SPCP-CALLREJECT-REQUEST = "forward" [WSP CALL-REFERENCE] CRLF CRLF CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-CALLREJECT-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-CALLREJECT-REQUEST message, it exe- cutes the process required to reject (terminate) the incoming call which as indicated by the CALL-REFERENCE message, then sends back a result with an SPCP-CALLREJECT-RESPONSE message. 3.1.12 Conference (SPCP-CONFERENCE-REQUEST) [MAY] The " conference " command is used for making a conference call or adding/removing somebody to/from an ongoing conference call. Here the syntax of this message is described in detail:Here the syntax of this message is described in detail: Kanai/Morinaga/Fukuyama/Matsuda [Page 23] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 + Message format SPCP-CONFERENCE-REQUEST = "conference" [WSP CONF-SET [WSP CALL-REFERENCE]] CRLF CRLF CONF-SET = "add" ; add somebody to a conference call / "delete" ; remove somebody from a conference call CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-CONFERENCE-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-CONFERENCE-REQUEST message, it exe- cutes the process required to make a conference call or add/remove somebody to/from an ongoing conference call, then sends back a result with an SPCP-FORWARD-RESPONSE message. 3.1.13 Data (SPCP-DATA-REQUEST) [SHOULD] The "data" command is used for sending/receiving data between a server and a client. Here the syntax of this message is described in detail: + Message format SPCP-DATA-REQUEST = "data" WSP DIRECTION [WSP KIND] CRLF [ "media-type" ":" MEDIA-TYPE CRLF "manage" ":" MANAGE CRLF "length" ":" LENGTH CRLF "flag" ":" FLAG CRLF ":" CRLF DATA CRLF] DIRECTION = "get" ; send data / "put" ; receive data KIND = STRING ; data (file) name MEDIA-TYPE = STRING ; media type of data MANAGE = STRING ; operation method LENGTH = STRING ; data length Kanai/Morinaga/Fukuyama/Matsuda [Page 24] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 FLAG = STRING ; repeat indicator DATA = DATA ; data + Response message SPCP-DATA-RESPONSE = "200" ; OK = "400" ; Error MEDIA-TYPE-ATTR-VALUE = TYPE "/" SUB-TYPE ; data attribute MANAGE-ATTR-VALUE = STRING ; operation method LENGTH-ATTR-VALUE = 1*DIGIT ; data length + Necessary process When a server receives an SPCP-DATA-REQUEST message, it checks if the requested process is available or not, then sends back the appropri- ate result with an SPCP-DATA-RESPONSE message. 3.1.14 Indicate (SPCP-INDICATE-REQUEST) [MAY] The "indicate" command is used by the client when requesting that the server provide its internal data. Such data might include voice messages or FAX messages. Here the syntax of this message is described in detail: + Message format SPCP-INDICATE-REQUEST = "indicate" WSP INDICATE-SET [WSP CALL-REFERENCE] CRLF [ "indicate-class" ":" INDICATE-CLASS CRLF] CRLF] INDICATE-SET = "on" ; start sending data / "off" ; stop sending data CALL-REFERENCE = 1*HEXDIT ; call reference number INDICATE-CLASS = STRING ; requesting data class + Response message SPCP-INDICATE-RESPONSE = "200" ; OK = "400" ; Error Kanai/Morinaga/Fukuyama/Matsuda [Page 25] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 + Necessary process When a server receives an SPCP-INDICATE-REQUEST message, it checks if requested data is available, then sends back the result with an SPCP-INDICATE-RESPONSE message. 3.1.15 Qoscontrol (SPCP-QOSCONTROL-REQUEST) [MAY] The "qoscontrol" command is used for adjusting the quality of voice transmission. Here the syntax of this message is described in detail: + Message format SPCP-QOSCONTROL-REQUEST = "qoscontrol" [WSP VALUE [WSP CALL-REFERENCE]] CRLF CRLF] VALUE = 1*DIGIT ; bandwidth CALL-REFERENCE = 1*HEXDIT ; call reference number + Response message SPCP-QOSCONTROL-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-QOSCONTROL-REQUEST message, it adjusts bandwidth of the voice transmission, then sends back a result with an SPCP-QOSCONTROL-RESPONSE message. 3.1.16 Parma (SPCP-PARAM-REQUEST) [SHOULD] The "param" command is used for getting or setting information in the server, such as key data, lamp data and system configuration. The PARAM-MODE part indicates which information should be retrieved or set. If the PARAM-MODE is omitted, all information should be retrieved or set. Here the syntax of this message is described in detail: And see [Appendix D] for examples of setting information. + Message format SPCP-PARAM-REQUEST = "param" WSP DIRECTION [WSP PARM-MODE] CRLF Kanai/Morinaga/Fukuyama/Matsuda [Page 26] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 [ "media-type" ":" MEDIA-TYPE CRLF "length" ":" LENGTH CRLF ":" CRLF DATA CRLF] CRLF DIRECTION = "get" ; retrieve information / "put" ; set information PARAM-MODE = "key-data" ; key data / "lamp-data" ; lamp data / "system-data" ; system configuration / "other" ; other data MEDIA-TYPE = STRING ; media type of data LENGTH = 1*DIGIT ; data length DATA = DATA ; data + Response message SPCP-PARAM-RESPONSE = "200" ; OK = "400" ; Error MEDIA-TYPE-ATTR-VALUE = TYPE "/" SUB-TYPE ; information attribute LENGTH-ATTR-VALUE = 1*DIGIT ; information length + Necessary process When a server receives an SPCP-PARAM-REQUEST message, it retrieves or sets required information, then sends back a result, and the retrieved information (if the DIRECTION is "get") with an SPCP- PARAM-RESPONSE message. 3.1.17 Do (SPCP-DO-REQUEST) [SHOULD] The "do" command is used for ordering a server to execute a particu- lar function. The FUNCTION part indicates which function should be executed. Here the syntax of this message is described in detail: + Message format SPCP-DO-REQUEST = "do" WSP FUNCTION [WSP OPERATION] CRLF CRLF FUNCTION = STRING ; function name Kanai/Morinaga/Fukuyama/Matsuda [Page 27] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 OPERATION = STRING ; description of operation + Response message SPCP-DO-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-DO-REQUEST message, it executes the function which is indicated by FUNCTION and OPERATION, then sends back a result with an SPCP-DO-RESPONSE message. 3.1.18 Name (SPCP-NAME-REQUEST) [MUST] The "name" command is used for getting a server name. Here the syn- tax of this message is described in detail: + Message format SPCP-NAME-REQUEST = "name" CRLF CRLF + Response message SPCP-NAME-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-NAME-REQUEST message, it checks if the name is available, then sends back a result, and the name if it is available, with an SPCP-NAME-RESPONSE message. 3.1.19 Nop (SPCP-NOP-REQUEST) [MUST for servers, MAY for clients] The "nop" command is used for checking a current server status (active/inactive). Here the syntax of this message is described in detail: + Message format SPCP-NOP-REQUEST Kanai/Morinaga/Fukuyama/Matsuda [Page 28] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 = "nop" CRLF CRLF + Response message SPCP-NOP-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-NOP-REQUEST message, if it is working properly it sends back an OK with an SPCP-NOP-RESPONSE message. If it is working improperly, it might send back an Error with an SPCP-NOP- RESPONSE message. If it is not working at all, the client will not receive any response message. 3.1.20 Selftest (SPCP-SELFTEST-REQUEST) [MAY] The "selftest" command is used for executing a self-test in a server. Here the syntax of this message is described in detail: + Message format SPCP-SELFTEST-REQUEST = "selftest" CRLF CRLF + Response message SPCP-SELFTEST-RESPONSE = "200" ; OK = "400" ; Error + Necessary process When a server receives an SPCP-SELFTEST-REQUEST message, it executes a self-test, then sends back the result with an SPCP-SELFTEST- RESPONSE message. 3.1.21 Proprietary Command [MAY] Implementers can create their own REQUEST commands for their proprietary use by adding "X-" to the top of a command string, as "X-mycommand". Kanai/Morinaga/Fukuyama/Matsuda [Page 29] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 3.2 SPCP-NOTICE SPCP-REQUEST is a message which a server sends to notify a client of an event. 3.2.1 Opened (SPCP-OPENED-NOTICE) [MUST] The "opened" notice is used when a server notifies a client that a session has been established successfully. Here the syntax of this message is described in detail: + Message format SPCP-OPENED-NOTICE = "opened" ":" [COMMENT] CRLF "spcp-version" ":" SPCP-VERSION CRLF "auth-code" ":" AUTH-CODE CRLF CRLF COMMENT = PHRASE ; description of the session SPCP-VERSION = "SPCP/1.0" ; version information of SPCP AUTH-CODE = STRING ; a challenge code for authentication + Necessary process A server sends this message to a client just after a TCP connection to the client is established successfully. The message contains an SPCP version and a challenge code for authentication in its ATRRIBUTE part. If the implemented protocol is compliant to this document, the SPCP-VERSION must be "SPCP/0.5". (For the detail of the SPCP-VERSION, see "INFORMATION".) The AUTH-CODE is filled with random characters. 3.2.2 Calling (SPCP-CALLING-NOTICE) [MUST] The "calling" notice is used when a server notifies a client that an outgoing call has been established successfully and is waiting for a receiver's action. Here the syntax of this message is described in detail: + Message format SPCP-CALLING-NOTICE = "calling" ":" [COMMENT] CRLF ["call-reference" ":" CALL-REFERENCE CRLF] CRLF Kanai/Morinaga/Fukuyama/Matsuda [Page 30] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 COMMENT = PHRASE ; description of the session CALL-REFERENCE = 1*HEXDIT ; call reference number + Necessary process A server sends this message to a client just after an outgoing call is established successfully. 3.2.3 Connect (SPCP-CONNECT-NOTICE) [MUST] The "connect" notice is used for when the server notifies a client that the receiver successfully answered an outgoing call, or when the server answered an incoming call. Here the syntax of this message is described in detail: + Message format SPCP-CONNECT-NOTICE = "connect" ":" [COMMENT] CRLF ["call-reference" ":" CALL-REFERENCE CRLF] CRLF COMMENT = PHRASE ; description of the session CALL-REFERENCE = 1*HEXDIT ; call reference number + Necessary process A server sends this message to the client just after a recipient of an outgoing call answered that call, or when the server answered an incoming call. 3.2.4 Offering (SPCP-OFFERING-NOTICE) [MUST] The "offering" notice is used when a server notifies a client that it received an incoming call. Here the syntax of this message is described in detail: + Message format SPCP-OFFERING-NOTICE = "offering" ":" [COMMENT] CRLF ["cp-number" ":" CP-NUMBER CRLF] ["call-reference" ":" CALL-REFERENCE CRLF] CRLF COMMENT = PHRASE ; description of the session Kanai/Morinaga/Fukuyama/Matsuda [Page 31] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 CP-NUMBER = STRING ; calling party information CALL-REFERENCE = 1*HEXDIT ; call reference number + Necessary process A server sends this message to a client just after it recieves an incoming call. The CP-NUMBER provides sender information. 3.2.5 Busy (SPCP-BUSY-NOTICE) [MUST] The "busy" notice is used by a server to notify a client that the recipient of an outgoing call is busy. Here the syntax of this mes- sage is described in detail: + Message format SPCP-BUSY-NOTICE = "busy" ":" [COMMENT] CRLF ["call-reference" ":" CALL-REFERENCE CRLF] CRLF COMMENT = PHRASE ; description of the session CALL-REFERENCE = 1*HEXDIT ; call reference number + Necessary process The server sends this message to the client immediately after it gets a busy response from the recipient. 3.2.6 Disconnect (SPCP-DISCONNECT-NOTICE) [MUST] The "disconnect" notice is used by a server to notify a client that a call has been disconnected. Here the syntax of this message is described in detail: + Message format SPCP-DISCONNECT-NOTICE = "disconnect" ":" [COMMENT] CRLF ["call-reference" ":" CALL-REFERENCE CRLF] CRLF COMMENT = PHRASE ; description of the session CALL-REFERENCE = 1*HEXDIT ; call reference number + Necessary process Kanai/Morinaga/Fukuyama/Matsuda [Page 32] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 The server sends this message to the client just after it completes the process required for call disconnection. 3.2.7 Indicate-info (SPCP-INDICATE-INFO-NOTICE) [MAY] The "indicate-info" notice is used when a server notifies a client that an event (previously been registered by the client) takes place. Here the syntax of this message is described in detail: + Message format SPCP-INDICATE-INFO-NOTICE = "indicate-info" ":" [COMMENT] CRLF "indicate-class"" ":" INDICATE-CLASS CRLF ["call-reference" ":" CALL-REFERENCE CRLF] ["media-type" ":" MEDIA-TYPE CRLF "length" ":" LENGTH CRLF "flag" ":" FLAG CRLF ":" CRLF DATA CRLF] CRLF COMMENT = PHRASE ; description of the session INDICATE-CLASS = STRING ; event type CALL-REFERENCE = 1*HEXDIT ; call reference number MEDIA-TYPE = STRING ; data attribute LENGTH = 1*DIGIT ; data length FLAG = STRING ; indicates top/tail of data DATA = DATA ; data + Necessary process If a client registers a notification of particular events with SPCP- INDICATE-REQUEST, then when a server detects those events it sends this message to notify the client, if necessary with data. 3.2.8 Done (SPCP-DONE-NOTICE) [SHOULD] The "done" notice is used by a server to notify a client that an event occurs on keys or lamps. Here the syntax of this message is described in detail: + Message format SPCP-DONE-NOTICE Kanai/Morinaga/Fukuyama/Matsuda [Page 33] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 = "done" ":" [COMMENT] CRLF "function-detect"" ":" FUNCTION "/" STATUS CRLF CRLF FUNCTION = 1*DIGIT ; key/lamp name STATUS = STRING ; event + Necessary process When a server detects events on keys/lamps, it sends this message to notify the client. 3.2.9 Progress (SPCP-PROGRESS-NOTICE) [MAY] The "progress" notice is used by a server to notify a client of the current state of progress of a server process if that process ahs taken too long. + Message format SPCP-PROGRESS-NOTICE = "progress" ":" [COMMENT] CRLF ["command-class" ":" COMMAND-CLASS CRLF "media-type" ":" MEDIA-TYPE CRLF "length" ":" LENGTH CRLF ":" CRLF DATA CRLF ] CRLF COMMENT = PHRASE ; description of the session COMMAND-CLASS = STRING ; command type MEDIA-TYPE = STRING ; data attribute LENGTH = 1*DIGIT ; data length DATA = DATA ; data + Necessary process A server sends this message to the client when the process in the server made some progress. 3.2.10 Proprietary Command [MAY] Implementers can create their own NOTICE commands for their proprietary use by prepending "X-" to the command string, as "X- Kanai/Morinaga/Fukuyama/Matsuda [Page 34] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 mycommand". 3.3 SPCP-RESPONSE A server responds to a client's request with an SPCP-RESPONSE mes- sage. 3.3.1 2xx (OK) [MUST] The "2xx" response indicates that a process completed properly. + Message format SPCP-RESPONSE = "2xx" ":" [COMMENT] CRLF ["call-reference" ":" CALL-REFERENCE CRLF] CRLF COMMENT = PHRASE ; description of the session CALL-REFERENCE = 1*HEXDIT ; call reference number + Necessary process A server sends this message to the client when it completes a process properly. 3.3.2 3xx (OK) [MUST] The "3xx" response indicates that a process was completed properly but still needs more commands. + Message format SPCP-RESPONSE = "3xx" ":" [COMMENT] CRLF ["call-reference" ":" CALL-REFERENCE CRLF] CRLF COMMENT = PHRASE ; description of the session CALL-REFERENCE = 1*HEXDIT ; call reference number + Necessary process When a server completes a process properly but still needs more com- mands, it sends this message to a client. The requested commands are listed in the INFORMATION part of the message. Kanai/Morinaga/Fukuyama/Matsuda [Page 35] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 3.3.3 4xx (Error) [MUST] The "4xx" response indicates that a process didn't complete properly. + Message format SPCP-RESPONSE = "4xx" ":" [COMMENT] CRLF CRLF COMMENT = PHRASE ; description of the session + Necessary process A server sends this message to a client if the process did not com- plete properly. If necessary, error information is included in the INFORMATION part of the message. 3.3.4 5xx (Fatal error) [MUST] The "5xx" response indicates that a fatal error occurred. + Message format SPCP-RESPONSE = "5xx" ":" [COMMENT] CRLF CRLF COMMENT = PHRASE ; description of the session + Necessary process A server sends this message to a client when a fatal error occurs on the server. If necessary, error information is included in the INFORMATION part of the message. 3.3.5 9xx (Proprietary response) [MAY] The "9xx" is reserved for implementers to create their own proprietary RESPONSE codes. + Message format SPCP-RESPONSE = "9xx" ":" [COMMENT] CRLF CRLF Kanai/Morinaga/Fukuyama/Matsuda [Page 36] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 COMMENT = PHRASE ; description of the session 3.4 INFORMATION The INFORMATION part in the SPCP-MESSAGE containins extra informa- tion, such as binary data. It consists of a DATA field, which is the main body of information, and an ATTRIBUTE field, which contains attributes of the information. + Message format INFORMATION = *ATTRIBUTE-LINE ; Attribute line ":" CRLF *DATA ; Data ATTRIBUTE-LINE = ATTR-TYPE DELIMITER ATTR-VALUE CRLF ATTR-TYPE = "media-type" ; media type / "spcp-version"; SPCP version / "length" ; data length / "timeout" ; time limit / "auth-code" ; challenge code for authentication / "cp-addr" ; calling party address / "call-reference" ; call reference number / "command" ; current process information / "flag" ; repeat indicator / "name-type" ; product name / "function-detect" ; key/lamp information / "X-" 1*PCHAR ; (extensible attribute type) 3.4.1 ATTRIBUTE-LINE The ATTRIBUTE-LINE field consists of an ATTR-TYPE field, which indi- cates an attribute type, and an ATTR-VALUE field, which contains attribute value. Here are details of ATTR-TYPEs and ATTR-VALUEs. 3.4.2.1 media-type [MAY] The "media-type" indicates data type and is followed by MEDIA-TYPE- ATTR-VALUE. + Message format Kanai/Morinaga/Fukuyama/Matsuda [Page 37] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 ATTRIBUTE-LINE = "media-type" "/" MEDIA-TYPE-ATTR-VALUE CRLF MEDIA-TYPE-ATTR-VALUE = "text" "/" "plain" ; plain text data / "text" "/" "html" ; HTML data / "audio" "/" "u-law" ; audio data (u-law) / "audio" "/" "a-law" ; audio data (a-law) / "audio" "/" "g723" ; audio data (g.723.1) / "audio" "/" "g729" ; audio data (g.729) / "image" "/" "tiff" ; image data (TIFF) / "image" "/" "giff" ; image data (GIFF) / "image" "/" "JPEG" ; image data (JPEG) / "image" "/" "bitmap" ; image data (BITMAP) 3.4.2.2 spcp-version [MUST] The "spcp-version" indicates the version of SPCP and is followed by the SPCP-VERSION-ATTR-VALUE. + Message format ATTRIBUTE-LINE = "spcp-version" "/" SPCP-VERSION-ATTR-VALUE CRLF SPCP-VERSION-ATTR-VALUE = "SPCP" "/" "1.0" ; SPCP v1.0 3.4.2.3 length [MAY] The "length" indicates the data media length and is followed by LENGTH-ATTR-VALUE. + Message format ATTRIBUTE-LINE = "length" "/" LENGTH-ATTR-VALUE CRLF LENGTH-ATTR-VALUE = 1*DIGIT ; data media length 3.4.2.4 timeout [MAY] The "timeout" indicates the time limit and is followed by TIMEOUT- ATTR-VALUE. Kanai/Morinaga/Fukuyama/Matsuda [Page 38] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 + Message format ATTRIBUTE-LINE = "timeout" "/" TIMEOUT-ATTR-VALUE CRLF TIMEOUT-ATTR-VALUE = 1*DIGIT ; the time limit 3.4.2.5 auth-code [MUST] The "auth-code" indicates a challenge code for authentication and is followed by AUTH-CODE-ATTR-VALUE. + Message format ATTRIBUTE-LINE = "auth-code" "/" AUTH-CODE-ATTR-VALUE CRLF AUTH-CODE-ATTR-VALUE = STRING ; challenge code 3.4.2.6 cp-addr [MAY] The "cp-addr" indicates a calling party address and is followed by CP-ADDR-ATTR-VALUE. + Message format ATTRIBUTE-LINE = "cp-addr" "/" CP-ADDR-ATTR-VALUE CRLF CP-ADDR-ATTR-VALUE = STRING ; calling party address 3.4.2.7 call-reference [MAY] The "call-reference" indicates a caller reference number and is fol- lowed by CALL-REFERENCE-ATTR-VALUE. + Message format ATTRIBUTE-LINE = "call-reference" "/" CALL-REFERENCE-ATTR-VALUE CRLF CALL-REFERENCE-ATTR-VALUE Kanai/Morinaga/Fukuyama/Matsuda [Page 39] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 = 1*HEXDIG ; call reference number 3.4.2.8 flag [MAY] The "flag" indicates he tbeginning or end of a data transmission and is followed by the FLAG-ATTR-VALUE. + Message format ATTRIBUTE-LINE = "flag" "/" FLAG-ATTR-VALUE CRLF FLAG-ATTR-VALUE = 1*HEXDIG ; repeat indicator 3.4.2.9 name-type [MAY] The "name-type" indicates the device product name and is followed by the NAME-TYPE-ATTR-VALUE. + Message format ATTRIBUTE-LINE = "name-type" "/" NAME-TYPE-ATTR-VALUE CRLF NAME-TYPE-ATTR-VALUE = PRODUCT "/" MACHINE [; MANUFA-NO] PRODUCT = STRING ; manufacturer MACHINE = STRING ; product type MANUFA-NO = 1*DIGIT ; serial number 3.4.2.10 function-detect [MAY] The "function-detect" indicates key/lamp information and is followed by FUNCTION-DETECT-ATTR-VALUE. + Message format ATTRIBUTE-LINE = "function-detect" "/" FUNCTION-DETECT-ATTR-VALUE CRLF FUNCTION-DETECT-ATTR-VALUE = FUNCTION-ID "/" STATUS FUNCTION-ID = 1*DIGIT ; key/lamp number Kanai/Morinaga/Fukuyama/Matsuda [Page 40] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 STATUS = STRING ; key/lamp status 3.4.2.11 X- [MAY] The "X- " is reserved for implementers to create proprietary ATTR- TYPEs. 4. Implementation Example Here are some examples of SPCP system implementation: In order to control an IP telephone with SPCP, a network device (like a PC) should have certain information about the IP telephone. This might include IP address ,telephone number, and perhaps other information as well. The method of obtaining that information depends on the net- work system configuration. 4.1 System configuration example In order to manage IP address, some network management devices (such as an Internet telephony controller, a directory Server, a DHCP server or so on) will be necessary. Here is an example of a network system configuration which includes IP telephones: + Network Devices - IP network ; MUST - IP telephone ; MUST - Computer ; MUST - Internet telephony controller ; SHOULD - Directory server ; SHOULD - DHCP server ; SHOULD Kanai/Morinaga/Fukuyama/Matsuda [Page 41] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 + System Configuration +----------+ | +----------+ | |================|================>| | | IP Phone |<===============|=================| APPL | | | | | | | | SPCP I/F | | | (MUST) |........ | (MUST) | | |<... : | | +----------+ : : +----------+ : A : : : A : : : : : : DHCP I/F----------- -------IT I/F DIR I/F+----------------- : : : : | : : V : : : | V : +----------+ : : +----------+ | +----------+ | DHCP SVR | : : |IT | | | DIR SVR | | | : :..>|Controller|.....|....>| | | (SHOULD) | :.......| (SHOULD) |<....|.....| (SHOULD) | +----------+ +----------+ | +----------+ IP Phone ; IP telephone APPL ; network management device DHCP SVR ; DHCP [6] server IT Controller ; Internet Telephony Controller (e.g. H.323 Gatekeeper [7]) DIR SVR ; Directory server (e.g. LDAP [8] server, X.500 server........j ====> ; SPCP protocol In the following it is assumed that the H.323 Gatekeeper is used as the Internet Telephony Controller and an LDAP server is used as the Directory server. Below each network device is detailed. 4.1.1 IP telephone An IP telephone is a network device dedicated to voice communications based on the IP protocol. Here are some requirements for the IP telephone: + User interfaces: - Handset ; MUST - Keys ; SHOULD - Lamps ; SHOULD - Ring ; SHOULD - Speaker ; MAY Kanai/Morinaga/Fukuyama/Matsuda [Page 42] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 - Ringer-volume-adjusting knob ; MAY + Functions: - Network interface ; MUST - TCP and UDP protocol stack ; MUST - H.323 protocol stack ; MUST - DHCP protocol stack ; SHOULD - LDAP protocol stack ; MAY - Voice message ; MAY - FAX ; MAY + Configuration data in the IP telephone: - MAC address of itself ; MUST - IP address of itself ; MUST - Alias of itself (*1) ; SHOULD - Host name of itself ; MAY - IP address of the Gatekeeper ; SHOULD - IP address of the LDAP server ; MAY (*1) Alias of IP telephone ; Character string which identifies the specific IP telephone --such as telephone number (e.g., E164 address). 4.1.2 Internet Telephony Controller An Internet Telephony Controller is a network device that arranges connections between IP telephones. Henceforth, it is assumed that an H.323 Gatekeeper is used as the Internet Telephony Controller. Here are some requirements for the Internet Telephony Controller: + User interfaces: - GUI for operation ; MAY + Functions: - Network interface ; MUST - TCP and UDP protocol stack ; MUST - H.323 protocol stack ; MUST + Information managed in the Internet Telephony Controller: - MAC addresses of IP telephones ; MAY - IP addresses of IP telephones ; MAY - Aliases of IP telephones ; MAY Kanai/Morinaga/Fukuyama/Matsuda [Page 43] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 - Host names of IP telephones ; MAY 4.1.3 Directory server A Directory server is a network device that manages aliases of IP telephones. Henceforth, it is assumed that an LDAP server is used as the Directory server. Here are some requirements for the Directory server: + User interfaces: - GUI for operation ; MAY + Functions: - Network interface ; MUST - TCP and UDP protocol stack ; MUST - LDAP protocol stack ; MUST + Information managed in the Directory server: - MAC addresses of IP telephones ; MUST - IP addresses of IP telephones ; MUST - Aliases of IP telephones ; SHOULD - Host names of IP telephones ; MAY 4.1.4 DHCP server A DHCP server is a network device that dynamically allocates IP address to network devices. Here are some requirements for the DHCP server: + User interfaces: - GUI for operation ; MAY + Functions: - Network interface ; MUST - TCP and UDP protocol stack ; MUST - DHCP protocol stack ; MUST + Information managed in the DHCP server: - MAC addresses of IP telephones ; MUST - IP addresses of IP telephones ; MUST Kanai/Morinaga/Fukuyama/Matsuda [Page 44] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 4.2 IP Telephone system implementation example This section shows some typical examples of IP telephone system implementation. It explains how network devices can obtain an IP telephone's IP address. Appendix A shows an another example of implementation, and Appendix B adds more information about system parameters. 4.2.1 Simplest implementation The network devices that are marked with "MUST" in the above Section 4.1 are essential for the simplest implementation of IP telephone system. They must be compliant to the "MUST" requirements. In this simplest system the network devices don't keep an IP telephone's IP address, so they have to obtain IP address from IP telephone to access that information. Here is the essential system parameter for the IP telephone: + System parameter for the IP telephone: - IP address of itself A specific IP address must be set manually into the IP telephone. 4.2.2 LDAP server implementation A centralized management of aliases and IP addresses of IP telephones based on a certain network policy allows network managers to sys- tematically organize IP address in their network systems. That is, IP telephones can be identified with their aliases, like telephone number, instead of their IP addresses. Telephone numbers should be maintained in a LDAP server. For such an implementation, the network devices that are marked with "MUST" and "SHOULD" in the above Section 4.1 are essential and also must be compliant to the "MUST" and "SHOULD" requirements. In this implementation the network devices can translate an IP telephone's alias to its IP address with the LDAP server. Here is some essential system parameters for the IP tele- phone: + System parameters for the IP telephone: - IP address of itself A specific IP address should be set dynamically into the IP telephone by using a DHCP server. - Alias of itself A specific alias should be set dynamically into the IP Kanai/Morinaga/Fukuyama/Matsuda [Page 45] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 telephone by using a Gatekeeper in RRQ/RCF method of RAS [7] (see Appendix B). - IP address of Gatekeeper An IP telephone should dynamically obtain the Gatekeeper's IP address by using the Gatekeeper in GRQ/GCF method of RAS [7] (see Appendix B). In such a system, the LDAP server should also maintain an IP telephone's MAC address with a link to its alias. In this way net- work devices can access an IP telephone only with its alias (such as telephone number). Here are some essential system parameters for the LDAP server: + Information to be maintained by a LDAP server: - MAC address of IP telephone When a Gatekeeper executes RRQ/RCF method, it should obtain a MAC address from an IP telephone and forward it to a LDAP server. - IP address of IP telephone When a Gatekeeper executes RRQ/RCF method, it should obtain an IP address from an IP telephone and forward it to a LDAP server. - Alias of IP telephone The alias of an IP telephone should be maintained in an LDAP server with a link to a MAC address.When a Gatekeeper executes the RRQ/RCF method, it should request that the LDAP server to translate an IP telephone's MAC address to its alias. Once the above procedures have been completed, network devices can obtain an IP telephones' IP address through the LDAP server. Here is an example of the sequence: + An example how a network device obtains an IP-telephone's IP address: The network device should request the LDAP server to translate an IP telephone's phone number to its IP address. APPL IP Phone DHCP SVR Gatekeeper LDAP SVR | | | | | | |............>| | | | [S01]|DHCPDISCOVER | | | | |<............| | | Kanai/Morinaga/Fukuyama/Matsuda [Page 46] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 | [S02]|DHCPOFFER | | | | |............>| | | | [S03]|DHCPREQUEST | | | | |<............| | | | [S04]|DHCPPACK | | | | ( |..........................>| ) | S | ( {S05]|GRQ | | ) | H | ( |<..........................| ) | O | ( [S06]|GCF | | ) | U | |..........................>| | L | [S07]|RRQ | | | D | | | |............>| | | | [S08]|SEARCH(s1) | | | | |<............| ( | | | [S09]|RESULT(s1) | M | | | |............>| A | | | [S10]|MODIFY(m1) | Y | | | |<............| ) | | | [S11]|RESULT(m1) | | |<..........................| | | [S12]|RCF | | | |......................................................>| [S13]|SEARCH(s2) | | | | |<......................................................| [S14]|RESULT(s2) | | | | | | | | | | | | | | ----------------------begin SPCP session------------------------- |============>| | | | [S15]|SPCP-REQUEST | | | | |<============| | | | [S16]|SPCP-RESPONSE| | | | |<============| | | | [S17]|SPCP-NOTICE | | | | | .... | | | | | | | | | ----------------------close SPCP session------------------------- | | | | | | |..........................>| | | [S18]|URQ | | | | | | |............>| S | | | [S19]|MODIFY(m2) | H | | | |<............| O | | | [S20]|RESULT(m2) | U | |<..........................| | L | [S21]|UCF | | | D | |............>| | | | [S22]|DHCPRELEASE | | | Kanai/Morinaga/Fukuyama/Matsuda [Page 47] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 | | | | | [S01] DHCPDISCOVER: (SHOULD, DHCP protocol) The IP telephone broadcasts its MAC address in order to obtain its IP address dynamically. [S02] DHCPOFFER: (SHOULD, DHCP protocol) The DHCP server responds [S01] to provide an IP address to the IP telephone. [S03] DHCPREQUEST: (SHOULD, DHCP protocol) The IP telephone requests that the DHCP server provide the network's system parameters. [S04] DHCPPACK: (SHOULD, DHCP protocol) The DHCP server responds [S03] by providing the network's system parameters to the IP telephone. (In this case, the DHCP server provides the Gatekeeper's IP address with an extension of OPTION. See Appendix B) [S05] GRQ: (MAY, H.323 protocol) In the event that the IP telephone can't obtain the Gatekeeper's IP address, it broadcasts (multicasts) a request for it. [S06] GCF: (MAY, H.323 protocol) The Gatekeeper responds [S05] to provide its IP address to the IP telephone. [S07] RRQ: (SHOULD, H.323 protocol) The IP telephone requests that the Gatekeeper register its IP address and translate its MAC address to an alias. [S08] SEARCH (s1): (SHOULD, LDAP protocol) The Gatekeeper requests that the LDAP server translate the IP telephone's MAC address to an alias. [S09] RESULT (s1): (SHOULD, LDAP protocol) The LDAP server responds [S08], providing an IP telephone's alias to the Gatekeeper. [S10] MODIFY (m1): (SHOULD, LDAP protocol) The Gatekeeper requests that the LDAP server register the IP telephone's IP address. [S11] RESULT (m1): (SHOULD, LDAP protocol) The LDAP server responds with a notification [S10] indicating completion of registration. Kanai/Morinaga/Fukuyama/Matsuda [Page 48] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 [S12] RCF: (SHOULD, H.323 protocol) The Gatekeeper responds [S07] providing the IP telephone's alias to the IP telephone. [S13] SEARCH (s2): (SHOULD, LDAP protocol) An application requests that the LDAP server translate the IP telephone's IP address into an alias. [S14] RESULT (s2): (SHOULD, LDAP protocol) The LDAP server responds [S13], providing the IP telephone's IP address to the application. [S15] SPCP-REQUEST The application sends an SPCP request message to the IP tele- phone. [S16] SPCP-RESPONSE The IP telephone responds [S15], sending an SPCP response to the application. [S17] SPCP-NOTICE The IP telephone sends the application an SPCP notice to notify the application that an event has occurred. [S18] URQ: (SHOULD, H.323 protocol) The IP telephone requests that the Gatekeeper remove its IP address entry. [S19] MODIFY (m2): (SHOULD, LDAP protocol) The Gatekeeper requests that the LDAP server remove the IP telephone's IP address entry. [S20] RESULT (m2): (SHOULD, LDAP protocol) The LDAP server responds to the [S19] request, notifying the Gatekeeper that the removal has been completed. [S21] UCF: (SHOULD, H.323 protocol) The Gatekeeper responds to the [S18] to notify the IP telephone that the removal has been completed. [S22] DHCPRELEASE: (SHOULD, DHCP protocol) The IP telephone requests that the DHCP server release its IP address. 5. Security Because of the need to provide safe communications, SPCP supports the Kanai/Morinaga/Fukuyama/Matsuda [Page 49] INTERNET DRAFT Simple Phone Control Protocol 25 Jun 1999 following security functions: 5.1 Authentication SPCP is compliant to the CRAM-MD5. This is a Challenge-Response-type authorization method. On the CRAM-MD5, a client composes a character string by combining a user's password with a random character string (Challenge) which is provided by a server, and performs a 1- directional hash function to the character string, and then sends the results (Response) to the server. The server independently calculates the same formula with a password which was stored at the serverin advance. The server then compares its result with the result gen- erated at the client. If they are identical, the client's access is authorized. This is one method to generate authorization without sending the raw password over the network. The CRAM-MD5 adopts MD5 (RFC 1321 [5]) as the 1-directional hash function. It calculates a 128-bit hash value from the input value. Here is an encryption method to calculate the Response from the password and the Challenge, and an example of authorization sequence: 5.1.1 Password encryption method The client calculates a Response from a Challenge (AUTH-CODE) (pro- vided by a server) and a password (PASSWORD). The calculation formula is as follows: AUTH-RES = MD5((PASSWORD_OPAD XOR opad), MD5((PASSWORD_OPAD XOR ipad),AUTH-CODE)) MD5(): MD5 function operator XOR: Exclusive-OR operator PASSWORD: 64-byte or shorter character string indicating user password PASSWORD_OPAD: 64-byte character string obtained by adding 0x00 to tail of PASSWORD AUTH-CODE: Random character string indicating "Challenge" AUTH-RES: "Response" ipad: Value obtained by repeating "0x36" 64 times opad: Value obtained by repeating "0x5c" 64 times 5.1.2 Example of authentication sequence s1) In the beginning of SPCP session establishment, a server must provide a Challenge (AUTH-CODE) to a client with an SPCP-NOTICE ("opened") message. The AUTH-CODE should be a character string con- sisting of a server host name, process ID, and a random number. Kanai/Morinaga/Fukuyama/Matsuda [Page 50] INTERNET DRAFT Si