psyc:[//{hostname}[:{port}]][/{object-name}][?{commands,options}].
A default port number will have to be decided upon.
The object-name is one of the following:
Leaving the object-name out means you are referencing the PSYC server itself for information and registration purposes. Commands can be passed to the adressed target, in a format like this: {commands} := {command}[?{arguments}][+{commands}]. So a typical UNI in a WWW page would be psyc://psyc.fsf.org/+announce?join and one in a .signature psyc://psyc.org/~lynx/. Routing suggestions may also be specified in UNIs.
User service programs handle issues like requests for login notification, "whois" information or answering machine type message deposit.
Channel control programs handle JOIN and LEAVE requests plus political issues in channel administration as implementing channel operators, topic information, moderations, access control.
These programs are implemented in an object-oriented fashion (instances of programs can be cloned for every psyc-object that wants to be serviced). In a small psyc server implementation this can be done in C++ or C, in a more complex implementation the server would provide an interpreted programming language to write channel programs in. The interpreter scripts can keep data sets for every object they represent. Since a psyc server can be installed by anyone, this gives great flexibility to the channel creators, to implement their favourite political schemes, and add extra functionality and information as they desire.
PSYC does however need at least one common protocol on the message delivery layer to send its conference control messages on. To this end a MDP message delivery protocol is proposed in a specification of its own.
The implementation of protocols is independent from PSYC, and older or simpler user agents would just ignore the protocols they are unable to transmit on. This implies that every receiver should also provide a conservative means of being reached.
The Message Delivery Layer is supposed to prepare delivery of messages. {logical_target} is the UNI for the target, pointing to the program that handles requests for the target, be it a group or a single. {physical_target}+ is a list of receivers, which are each specified by a list of UNLs (uniform network location) that may be used to address them. The MDL may then choose the best suited protocols to deliver the data to each receiver.
MDL_deliver (logical_target, message...)
{message}+ is one or more PSYC messages as described below. When multiple messages are given, the delivery layer is encouraged to send them as a whole.
PSYC_receive (source, logical_target, message...)
This is a callback-type function. {source} is the UNI of the originator of the incoming message(s).
{message} :=
{msg flags} := {8 bits}
{msg type} := {8 bits}
[ {tag} := {null-terminated string} ]
[ {auth info} := {null-terminated string} ]
[ {content type} := {null-terminated string} ]
[ {header} := {null-terminated string} ]
{msg data}
{msg flags} := {is reply} # bit 0
# bit 1
{is compressed} # bit 2
{is encrypted} # bit 3
{tag given} # bit 4
{auth info given} # bit 5
{content type given} # bit 6
{header given} # bit 7
The {msg flags} are meant to tell what optional elements of the message
are present and how it is affected. There is a law that no reply may be
generated to a message with the {is reply} flag set. This to avoid
automatons getting deadlocked in so-called message wars.
{msg type} is explained further below.
{content type} is intended to be like HTTP content types, which is similar to MIME content types. It describes the type of data contained in this particular message.
A {tag} containing any kind of null-terminated data can optionally be added in queries and will be returned in replies to be able to match up queries with replies.
{auth info} may contain any cookie as appropriate for the selected {authorization method}, to help ensure identity of sender over unreliable networks.
{header} contains additional information for all kinds of present and future extensions. It is a set of {field-name} and {field-value} pairs seperated by colons (':') and newlines (0x10) much like mail headers. Unrecognized information can be ignored, but should be relayed if the message is.
{msg data} is data according to the message type.
{msg type} :=
0x00: NOTICE # an automatic reply of informative nature
0x01: WARNING # an automatic reply stating some problem
0x02: ERROR # an automatic reply describing an error
0x20: TEMP_MOVE # temporary new UNI for sender
0x21: PERM_MOVE # permanent change of UNI
0x30: TEMP_RENAME # temporary new {name} for sender
0x31: PERM_RENAME # permanent change of {name}
0x40: COMMAND # an {instruction} (to a program)
0x41: QUERY # a {query} (to a program)
0x48: PING # AYT query or answer if {is reply} set
0x50: BROWSE # {data} of given {content type}
0x51: FILE # store {data} to disk instead
0x60: CONTENT_TYPE # define or query {content type}
0x61: COMPRESSION_METHOD # define or query {compression method}
0x62: ENCRYPTION_METHOD # define or query {encryption method}
0x63: AUTHORIZATION_METHOD # define or query {authorization m.}
0x70: HEADER # set or query overall settings
0x71: HEADER_MOD # modify or query overall settings
0x80: TEXT # simple {text} message
0x81: DESCRIPTION # descriptive type of {text} message
0xc0: LEAVE_GROUP # sender is leaving this group
0xd0: GROUP_MEMBERS # list of {members} of a group
0xd1: GROUP_MEMBERS_MOD # {modification of member list}
0xe2: GROUP_AUTHORITY # {authority} objects for a group
0xe3: GROUP_AUTHORITY_MOD # {modification of authority}
0xf0: GROUP_FLAGS # {group flags}
A TEXT is a message typed in by a human for humans to read, so it should be displayed appropriately with a nickname (and maybe a face) prepended, like this:
(nickname) text
A DESCRIPTION is an alternative to TEXT which should be displayed like this:
* nickname textBut these are just recommendations.
A NOTICE is a special reply message produced by an automaton, such as a channel program. As the first word in the {text} an integer is provided, which is used to identify the type of reply. Standard such {numeric} codes are discussed later. NOTICE_X denotes unusual notices for which no standard {numeric} code is applicable.
An ERROR is the stronger form of a NOTICE with its set of {numeric} codes.
All {text} type messages are encoded in ISO-8859-1, unless specified otherwise by a "Charset:" {header}.
A COMMAND is an instruction to an automaton normally issued by a human. JOIN and LEAVE are typical ones.
QUERY is similar to COMMAND, but should not alter the state of the remote target. It is used to request an other user's client version, for instance.
Both BROWSE and FILE imply that the data you have received is actually of the negotiated {content type}, which is not the case with any other message type. One suggests you to present the data to the user, the other suggests to prompt the user for file storage. In the latter case an extra {header} called "Name:" indicating a file name for the resource should be provided. Optionally also a "URI:" header indicating where the resource normally resides.
The following four set, query or report (when {is reply} is set) their corresponding values. {content type} has been described above. {compression method} may be gzip, compress or anything fancier. {encryption method} may be crypt, des, pgp or anything fancier. {authorization method} may be anything fancy.
HEADER and HEADER_MOD are used to setup header fields that are valid throughout the whole communication. A Japanese "Charset:" would be set up this way. HEADER resets the whole set of header settings while HEADER_MOD modifies them.
#### leaving out details of some message types here..
{group flags} := {one byte}
# with bits like this:
#
# 1 0x01: AUTHORITY_ADD
# 2 0x02: AUTHORITY_DEL
# 3 0x04: MEMBER_ADD
# 4 0x08: MEMBER_DEL
# 5 0x10: PUBLIC
# 6,7 # reserved: ignore the contents, generate zero
# 8 0x80: MODERATED
AUTHORITY_ADD means every member of the channel is allowed to
declare an additional channel authority by means of the GROUP_AUTHORITY_MOD
message. A client itself isn't an authority, but if it can handle that, he
can then declare itself one. But normally authority will be kept by a few.
AUTHORITY_DEL means every channel member may disable authorities.
This is a risky flag to enable. On the receiving side, if an incoming message
attempts to remove authorities, although this flag has not been set on the
group, the whole message is discarded, even if it contains valid additions.
PUBLIC means your client is allowed to give out the members list of the group to other network objects. This way people outside the group can send messages to the group.
MEMBER_ADD means your client is authorized to send a join message for an external object, adding him to the group. This is done with the GROUP_MEMBERS_MOD +{client} message. And it only makes sense if you're also enabled to give him the list of members. MEMBER_DEL also enables a client to remove a member from the group, to effectively kick him off the group. But normally this is achieved by command to the authority, so it won't be used.
MODERATED means not even people in the group may speak to each other. They only listen to what the channel authority has to say. In most cases this is just an informative message to the client, since it will probably not even receive the list of channel members. When the client receives this flag, it should not expect the member list to follow.