include "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);
Init must be called once when the application starts, to set up its plumbing connections. Applications can choose to send messages, receive them, or do both. Note that the 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-oriented communication even without a window system.
If the application will be sending messages via the plumber, the value willsend must be non-zero, and init will open an appropriate channel to the plumber; if the application will not send messages, the value should be zero.
If the application is prepared to receive messages, the parameter rcvport names its logical input port, which must also be known to the plumber (ie, it must be named as a possible destination in plumbing(6)); init will open an appropriate channel to receive messages from the plumber. The parameter maxdata gives the size in bytes of the largest message the application is prepared to receive. Applications that only send messages set rcvport to nil.
Init returns 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.
The following program fragment establishes input and output plumbing for an application `edit':
plumbed := 0; plumbmsg = load Plumbmsg Plumbmsg->PATH; if(plumbmsg->init(1, "edit", 1000) >= 0) plumbed = 1;
The variable plumbed is set to allow the application to disable its plumbing user interface (and not attempt to send messages) if initialisation fails.
The Msg adt encapsulates the message data routed between applications and provides member functions to send and receive them. Its components are used as follows:
Plumbing messages are created directly using Limbo's ref operator, giving the desired value to each field. For example:
msg := ref Msg( "WmSh", "", workdir->init(), "text", attr, array of byte text);
The plumbing messages are exchanged with the plumber using two member functions:
Shutdown sends a message to the plumber that shuts down plumbing for the application's input port rcvport. An application must call it before it exits if it has an active input port.
String2attrs takes a string containing a tab-separated list of attribute pairs and returns a list of references to Attr adts.
Attr2string converts a list of references to Attr adts into a string of the form name=valuename=value . . . . The name=value pairs are separated by a single tab.
Lookup searches attrs for an attribute name, and if found, returns the tuple (1,value). If name is not found, lookup returns (0, nil).
Plumbing messages have a fixed structure: five lines of text giving UTF representations of the corresponding fields of Msg, then a line giving the length of data in decimal, followed by the bytes of data:
source\n destination\n directory\n kind\n attributes\n n\n n bytes
PLUMBMSG(2 ) | Rev: Thu Feb 15 14:43:27 GMT 2007 |