INTERNET-DRAFT G. Hiddink Expires: June 2001 September 2000 draft-hiddinkg-wwcp-part5-01.txt WWCP Part 5: Client protocol 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. Internet Drafts may be updated, replaced, or obsoleted by other documents at any time. It is not appropriate to use Internet Drafts as reference material or to cite them other than as a ``working draft'' or ``work in progress``. To learn the current status of any Internet-Draft, please check the 1id- abstracts.txt listing contained in the Internet-Drafts Shadow Directories on ds.internic.net, nic.nordu.net, ftp.isi.edu, or munnari.oz.au. A revised version of this draft document will be submitted to the RFC editor as a Proposed Standard for the Internet Community. Discussion and suggestions for improvement are requested. This document will expire before October 1996. Distribution of this draft is unlimited, but all copyrights are reserved to G. Hiddink. The ideas contained herein are intellectual property of G. Hiddink. Abstract The Client protocol describes the interaction between a conferencing client and a conferencing server. There are three types of clients: IRC compatible clients (level 1), modified IRC clients (level 2) and "native" WWCP clients (level 3). The protocol for level 1 clients is described in RFC1459; the protocol for the other two levels will be specified in this document. CONTENTS 1. Introduction ................................................ 2. Client types ................................................ Hiddink [Page 1] Internet Draft WWCP Part 5 July 15 1997 2.1 Level 1: IRC clients ....................................... 2.2 Level 2: adapted IRC clients ............................... 2.3 Level 3: WWCP clients ...................................... 3. Level 3 protocol 3.1 General .................................................... 3.2 Identifying ................................................ 3.3 Registering ................................................ 3.4 Listing channels ........................................... 3.5 Listing users .............................................. 3.6 Joining a channel .......................................... 3.6.1 From client to server 3.6.2 From server to client 3.7 Saying things on a channel ................................. 3.7.1 From client to server .................................... 3.7.2 From server to client .................................... 3.7.3 Error messages ........................................... 3.8 Doing things on a channel .................................. 3.8.1 From client to server .................................... 3.8.2 From server to client .................................... 3.8.3 Error messages ........................................... 3.9 Selecting transport media .................................. 3.9.1 From server to client .................................... 3.9.2 From client to server .................................... 3.9.3 Error messages ........................................... 3.10 Leaving a channel ......................................... 3.10.1 From client to server ................................... 3.10.2 From server to client ................................... 3.10.3 Error messages .......................................... 3.11 Creating a channel ........................................ 3.11.1 From client to server ................................... 3.11.2 From server to client ................................... 3.11.3 Error messages .......................................... 3.12 Creating a directory ...................................... 3.13 Sending messages .......................................... 3.13.1 From client to server ................................... 3.13.2 From server to client ................................... 3.13.3 Error messages .......................................... 3.14 Inviting users ............................................ 3.14.1 From client to server ................................... 3.14.2 From server to client ................................... 3.14.3 Error messages .......................................... 3.15 Ignoring users ............................................ 3.15.1 From client to server ................................... 3.15.2 From server to client ................................... 3.15.3 Error messages .......................................... 3.16 Changing a nick ........................................... Hiddink [Page 2] Internet Draft WWCP Part 5 July 15 1997 3.16.1 From client to server ................................... 3.16.2 From server to client ................................... 3.16.3 Error messages .......................................... 3.17 Terminating servers ....................................... 3.18 Various error messages .................................... 4. Level 2 protocol 4.1 Identifying a WWCP server .................................. 4.2 Listing channels ........................................... 4.2.1 Directory permissions .................................... 4.2.3 Errors ................................................... 4.3 Joining channels ........................................... 4.3.1 Registration information ................................. 4.3.2 Errors ................................................... 4.4 Identical nicks ............................................ 1. Introduction ................................................ This document describes the protocol that is spoken from an entitity that identified itself as a client ("CLNT") and a server that supports connections from such entities. 1.2 Messages Messages between clients and servers consist of human-readable ASCII messages terminated by a CR (ascii 13) and/or a LF (ascii 10). A message is up to 511 bytes long. Clients and servers communicate using the Network Interface Layer protocol, as described in part 1 of this protocol suite. 1.1 Error messages Note that a WWCP implementation may decide to send empty textual information to save bandwidth. A client implementation should only rely on the numeric, but may display the textual information, if present, to the human user. 2. Client types As most users are familiar with Internet Relay Chat (IRC) clients, some support must be provided for them to be able to use their client software. Currently, february 1997, there are no WWCP clients yet, so that WWCP servers must be able to communicate with IRC clients. However, some problems arise with some client software, so that some adaptations have to be made. For these purposes, three levels of clients have been defined. Hiddink [Page 3] Internet Draft WWCP Part 5 July 15 1997 2.1 Level 1: IRC clients Level 1 clients are regular IRC clients, i.e. they comply with RFC1459 or a de-facto derivative. A WWCP conferencing server that supports level 1 clients, shall express all output in RFC1459 compliant messages (hereafter called `IRC messages'). WWCP implementations are free in the choice of their translation. 2.2 Level 2: adapted IRC clients Level 2 clients are adapted IRC clients. Especially handling identical nicks, the channel lists and joining channels is hard to express in IRC messages. Therefore, a minimal set of adaptations has been chosen that, when implemented in existing IRC client software, should result in quite usable clients with minimal effort. The adaptations mostly consist of assigning special meaning to certain fields of IRC messages. Thus, client software can provide both IRC and WWCP level 2 compatibility. 2.3 Level 3: WWCP clients Level 3 clients are clients compliant with the WWCP client protocol. This protocol is quite different from IRC, and is needed in order to maximally utilize the properties of the WWCP protocol suite. For example, it eliminates the continuous sending of "nick!user@host" user identifiers, and replaces them with pairs. 3. Level 3 protocol 3.1 General A client sends messages that consist of ascii character sequences, terminated by a carriage return (0x0c). The server will also send messages that consist of ascii characters, terminated by a carriage return. There is one special kind of message that is sent from the server to the client: a numeric reply. This is usually an error message, and consists of a number expressed in ascii (0x30 to 0x39), whitespace, and a textual explanation of the error. The textual explanation is NOT part of the protocol, and clients shall NOT rely on it. Clients shall only rely on the number. In a revision of this protocol, a binary version will be specified. The client will be able to indicate whether it understands the binary or the ascii version using the Protocol field in the IAM message (see section 2.1 of part 2). Hiddink [Page 4] Internet Draft WWCP Part 5 July 15 1997 3.2 Identifying Clients and servers communicate via TCP/IP connections. The connection is initiated by the client. The client then identifies itself according to the NIL protocol. After that, the client can send messages that comply with the protocol described in this document. Note that the client shall still respond to NIL messages, for example the PING message. After the connection has been established, the client must send a valid IAM message (see part 2, section 3.1). The "next protocol information" should contain the nickname the client wishes to use. The client should send its assigned local user ID. If the client has not been assigned one, it should send "0" (zero). If the identification has been accepted by the server, it will send an IAM message informing the client who and what the server is. The password in the IAM message will be an asterisk ('*'), as the server does not maintain "reverse" passwords for clients. After the client has received an IAM message from the server, it can expect messages conforming to the level 3 protocol. The client is expected to read all data as quickly as it can, without leaving any data in network buffers (e.g. Unix-based clients are not expected to suspend processing data that is waiting on the filedescriptor of the socket). One of the first messages the client will get, is the YOU ARE message which is used to inform the client what its user ID for the current session is. This user ID will become invalid when the session is closed, i.e. when the network connection is closed. The user ID is used by the client to recognize messages about itself (e.g. the JOIN message, see section ##.##). The format of the YOU ARE message is: UR 3.3 Registering A client has to be registered in order to be able to fully make use of the conferencing system. Registering constitutes of sending the real name and the e-mail address of the human user to the server. This information will be stored in a user database, and propagated to the User Directory Service. The user can determine what other users have access to this information. 3.3.1 REG Message format The format of the message the client sends to the server to register Hiddink [Page 5] Internet Draft WWCP Part 5 July 15 1997 is: REG If the server finds this e-mail address already registered, it will send numeric 851, which means "You are already registered". If the user hasn't registered before, the server will send a numeric message 852, meaning "Registration in progress". It will then send a message to the designated e-mail address containing a unique user id and a server-generated password. This mail message is intended to be human readable, and there are no prescriptions as to the content of the message. 3.3.2 Error messages The conferencing server will send clients that have not registered (i.e. who have sent id "0") a numeric message: 850 You have not registered. Note that the textual information is not part of the protocol, and that clients shall not use this information (see also section 3.1). 3.4 Listing channels A client can list a directory by sending the message "LIST ", eg. "LIST chat". If the client wishes to receive the top directory, then no argument must be given. The client must cache this list during a session, and only delete it if it becomes dirty (see section 3.13). The output of the LIST message first starts with a header, the DIR message. In this message, the is the same as the LIST argument, or "TOP" if no argument was supplied. It looks as follows: LIST Then zero or more of the following lines are sent: DIR CHN Here, the and are the name of the subdirectory or channel in the requested directory. The list ends with an END message: Hiddink [Page 6] Internet Draft WWCP Part 5 July 15 1997 END consists of zero or more of characters. For directories, the following characters can be used: 'd' - it is allowed to create a directory inside that directory 'c' - it is allowed to create a channel inside that directory 'k' - the directory is unsuitable for users younger than 12 years 'a' - the directory is unsuitable for users younger than 18 years In the case of 'k' and 'a', the client should prohibit access to these directories if the user is not at an appropriate age. It is up to the client implementation to track this information. For channels, the following characters can be used: 'k' - the channel is unsuitable for users younger than 12 years 'a' - the channel is unsuitable for users younger than 18 years 'i' - access to the channel will only be granted after an invitation 'r' - the channel is registered 'b' - the channel is a broadcast channel 'u' - the number of users on the channel is unknown 'l' - the channel is local (is not shared with other servers) Note that the server will only know the number of users of channels it is on itself. The conferencing server will send '0' users if it doesn't know how many users are on the channel. The client is supposed to only retrieve the channel lists when it is really needed. The client shall not retrieve the entire tree at once. 3.4.1 Possible errors Error messages that can be sent to the client are: 910 Directory Service is offline Please recall that the textual information is not part of the protocol. 3.5 Listing users 3.6 Joining a channel 3.6.1 From client to server A client joins a channel by sending a message JOIN [] Hiddink [Page 7] Internet Draft WWCP Part 5 July 15 1997 to the server. The password is needed if the client is owner of the channel and wishes to identify himself (see section ##.##). If the channel does not exist, then the client will receive ... If the channel is in invite-only mode and the client has not been recently invited, then the client will receive .... Otherwise, the join will be succesful and the client will first receive user data of users on the channel, using the following message: MEET * where 'userid' is a number ranging from 1 to 65535, and where 'format' is a sequence of characters which determine what data items can be expected. The format string will contain one or more of the following: 'n' for nickname, a word conforming to what has been defined in section ##.## 'r' for realname, a string enclosed by double quotes 'e' for e-mail address, a word conforming to what has been defined in section ##.## 'a' for network address, either IP number or a hostname An example of this message is: MEET 8 12 nre Grit "Gerrit Hiddink" grit@wwcn.org i.e. the ID of the server "Grit" is on, as 8; on this server, the ID of this user is 12. According to the format parameter, the message contains the nickname, the realname and the e-mail address of the user. For each format character, the corresponding data item MUST be present. The order of the data items is the same as the order of the format characters. The format string shall always contain the character 'n' and the nickname shall always be present in the data items list. After that, the client will receive the following message: 3.6.2 From server to client If a client is present on a channel, then this client will receive updates of all evens that take place on the channel: joining users, leaving users, users that say lines, etcetera. A user joining a certain channel causes the following message to be sent to all clients connected to the server that are also on that channel: Hiddink [Page 8] Internet Draft WWCP Part 5 July 15 1997 JOIN The server to which the joining user is connected shall also send this message to the joining user itself to indicate that he has succesfully joined a channel. 3.7 Saying things at a channel 3.7.1 From client to server SAY where is | 3.7.2 From server to client SAY where is | 3.7.3 Error messages 3.8 Doing things at a channel The many years of IRC use brought to the attention that users want to 'do' things on a channel, i.e. the channel's output should not only reflect that users say things, but also that they virtually do things. Ususally, the client command is '/me', i.e. if a user named "John" types in his client: /me pours in another cup of coffee. then the text presented to the channel members is: * John pours in another cup of coffee. In WWCP client level 3, a command to do things is present: the ACT message. 3.8.1 From client to server ACT where is | This message should be sent by the client when the user enters a '/me' Hiddink [Page 9] Internet Draft WWCP Part 5 July 15 1997 or equivalent command. 3.8.2 From server to client ACT where is | This message shall prompt the client to display the nickname of the user (as sent in the SIGNON command, see sectino ##.##) in the channel's context. 3.8.3 Error messages 3.9 Selecting transport media 3.9.1 From server to client 3.9.2 From client to server 3.9.3 Error messages 3.10 Leaving a channel 3.10.1 From client to server A client leaves a channel by sending a message LEAVE channelname [reason] to the server. 3.10.2 From server to client A server shall send the following LEAVE message to every (local) client on a channel when another client (any client) leaves a channel: LEAVE userid serverid channelname [reason] 3.10.3 Error messages 3.11 Creating a channel 3.11.1 From client to server Hiddink [Page 10] Internet Draft WWCP Part 5 July 15 1997 3.11.2 Error messages 3.12 Creating a directory 3.13 Sending messages 3.13.1 From client to server 3.13.2 From server to client 3.13.3 Error messages 3.14 Inviting users 3.14.1 From client to server 3.14.2 From server to client 3.14.3 Error messages 3.15 Ignoring users 3.15.1 From client to server 3.15.2 From server to client 3.15.3 Error messages 3.16 Changing a nick 3.16.1 From client to server 3.16.2 From server to client 3.16.3 Error messages 3.17 Terminating servers A server that is shutting down, and is still healty enough to send network messages, will send an "IDIE" message to the clients. The format of this message is: 860 Shutting down: %s with %s being the reason why the server is shutting down. 3.18 Various error messages A server may send various other error messages. A list of these is given below. Hiddink [Page 11] Internet Draft WWCP Part 5 July 15 1997 910 Channel Directory Service is offline 911 User Directory Service is offline 4. Level 2 protocol This section describes the special message formats for level 2 clients. 4.1 Identifying a WWCP server As adapted IRC clients will have to distinguish between IRC servers and WWCP servers, a special string is sent in the RPL_MYINFO numeric (004). Note that this numeric is not part of RFC1459, but the majority int n = 0; of IRC clients and servers rely on it. Most clients use this numeric to identify the type of server they are connected to. This string is: 3.x.y WWCP level 2 with x and y being major and minor client-server protocol versions respectively, and being the FQDN (full query domain name) of the conferencing server. See also section xx of the WWCP protocol suite part x. This string shall be sent just after the client has identified itself using the NICK and USER messages (see RFC1459, section 4.1). 4.2 Listing channels One of the major (external) enhancements of WWCP is the `Usenet news-like' channel structure (see WWCP part 1, section 4.3). This has a large impact on the channel list handling by clients. In the following sections, conventions are presented for IRC messages in order to convey the extra information used by the WWCP protocol. 4.2.1 Directory permissions First of all, there are a few permissions imposed on directories: is it allowed to create a subdirectory or a channel, can a person aged below 12 or 18 enter it etcetera. These permissions are coded in numeric RPL_LIST as follows: 322 : The field consists either of the charter of the channel if is not a directory, or permissions if it is. The client will know that it is a directory if is zero. If so, it may interpret the field as follows: First, the field will contain a string "" to confirm that it is a directory. Hiddink [Page 12] Internet Draft WWCP Part 5 July 15 1997 Then, a string "mk-dir" is included if the client is allowed to make a subdirectoryunder . The string "mk-chan" is included if the client is allowed to create a channel under . Finally, a string may be included that indicates for what age category the channel is suitable, using one of the strings "k8", "k12", and "k16" for ages 8, 12 and 18 respectively. Clients will thus be able to disallow access to certain areas if, for example, the "adult" password has not been entered. The administration of the conferencing network will have to make sure top directories are given apropriate admission strings. The different parts of the field are seperated by spaces (one or more). Note that if a channel does not have a charter (which is the case when it is an unregistered channel), and the current channel topic is unknown, then consists of the string "Unregistered channel - Charter unknown". If the topic is known, then the field consists of the channel topic. 4.2.2 The channel list format 4.2.3 Errors 4.3 Joining channels 4.3.1 Registration information 4.3.2 Errors 4.4 Identical nicks Hiddink [Page 13]