NAME

       rpcbuf - streambuf specialized for sending and receiving RPC requests

SYNOPSIS

       #include <Dispatch/rpcbuf.h>

DESCRIPTION

       An  rpcbuf is a streambuf specialized in two ways: to use an IPC connection as a source or
       sink of characters and to send and receive RPC requests.  The rpcbuf encloses RPC requests
       in  packets  which  begin with a length field so that the rpcbuf can buffer requests until
       they are complete if the user uses non-blocking I/O.

CONSTRUCTORS

       rpcbuf(iostreamb* = nil)
              Construct an unopened rpcbuf, giving it a pointer  to  an  iostreamb  so  that  the
              rpcbuf can read and write the length field of RPC requests.

IPC OPERATIONS

       const char* host()
       int port()
       int fd()
       boolean opened()
       boolean nonblocking()
              Return information about the IPC connection.

       enum { anyport = 0 }
       rpcbuf* listen(int port)
              Create  a  socket,  bind  the socket to a <localhost, port> address, and prepare to
              accept incoming connections.  anyport can be used  in  place  of  a  specific  port
              number.  Return the rpcbuf's address if successful, nil otherwise.

       rpcbuf* connect(const char* host, int port)
              Create  a  socket and connect it to a peer at the <host, port> address.  Return the
              rpcbuf's address if successful, nil otherwise.

       rpcbuf* accept(int& fd)
              Accept an incoming connection, allocate a new file descriptor for  it,  and  assign
              the  new  file  descriptor  to  the  parameter.   Return  the  rpcbuf's  address if
              successful, nil otherwise.  Can be called only for rpcbufs that have already called
              listen.

       rpcbuf* attach(int fd)
              Attach  the  rpcbuf  to a file descriptor.  The rpcbuf will not be allowed to close
              the file descriptor.

       rpcbuf* nonblocking(boolean)
              Enable or disable non-blocking I/O on the file descriptor (disabled by default).

       rpcbuf* verbose(boolean)
              Enable or disable printing of error messages when anything goes wrong  (enabled  by
              default).

       rpcbuf* close()
              Flush  the  get  and  put areas, close the file descriptor if it was created by the
              rpcbuf, and detach the rpcbuf from the file descriptor.

RPC OPERATIONS

       int start_request()
              If a current request exists, compute its length and  insert  the  length  into  the
              request's  length  field.  Then start a new request, making sure to leave space for
              the request's length field.  Return 0 if no problem occurred, EOF otherwise.

       int read_request()
              Return 0 if a complete request is buffered in the get  area,  EOF  otherwise.   The
              rpcbuf  moves the get pointer back to the beginning of the request after extracting
              the length field and checking that the get area contains that many bytes.

STREAMBUF OPERATIONS

       virtual int overflow(int c=EOF)
              If given EOF, terminate the current request.  Flush all requests  buffered  in  the
              put  area  except  for  the last request if it's still incomplete.  Shift any still
              incomplete request to the beginning of the put area.  If given a character,  append
              it to the request.

       virtual int underflow()
              Flush the put area.  Shift any still unread or incomplete requests to the beginning
              of the get area and position the get pointer at the  beginning  of  the  get  area.
              Read  as  much  data as available to fill the rest of the get area.  Return the get
              area's first character or EOF if a problem occurred.

       virtual int sync()
              Discard any still unread requests from the get area.  Flush all  buffered  requests
              from the put area.

       virtual streampos seekoff(streamoff, ios::seek_dir, int)
              Allow  the  user to find the get pointer's current position so the user can compute
              how many bytes the get pointer moved between calls to seekoff.  Return EOF  if  the
              user tries to do anything else than find the get pointer's current position.

       virtual streambuf* setbuf(char*, int)
              Reject  any attempt to set the buffer used to store incoming and outgoing requests.
              The rpcbuf dynamically allocates separate buffers for both areas and  automatically
              resizes the buffers whenever necessary.

SEE ALSO

       IOS.INTRO(3C++), rpcstream(3I)