NAME
Haver::Spec - The core haver protocol.
DESCRIPTION
This document describes the core functionality of the Haver protocol. It is not as comprehensive as the Manual, but it is slightly better than keeping these things in plain text files.
BEGIN YOUR FEAR
Here's a general overview with examples. Lines beginning with C: are from the client, and lines beginning with S: are from the server. Items enclosed in square brackets are optional.
HAVER/IDENT/HELLO
$supported
is a comma-seperated last of supported extensions (See "EXTENSIONS")
C: HAVER Foobar/1.0 [$supported]
S: HAVER example.com FoobarServer/1.0
C: IDENT $name
S: HELLO $name
JOIN/PART/LIST
$namespace
is one of "user", "service", or "channel".
C: JOIN $channel
S: JOIN $channel $user
C: PART $channel
S: PART $channel $user
C: LIST $channel $namespace
S: LIST $channel $namespace Thing1 Thing2 Thing3
IN/TO/FROM
Public messages (a message sent to everyone in a channel)
C: IN $channel $type @args
S: IN $channel $user $type @args
Private messages (a message sent ot a select group of users)
C: TO $users $type @args
S: FROM $users $type @args
Clients must use any word (/^\w+$/
) for $type, but it is typically "do" or "say".
INFO
C: INFO $namespace $name
S: INFO $namespace $name $key1 $value1 $key2 $value2 ...
Sending this message results in the server sending back a message (S:INFO) with a list of key/value pairs. The keys vary depending on what is queried. Different server implementations may add extra keys too. Good user agents will allow the user to see any and all keys assigned to entity, even ones that did not exist when the user agent was programmed.
Keys for Users and Services
- address
-
A (probably masked) IP address. E.g. 1.2.3.*
- version
-
The name and version number of the user-agent and service program, as sent by C:HAVER.
- idle
-
The number of seconds the client has been idle. For users, idle is defined as the length of time between sending TO or IN messages.
-
The email address of the user or service. All registered services and users will have email addresses associated with them.
Keys for Channels
- creator
-
The name of the user that created the channel.
- created
-
The date and time the channel was created.
Keys for the Lobby
- booted
-
The date and time the server was booted.
- hostname
-
The hostname of the server.
- version
-
The version name of the server, the same as from S:HAVER.
POKE/OUCH
POKE is used to see if the server is alive. The server will respond with OUCH.
C: POKE $string
S: OUCH $string
PING/PONG
If the server sends PING, the client must respond with PONG, like so:
S: PING $string
C: PONG $string
BYE/QUIT
To disconnect, a client should send BYE:
C: BYE $detail
The server will reply with:
S: BYE $type $detail
All users sharing a channel with the client will see:
S: QUIT $sender $type $detail
The $type of quit is one of several things:
closed
error ($detail = error code?)
bye ($detail = from BYE)
ping
ghost
kill ($detail = killer)
YOU FAIL
The server may respond to any given message with FAIL, which has the form of:
S: FAIL $cmd $error [@args]
Where $cmd is the name of the message that failed, $error is the error name, and @args are bits of information related to the error.
invalid.name
You used a name that contains invalid characters.
reserved.name
You used a name that contains characters only special people are allowed to use.
exists.user
The user name you requested is in use.
unknown.user
That user name does not exist on the server.
unknown.channel
That channel name does not exist on the server.
unknown.namespace
The namespace (used in LIST, for example) is not one that the server is aware of.
invalid.type
The $type argument of an IN or TO message contained non-word characters.
already.joined
Tried to join a channel that you're already in.
already.parted
Tried to part a channel you're not in.
I MEAN, HI
I could describe the messages here in greater detail, but I think that belongs in the manual. There might be some other useful information to put in this section, too. But it is five thirteen in the morning, so I can't think of it.
EXTENSIONS
Currently defined extensions: Haver::Spec::Ghost, Haver::Spec::Auth, Haver::Spec::Reg.
AUTHOR
Dylan William Hardison, <dylan@haverdev.org>
SEE ALSO
COPYRIGHT and LICENSE
Copyright (C) 2005 by Dylan William Hardison. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This module is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this module; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA