"Fossies" - the Fresh Open Source Software Archive

Member "netbiff-0.9.18/PROTO" (21 Sep 2003, 3358 Bytes) of package /linux/privat/old/netbiff-0.9.18.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Netbiff is split into two parts. The front end is the interface to the user
    2 and is driven by user interaction and events from the back ends.  A single
    3 front end can support an arbitrary number of back ends (each referred to as a
    4 connection).  They communicate using a simple human-readable protocol.
    5 
    6 A connection is established when a front end unit executes a back end unit
    7 with the back end's standard input/output redirected to the front end.
    8 All communication occurs of this byte stream channel.
    9 
   10 Each protocol unit consists of a line of text delimited by whitespace and
   11 ending with a newline.  Requests are of the form
   12 <COMMAND> [ARGUMENTS]\n
   13 
   14 and responses are either of the form
   15 <STATUS> [EXPLANATION]\n
   16 or
   17 * <EVENT> [ARGUMENTS]\n
   18 
   19 Valid request commands are:
   20 
   21 FOLDER -- add the specified folder to the list of folders to be checked
   22 	(either on a POLL or to be interrupt-driven).  The argument specifies
   23 	the folder.
   24 
   25 POLL -- If an argument is given, poll the specified folder. Otherwise, poll
   26 	all previously specified folders. 
   27 
   28 DATARESPONSE -- The response to a requested data item.  The first
   29 space-delimited word is the tag of the data item (as given by the module's
   30 request); the remainder of the line is the data item itself (which is not
   31 allowed to contain newlines).
   32 
   33 
   34 QUIT -- terminate the session.
   35 
   36 
   37 Every request must receive a status response (though it is not necessarily
   38 the next piece of data).  In addition, a back end must send a status response
   39 upon startup to indicate either success or failure of its startup sequence.
   40 Valid response statuses are:
   41 
   42 OK -- the specified request completed successfully.
   43 
   44 NO -- an error occurred while processing the request.  This is often
   45 	accompanied by a human readable (i.e., suitable for user display)
   46 	explanation.
   47 
   48 BAD -- the request was malformed and should not be repeated.  This is often
   49 	accompanied by a human readable explanation and is typically
   50 	caused by programming errors.
   51 
   52 
   53 Event responses are referred to as "untagged responses" in the code (this
   54 term is borrowed from IMAP, which uses the '* ' syntax to indicate data that
   55 is not a direct status response to a request.  In IMAP, all status responses
   56 are tagged to match requests, and thus untagged responses are referred to as
   57 such. Here it makes no real sense).  Back ends may send untagged responses as
   58 a result of a request, but may also send them at its discretion (to
   59 facilitate non-polled checking). The valid events are:
   60 
   61 UPDATE -- The argument is a folder which has been updated. The user should be
   62 	notified.
   63 
   64 RESET -- The argument is a folder which no longer contains new information.
   65 	Any events which occured as a response to the UPDATE of that folder 
   66 	should be cancelled (e.g., the flag should go down).
   67 
   68 DATAREQUEST -- The module requests a piece of data from the frontend.  The
   69 	first whitespace-delimited argument is a tag for the data item. The
   70 	remainder of the line is a human-readable description (suitable for
   71 	presenting to a user).
   72 
   73 
   74 An example session follows:
   75 (front end messages are prepended with F:, back end messages with B:)
   76 B: OK Howdy.
   77 F: FOLDER
   78 B: BAD Command FOLDER requires an argument.
   79 F: FOLDER foo
   80 B: OK Folder foo added.
   81 F: FOLDER bar
   82 B: OK Folder bar added.
   83 F: POLL
   84 B: * UPDATE foo
   85 B: OK Poll completed
   86 F: FOLDER bleep
   87 B: NO Out of memory
   88 F: POLL foo
   89 B: * RESET foo
   90 F: QUIT
   91 B: OK Bye
   92