#ifndef _AGENT_H_7616ad23_
#define _AGENT_H_7616ad23_

/* This file is in the public domain. */

/*
 * Definitions for various agent stuff.
 */

/*
 * Agent connection type values.  The connection between client and
 *  agent sends at least two bytes along with the fd.  (The reason it
 *  always sends at least two is for backward compatability: all
 *  previous versions sent only one byte.  Since they left its value
 *  indeterminate, we can't use its value to distinguish between
 *  new-style connections and backward-compatability connections.  So
 *  we treat all one-byte connections as compatability connections.
 *  This means sending at least two bytes with all new-style
 *  connections even if we don't need the second one.)
 *
 * AGENT_PROTO_NORMAL marks regular connections.  The second byte is
 *  unused.  The accompanying file descriptor carries ordinary
 *  agent<->client protocol.  This is equivalent to the compatability
 *  behaviour when only one byte is sent.
 *
 * AGENT_PROTO_INTERACTIVE marks interactive agent connections.  The
 *  second byte is unused; the accompanying file descriptor carries a
 *  private protocol (documented below).
 *
 * Do not change the numeric values of any of these.  They appear in
 *  octets between agent client and agent server; changing them will
 *  break client/server interoperability across the change.
 */
typedef enum {
	  AGENT_PROTO_NORMAL = 1,
	  AGENT_PROTO_INTERACTIVE
	  } AGENT_PROTO;

/*
 * The private protocol carried over AGENT_PROTO_INTERACTIVE
 *  connections is very simple, amounting to little more than a
 *  packetizing protocol wrapped around a traditional line-oriented
 *  command-line interface.
 *
 * In the client->server direction, each line of user input, of length
 *  L, is converted into 4+L bytes on the wire.  The first four bytes
 *  hold L, in network byte order; the rest hold the line.  (The
 *  newline that terminates the line on stdin is not considered part of
 *  the line for these purposes.)  There is no way to describe a line
 *  of more than 4294967295 bytes.
 *
 * In the server->client direction, the protocol is similar but not
 *  identical.  The first difference is that if there are N bytes of
 *  data to send, there are 5+N bytes of wire data (not 4+N); the first
 *  four bytes are N, in network byte order, followed with one byte of
 *  flag bits (see below), then the N bytes of data.  The second
 *  difference is that newlines are treated as part of the data stream
 *  in this direction.  Arbitrary amounts of data may be transferred,
 *  but no more than 4294967295 bytes per blob.
 */

/*
 * Flag bits used in the private protocol for AGENT_PROTO_INTERACTIVE
 *  agent connections.  These go in the byte after the length, in
 *  server->client messages.
 *
 * REPLY, if set, indicates that the message is a reply to something
 *  the client sent.  If clear, the message is a gratuitous
 *  (asynchronous) message, such as a notification of other client
 *  action.  (This bit actually means "clear one queued command and
 *  reprompt if no more queued commands pending"; it can also be clear
 *  on something that is a reply to the client but which will be
 *  followed by another message bearing more data that belongs to the
 *  same reply.)
 */
#define AGENT_INTER_REPLY 0x01

#endif