dependencies/yaz_3.0.14/doc/comstack.common.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>3. Common Functions</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><link rel="start" href="index.html" title="YAZ User's Guide and Reference"><link rel="up" href="comstack.html" title="Chapter 11. The COMSTACK Module"><link rel="prev" href="comstack.introduction.html" title="2. Introduction"><link rel="next" href="comstack.client.html" title="4. Client Side"></head><body><link rel="stylesheet" type="text/css" href="common/style1.css"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3. Common Functions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="comstack.introduction.html">Prev</a> </td><th width="60%" align="center">Chapter 11. The COMSTACK Module</th><td width="20%" align="right"> <a accesskey="n" href="comstack.client.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="comstack.common"></a>3. Common Functions</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="comstack.managing.endpoints"></a>3.1. Managing Endpoints</h3></div></div></div><pre class="synopsis">
   2      COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
   3     </pre><p>
   4      Creates an instance of the protocol stack - a communications endpoint.
   5      The <code class="literal">type</code> parameter determines the mode
   6      of communication. At present the following values are supported:
   7     </p><div class="variablelist"><dl><dt><span class="term"><code class="literal">tcpip_type</code></span></dt><dd><p>TCP/IP (BER over TCP/IP or HTTP over TCP/IP)
   8        </p></dd><dt><span class="term"><code class="literal">ssl_type</code></span></dt><dd><p>Secure Socket Layer (SSL). This COMSTACK
   9         is experimental and is not fully implemented. If
  10         HTTP is used, this effectively is HTTPS.
  11        </p></dd><dt><span class="term"><code class="literal">unix_type</code></span></dt><dd><p>Unix socket (unix only). Local Transfer via
  12         file socket. See <span class="citerefentry"><span class="refentrytitle">unix</span>(7)</span>.
  13        </p></dd></dl></div><p>
  14      The <code class="function">cs_create</code> function returns a null-pointer
  15      if a system error occurs.
  16      The <code class="literal">blocking</code> parameter should be one if
  17      you wish the association to operate in blocking mode, zero otherwise.
  18      The <code class="literal">protocol</code> field should be
  19      <code class="literal">PROTO_Z3950</code> or <code class="literal">PROTO_HTTP</code>.
  20      Protocol <code class="literal">PROTO_SR</code> is no longer supported.
  21     </p><pre class="synopsis">
  22      int cs_close(COMSTACK handle);
  23     </pre><p>
  24      Closes the connection (as elegantly as the lower layers will permit),
  25      and releases the resources pointed to by the
  26      <code class="literal">handle</code>
  27      parameter. The
  28      <code class="literal">handle</code>
  29      should not be referenced again after this call.
  30     </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
  31       We really need a soft disconnect, don't we?
  32      </p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="comstack.data.exchange"></a>3.2. Data Exchange</h3></div></div></div><pre class="synopsis">
  33      int cs_put(COMSTACK handle, char *buf, int len);
  34     </pre><p>
  35      Sends
  36      <code class="literal">buf</code>
  37      down the wire. In blocking mode, this function will return only when a
  38      full buffer has been written, or an error has occurred. In nonblocking
  39      mode, it's possible that the function will be unable to send the full
  40      buffer at once, which will be indicated by a return value of 1. The
  41      function will keep track of the number of octets already written; you
  42      should call it repeatedly with the same values of <code class="literal">buf</code>
  43      and <code class="literal">len</code>, until the buffer has been transmitted.
  44      When a full buffer has been sent, the function will return 0 for
  45      success. -1 indicates an error condition (see below).
  46     </p><pre class="synopsis">
  47      int cs_get(COMSTACK handle, char **buf, int *size);
  48     </pre><p>
  49      Receives a PDU or HTTP Response from the peer. Returns the number of
  50      bytes read.
  51      In nonblocking mode, it is possible that not all of the packet can be
  52      read at once. In this case, the function returns 1. To simplify the
  53      interface, the function is
  54      responsible for managing the size of the buffer. It will be reallocated
  55      if necessary to contain large packages, and will sometimes be moved
  56      around internally by the subsystem when partial packages are read. Before
  57      calling
  58      <code class="function">cs_get</code>
  59      for the fist time, the buffer can be initialized to the null pointer,
  60      and the length should also be set to 0 - cs_get will perform a
  61      <code class="function">malloc(2)</code>
  62      on the buffer for you. When a full buffer has been read, the size of
  63      the package is returned (which will always be greater than 1). -1
  64      indicates an error condition.
  65     </p><p>
  66      See also the <code class="function">cs_more()</code> function below.
  67     </p><pre class="synopsis">
  68      int cs_more(COMSTACK handle);
  69     </pre><p>
  70      The <code class="function">cs_more()</code> function should be used in conjunction
  71      with <code class="function">cs_get</code> and
  72      <code class="function">select(2)</code>.
  73      The <code class="function">cs_get()</code> function will sometimes
  74      (notably in the TCP/IP mode) read more than a single protocol package
  75      off the network. When this happens, the extra package is stored
  76      by the subsystem. After calling <code class="function">cs_get()</code>, and before
  77      waiting for more input, You should always call
  78      <code class="function">cs_more()</code>
  79      to check if there's a full protocol package already read. If
  80      <code class="function">cs_more()</code>
  81      returns 1,
  82      <code class="function">cs_get()</code>
  83      can be used to immediately fetch the new package. For the
  84      mOSI
  85      subsystem, the function should always return 0, but if you want your
  86      stuff to be protocol independent, you should use it.
  87     </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
  88       The <code class="function">cs_more()</code>
  89       function is required because the RFC1729-method
  90       does not provide a way of separating individual PDUs, short of
  91       partially decoding the BER. Some other implementations will carefully
  92       nibble at the packet by calling
  93       <code class="function">read(2)</code>
  94       several times. This was felt to be too inefficient (or at least
  95       clumsy) - hence the call for this extra function.
  96      </p></div><pre class="synopsis">
  97      int cs_look(COMSTACK handle);
  98     </pre><p>
  99      This function is useful when you're operating in nonblocking
 100      mode. Call it when
 101      <code class="function">select(2)</code>
 102      tells you there's something happening on the line. It returns one of
 103      the following values:
 104     </p><div class="variablelist"><dl><dt><span class="term">CS_NONE</span></dt><dd><p>
 105         No event is pending. The data found on the line was not a
 106         complete package.
 107        </p></dd><dt><span class="term">CS_CONNECT</span></dt><dd><p>
 108         A response to your connect request has been received. Call
 109         <code class="function">cs_rcvconnect</code>
 110         to process the event and to finalize the connection establishment.
 111        </p></dd><dt><span class="term">CS_DISCON</span></dt><dd><p>
 112         The other side has closed the connection (or maybe sent a disconnect
 113         request - but do we care? Maybe later). Call
 114         <code class="function">cs_close</code> to close your end of the association
 115         as well.
 116        </p></dd><dt><span class="term">CS_LISTEN</span></dt><dd><p>
 117         A connect request has been received.
 118         Call <code class="function">cs_listen</code> to process the event.
 119        </p></dd><dt><span class="term">CS_DATA</span></dt><dd><p>
 120         There's data to be found on the line.
 121         Call <code class="function">cs_get</code> to get it.
 122        </p></dd></dl></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
 123       You should be aware that even if
 124       <code class="function">cs_look()</code>
 125       tells you that there's an event event pending, the corresponding
 126       function may still return and tell you there was nothing to be found.
 127       This means that only part of a package was available for reading. The
 128       same event will show up again, when more data has arrived.
 129      </p></div><pre class="synopsis">
 130      int cs_fileno(COMSTACK h);
 131     </pre><p>
 132      Returns the file descriptor of the association. Use this when
 133      file-level operations on the endpoint are required
 134      (<code class="function">select(2)</code> operations, specifically).
 135     </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="comstack.introduction.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="comstack.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="comstack.client.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. Introduction </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 4. Client Side</td></tr></table></div></body></html>