.TH PLUMBMSG 2.SH NAMEplumbmsg \- plumbing message module.SH SYNOPSIS.EXinclude "plumbmsg.m";plumbmsg := load Plumbmsg Plumbmsg->PATH;Msg: import plumbmsg; Msg: adt{    src:    string;    dst:    string;     dir:    string;    kind:   string;    attr:   string;    data:   array of byte;    # used by applications    send:   fn(msg: self ref Msg): int;    recv:   fn(): ref Msg;    # used by plumb and send, recv    pack:   fn(msg: self ref Msg): array of byte;    unpack: fn(b: array of byte): ref Msg;}; Attr: adt{    name: string;    val:  string;}; init:         fn(willsend: int, rcvport: string, maxdata: int): int;shutdown:     fn();string2attrs: fn(s: string): list of ref Attr;attrs2string: fn(l: list of ref Attr): string;lookup:       fn(attrs: list of ref Attr, name: string): (int, string);.EE.SH DESCRIPTION.B Plumbmsgis an interface for message-passing between applicationsvia the.IR plumber (8).It allows applications to receive messages from the plumber on a logical input port,and send messages to other applications via the plumber..PP.B Initmust be called once when the application starts, toset up its plumbing connections.Applications can choose to send messages, receive them, or do both.Note thatthe plumber must be running before any of these functions are useful.Normally, that is done by the window system's initialisation procedure,but in specialised systems, plumbing can be used for attribute-orientedcommunication even without a window system..PPIf the application will be sendingmessages via the plumber, the value.I willsendmust be non-zero, and.B initwill open an appropriate channel to the plumber; if the applicationwill not send messages, the value should be zero..PPIf the application is prepared to receive messages, the parameter.I rcvportnames its logical input port,which must also be known to the plumber (ie, it mustbe named as a possible destination in.IR plumbing (6));.B initwill open an appropriate channel to receive messages from the plumber.The parameter.I maxdatagives the size in bytes of the largest messagethe application is prepared to receive.Applications that only send messages set.I rcvportto nil..PP.B Initreturns returns -1 if for any reason either connection cannot be set up correctly,in particular if the plumber is not running or the input port is unknown.Otherwise it returns a non-negative value..PPThe following program fragment establishes input and output plumbingfor an application `edit':.IP.EXplumbed := 0;plumbmsg = load Plumbmsg Plumbmsg->PATH;if(plumbmsg->init(1, "edit", 1000) >= 0)	plumbed = 1;.EE.PPThe variable.B plumbedis set to allow the application to disable its plumbing user interface(and not attempt to send messages) if initialisation fails..PPThe.B Msgadtencapsulates the message data routed between applications andprovides member functions to send and receive them.Its components are used as follows:.TF dataxx.PD.TP.B srcThe name of the program generating the message..TP.B dstThe output port to which the plumber should route the message.In practice, destination is often left empty, andthe destination port will be determined bythe plumber applying the automatic routing rules(cf..IR plumbing (6)).TP.B dirThe directory in which to interpret the data (eg, if the data is a local file name)..TP.B kindThe format of the data.Currently,.RB ` text 'is the only type that applications understand, but the plumbing systemcan route any kind of data..TP.B attrA string containing.IB name = valuepairs (eg,.BR click=7 ),separated by tabs.Normally the value should be created using.B attrs2stringand parsed using.BR string2attrs ,described below..TP.B dataThe message to be conveyed.If.B kindis.BR text ,and the message is a string.IR s ,.B datawill be.RB ` array.B of.BI byte " s'"(ie, its UTF encoding)..PD.PPPlumbing messages are created directly using Limbo's.B refoperator, giving the desired value to each field.For example:.IP.EX	msg := ref Msg(		"WmSh",		"",		workdir->init(),		"text",		attr,		array of byte text);.EE.PPThe plumbing messages are exchanged withthe plumberusing two member functions:.TP.IB m .send( msg )Writes a plumbing message to theplumber.It returns the number of bytes written (the result of.I writein.IR sys-read (2)which does the writing).It returns -1 if the plumber cannot route the message..TP.B Msg.recv()Reads a plumbing message from the filerepresenting the application's input port,previously opened by.BR init .It waits for a message, and returns a reference to a.B Msgthat contains the message data..PP.B Shutdownsends a message to the plumberthat shuts down plumbing for the application's input port.IR rcvport .An application.I mustcall it before it exits if it has an active input port..PP.B String2attrstakes a string containing a tab-separated list of attribute pairs and returns a list of references to.B Attradts..PP.B Attr2stringconverts a list of references to.B Attradts into a string of the form.IB name = value name = value\&. . .  .The.IB name = valuepairs are separated by a single tab..PP.B Lookupsearches.I attrsfor an attribute.IR name ,and if found, returns the tuple.BI (1, value ) .If.I nameis not found,.B lookupreturns.BR "(0, nil)" ..SS Packed message formatThe format of plumbing messages as transmitted, and member functionsthat encapsulate it, are documented here for completeness, and in casethe details are useful in interpreting plumbing messages outside the Inferno environment..PPPlumbing messages have a fixed structure: five lines of textgiving UTF representations of thecorresponding fields of.BR Msg ,then a line giving the length of.B datain decimal,followed by the bytes of.BR data :.IP.nf.IB source \en.IB destination \en.IB directory \en.IB kind \en.IB attributes \en.IB n \en.IB n " bytes".fi.PPThe details are encapsulated in two functions:.TP.IB m .pack().B Packpacks the contents.B Msg.I minto an array of byte for subsequent transmission using.I write(see.IR sys-read (2))..TP.BI Msg.unpack( b )Unpack unpacks an array of byte.I bto form a copy of the original.BR Msg ,which it returns..SH FILES.TF /chan/plumb.rcvport.TP.B /chan/plumb.inputfile to send messages to the plumber.TP.BI /chan/plumb. rcvportfile to receive messages routed to the logical name.I rcvport.SH SOURCE.B /appl/lib/plumbmsg.b.SH BUGS.I Shutdownshould not be needed:the.IR plumber (8),as a file server, must know that a particular client has vanished.