.TH COLLABSRV 8.SH NAMEcollabsrv \- multi-user collaboration.SH SYNOPSIS.B collabsrv/collabsrv[.BI "-f " keyfile] [.BI "-n " netaddress] [.I dir].PP.B collabsrv/servers/chatsrv.PP.B collabsrv/servers/mpx.PP.B collabsrv/servers/wbsrv.SH DESCRIPTION.I Collabsrvlistens on network address.I netaddress(default:.BR tcp!*!9999 )for incoming requests to attach to servicesit offers.The services are defined by the contents of directory.IR dir(default:.BR /services/collab )..I Collabsrvserves an authenticated Styx connection that exports the contents of.IB dir /export(default:.BR /services/collab/export ).The exported name space can contain directories from a shared file server,but it will also contain a directory.B servicesgiving access to any collaborative activity services that have been configured..PPThe.B servicesdirectory contains a single.B ctlfile and a set of subdirectories, numbered.BR 0 ,.BR 1and so on.The.B ctlis used to activate and access services.Each service instance is identified by a name;clients connect to a given instance by presenting its name.Each directory represents one instance of a service.Each service instance corresponds to a name space; the clientsall share that name space.The name space is determined by the service..PPA client wishing to make use of the services must first.IR sys-dial (2)to connect to.IR collabsrv,and authenticate and mount the resulting Styx connection.It can do so using the.I mountcommand(see.IR bind (1)),or byusing.IR security-auth (2)and.B Sys->mount(see.IR sys-bind (2)).Normally, this is done by.IR collab (1)..PPA new connection to a particular service is requested by opening the.B ctlfile for reading and writing,writing a service request to it, and reading backthe number of the directory corresponding to the requested service.A service request written to.B ctlis text of the following form:.IP.DS.I "service id".DE.PPwhere.I serviceis a string specifying the type of service (eg,.BR chat )and.I idis a string identifying the instance.The server does not interpret.IR id ;it is up to the clients to agree a naming convention (oftenusing the name of a shared file as an.IR id )..I Collabsrvwill connect to instance.I idof the requested.I servicetypeif one is already running, or start one if necessary;the write request returns an error if the service cannot be started.Following a successful write to.BR ctl ,a read will return the number of the servicedirectory containing the client's private connection to that service instance.Closing the.B ctlfile disconnects from the service..PPAvailable services are defined by a configuration file.BR /services/collab/services.cfg ,which contains a sequence of configurationentries of the following form:.IP.EX.I service.br\f5	path=\fIdisfile\fP.EE.PPwhere.I serviceis the name presented in a service request, and.I disfilenames a Dis file implementing that service;path names are interpreted relative to.BR /services/collab ,but usually refer to files in.BR /dis/collabsrv/servers ..PPEach.I collabsrvservice is represented by a name space peculiar to that service.The interface to the service is therefore implemented by a service-specific Styx server.RI ( disfilein the configuration file).Current services are described below..SS "Chat".I Chatsrvprovides a simple service for the exchange of text messages.It serves a name space containing two files.The files together represent a single messaging group:.TF users.TP.B usersA read-only file that lists the user names of the current members of the group, one per line.The version number of the file's Qid(see.IR sys-stat (2))is incremented each time a client arrives or leaves..TP.B msgs.RSA client connects to the messaging group by opening this file.A message is sent to the group by writing to the file.Each read returns the next unread message, prefixed by the name of the sender,or.B <you>for a message sent by the current client.A client sees no messages sent before it connects.Messages are delivered in the same order to all clients; clients receive their own messages.Two special messages are generated by the server:.IP.EX+++ \fIname\fP has arrived--- \fIname\fP has left.EE.PPas clients come and go..RE.SS "Multiplexor".I Mpxoffers a general fan-out/fan-in multiplexing service for a tree of processes,with one controlling or root process at the root of the tree,and a set of client processes at the leaves of the tree.It serves three files:.TF users.TP.B rootAn exclusive-use file read and written by the root processto communicate with the leaf processes..TP.B leafClient processes read and write this file to communicate with theroot process (each.B openof.B leafis independent).It cannot be opened until a process has opened.BR root .After.B roothas been closed, and any remaining messages on.B leafhave been read,subsequent reads will return zero bytes (end-of-file)..TP.B usersA read-only text file that lists the user names of processes that currently have.B leafopen.There is one line per leaf, containing a unique numeric ID for the leaf, a space, and then the users's name..PPA message written to.B rootis replicated on all instances of.B leafthat are currently open.A message written to any instance of.B leafwill be read by the process reading.BR root .Data written to both.B rootand.B leafhas a prefix added to identify the sender, causing messagesto have the following format:.IP.EX.I "seq clientid op name data".EE.PPwhere.I seqis a unique message sequence number;.I clientidis a unique number identifying the process amongst currently connected clients,with 0 identifying the root process;.I opis a single character giving the message type (see below);.I nameis the sending process's user name; and.I datais the data written by the process, which can be text or binary (the message header is always text)..I Mpxalso generates messages as root and leaf processes arrive and leave.These are identified by.IR op .The various.I opvalues and the direction in which they can occur are listed below:.TP.B aNew leaf process has arrived (leaf to root).TP.B MMessage from root process (root to leaf).TP.B mMessage from leaf process (leaf to root).TP.B LRoot process has left (root to leaf).TP.B lLeaf process has left (leaf to root).PPMessages are only ever sent from the root to all leaves, or from a leaf to the root,never from leaf to leaf; the root process could of course rebroadcast a message from a leaf.The multiplexor service is used to implementa real-time poll(see.B polland.B pollerin.IR collab-clients (1)),but could be used for several other services, such as auctions..SS "Whiteboard".I Wbsrvoffers a service for sharing a simple line drawing.It serves two files:.TP.B wb.bitA read-only file containing an uncompressed.IR image (6)with the current state of the drawing..TP.B strokesThis file is read and written to exchange strokes with other clients.A stroke has the following representation:.RS.IP.IR "colour width x0 y0 x1 y1 " ....PPwhere all values are space-separated decimal numbers:.I colouris an index into the.IR rgbv (6)colour map;.I widthis the width of the line in pixels, andthe sequence of coordinate pairs defines the connected line segments to draw.A stroke is transmitted from one client to all others by writing a stroke description to the file in a single write.Each read returns a description of a stroke made by another client..RE.PPA whiteboard client should read the.B wb.bitfile to obtain its image, then read the.B strokesfile for instructions to keep it up to date..SH FILES.TF /services/collab/export/services.TP.B /services/collab/export/servicesactive service directory.TP.B /services/collab/services.cfgmaps service names to modules.TP.B /dis/collabsrv/serversservice implementation modules.SH SOURCE.B /appl/collabsrv.br.B /appl/collabsrv/servers.br.B /appl/collabsrv/lib.SH SEE ALSO.IR collab (1),.IR collab-clients (1)