X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fcomstack.xml;h=65e3d1d5f1465075660ad566bc870c052257e062;hp=4c2c6ba5811ac728fadc6c262dcf62755ff51134;hb=32e80f00a5c06ad5d5de0d4205897197a770fd31;hpb=d82eeac05d2899fa30704e2c40e9dd603ff2c581

diff --git a/doc/comstack.xml b/doc/comstack.xml
index 4c2c6ba..65e3d1d 100644
--- a/doc/comstack.xml
+++ b/doc/comstack.xml
@@ -1,57 +1,62 @@
-<!-- $Id: comstack.xml,v 1.9 2002-08-17 07:55:51 adam Exp $ -->
  <chapter id="comstack"><title>The COMSTACK Module</title>
   
   <sect1 id="comstack.synopsis"><title>Synopsis (blocking mode)</title>
    
-   <programlisting>
+   <programlisting><![CDATA[
+    COMSTACK stack;
+    char *buf = 0;
+    int size = 0, length_incoming;
+    char server_address_str[] = "localhost:9999";
+    void *server_address_ip;
+    int status;
+
+    char *protocol_package = "GET / HTTP/1.0\r\n\r\n";
+    int protocol_package_length = strlen(protocol_package);
+
+    stack = cs_create(tcpip_type, 1, PROTO_HTTP);
+    if (!stack) {
+        perror("cs_create");  /* use perror() here since we have no stack yet */
+        return -1;
+    }
     
-COMSTACK stack;
-char *buf = 0;
-int size = 0, length_incoming;
-char *protocol_package; 
-int protocol_package_length;
-char server_address_str[] = "myserver.com:2100";
-void *server_address_ip;
-int status;
-
-stack = cs_create(tcpip_type, 1, PROTO_Z3950);
-if (!stack) {
-    perror("cs_create");  /* use perror() here since we have no stack yet */
-    exit(1);
-}
-
-server_address_ip = cs_addrstr (stack, server_address_str);
-
-status = cs_connect(stack, server_address_ip);
-if (status != 0) {
-    cs_perror(stack, "cs_connect");
-    exit(1);
-}
-
-status = cs_put(stack, protocol_package, protocol_package_length);
-if (status) {
-    cs_perror(stack, "cs_put");
-    exit(1);
-}
-
-/* Now get a response */
-
-length_incoming = cs_get(stack, &amp;buf, &amp;size);
-if (!length_incoming) {
-    fprintf(stderr, "Connection closed\n");
-    exit(1);
-} else if (length_incoming &lt; 0) {
-    cs_perror(stack, "cs_get");
-    exit(1);
-}
-
-/* Do stuff with buf here */
-
-/* clean up */
-cs_close(stack);
-if (buf)
-    free(buf);
+    server_address_ip = cs_straddr(stack, server_address_str);
+    if (!server_address_ip)
+    {
+        fprintf(stderr, "cs_straddr: address could not be resolved\n");
+        return -1;
+    }
     
+    status = cs_connect(stack, server_address_ip);
+    if (status != 0) {
+        fprintf(stderr, "cs_connect: %s\n", cs_strerror(stack));
+        return -1;
+    }
+    
+    status = cs_put(stack, protocol_package, protocol_package_length);
+    if (status) {
+        fprintf(stderr, "cs_put: %s\n", cs_strerror(stack));
+        return -1;
+    }
+    /* Now get a response */
+    
+    length_incoming = cs_get(stack, &buf, &size);
+    if (!length_incoming) {
+        fprintf(stderr, "Connection closed\n");
+        return -1;
+    } else if (length_incoming < 0) {
+        fprintf(stderr, "cs_get: %s\n", cs_strerror(stack));
+        return -1;
+    }
+    
+    /* Print result */
+    fwrite(buf, length_incoming, 1, stdout);
+    
+    /* clean up */
+    cs_close(stack);
+    if (buf)
+        free(buf);
+    return 0;
+]]>
    </programlisting>
 
   </sect1>
@@ -60,8 +65,8 @@ if (buf)
    <para>
     The &comstack;
     subsystem provides a transparent interface to different types of transport
-    stacks for the exchange of BER-encoded data. At present, the
-    RFC1729 method (BER over TCP/IP), local UNIX socket and an
+    stacks for the exchange of BER-encoded data and HTTP packets.
+    At present, the RFC1729 method (BER over TCP/IP), local UNIX socket and an
     experimental SSL stack are supported, but others may be added in time.
     The philosophy of the
     module is to provide a simple interface by hiding unused options and
@@ -101,7 +106,7 @@ if (buf)
   </sect1>
   <sect1 id="comstack.common"><title>Common Functions</title>
 
-   <sect2><title>Managing Endpoints</title>
+   <sect2 id="comstack.managing.endpoints"><title>Managing Endpoints</title>
 
     <synopsis>
      COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
@@ -115,16 +120,17 @@ if (buf)
     
     <variablelist>
      <varlistentry><term><literal>tcpip_type</literal></term>
-      <listitem><para>TCP/IP (BER over TCP/IP)
+      <listitem><para>TCP/IP (BER over TCP/IP or HTTP over TCP/IP)
        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>ssl_type</literal></term>
       <listitem><para>Secure Socket Layer (SSL). This COMSTACK 
-        is experimental and is not fully implemented.
+        is experimental and is not fully implemented. If
+        HTTP is used, this effectively is HTTPS.
        </para></listitem>
      </varlistentry>
      <varlistentry><term><literal>unix_type</literal></term>
-      <listitem><para>Unix socket (unix only). Fast local transfer via
+      <listitem><para>Unix socket (unix only). Local Transfer via
         file socket. See <citerefentry><refentrytitle>unix</refentrytitle>
          <manvolnum>7</manvolnum></citerefentry>.
        </para></listitem>
@@ -137,12 +143,12 @@ if (buf)
      The <literal>blocking</literal> parameter should be one if
      you wish the association to operate in blocking mode, zero otherwise.
      The <literal>protocol</literal> field should be
-     <literal>PROTO_Z3950</literal>.
+     <literal>PROTO_Z3950</literal> or <literal>PROTO_HTTP</literal>.
      Protocol <literal>PROTO_SR</literal> is no longer supported.
     </para>
 
     <synopsis>
-     int cs_close(COMSTACK handle);
+     void cs_close(COMSTACK handle);
     </synopsis>
 
     <para>
@@ -161,7 +167,7 @@ if (buf)
     </note>
    </sect2>
 
-   <sect2><title>Data Exchange</title>
+   <sect2 id="comstack.data.exchange"><title>Data Exchange</title>
 
     <synopsis>
      int cs_put(COMSTACK handle, char *buf, int len);
@@ -186,7 +192,8 @@ if (buf)
     </synopsis>
 
     <para>
-     Receives a PDU from the peer. Returns the number of bytes read.
+     Receives a PDU or HTTP Response from the peer. Returns the number of
+     bytes read.
      In nonblocking mode, it is possible that not all of the packet can be
      read at once. In this case, the function returns 1. To simplify the
      interface, the function is
@@ -397,7 +404,7 @@ if (buf)
    </para>
 
    <synopsis>
-    char *cs_addrstr(COMSTACK);
+    const char *cs_addrstr(COMSTACK);
    </synopsis>
 
    <para>
@@ -429,7 +436,7 @@ if (buf)
    </para>
 
    <synopsis>
-    &lt;host> &lsqb; ':' &lt;portnum> &rsqb;
+    &lt;host> [ ':' &lt;portnum> ]
    </synopsis>
 
    <para>
@@ -453,7 +460,7 @@ if (buf)
    </para>
 
    <synopsis>
-    char *cs_addrstr(COMSTACK h);
+    const char *cs_addrstr(COMSTACK h);
    </synopsis>
 
    <para>
@@ -488,6 +495,47 @@ if (buf)
 
   </sect1>
 
+  <sect1 id="comstack.ssl"><title>SSL</title>
+   <para>
+    <synopsis>
+     void *cs_get_ssl(COMSTACK cs);
+    </synopsis>
+    Returns the SSL handle, <literal>SSL *</literal> for comstack. If comstack
+    is not of type SSL, NULL is returned.
+   </para>
+
+   <para>
+    <synopsis>
+     int cs_set_ssl_ctx(COMSTACK cs, void *ctx);
+    </synopsis>
+    Sets SSL context for comstack. The parameter is expected to be of type
+    <literal>SSL_CTX *</literal>. This function should be called just
+    after comstack has been created (before connect, bind, etc).
+    This function returns 1 for success; 0 for failure.
+   </para>
+
+   <para>
+    <synopsis>
+     int cs_set_ssl_certificate_file(COMSTACK cs, const char *fname);
+    </synopsis>
+    Sets SSL certificate for comstack as a PEM file. This function
+    returns 1 for success; 0 for failure.
+   </para>
+
+
+   <para>
+    <synopsis>
+     int cs_get_ssl_peer_certificate_x509(COMSTACK cs, char **buf, int *len);
+    </synopsis>
+    This function returns the peer certificate. If successful,
+    <literal>*buf</literal> and <literal>*len</literal> holds
+    X509 buffer and length respectively. Buffer should be freed
+    with <literal>xfree</literal>. This function returns 1 for success;
+    0 for failure.
+   </para>
+
+  </sect1>
+  
   <sect1 id="comstack.diagnostics"><title>Diagnostics</title>
 
    <para>
@@ -499,55 +547,52 @@ if (buf)
    </para>
 
    <para>
-    When a function (including the data exchange functions) reports an
-    error condition, use the function
-    <function>cs_errno()</function> to determine the cause of the
-    problem. The function
+    The error code for the COMSTACK can be retrieved using C macro
+    <function>cs_errno</function> which will return one
+    of the error codes <literal>CSYSERR</literal>,
+    <literal>CSOUTSTATE</literal>,
+    <literal>CSNODATA</literal>, ...
    </para>
 
    <synopsis>
-    void cs_perror(COMSTACK handle char *message);
+    int cs_errno(COMSTACK handle);
    </synopsis>
 
    <para>
-    works like <function>perror(2)</function> and prints the
-    <literal>message</literal> argument, along with a system message, to
-    <literal>stderr</literal>. Use the character array
+    You can the textual representation of the error code
+    by using <function>cs_errmsg</function> - which
+    works like <function>strerror(3)</function>
    </para>
 
    <synopsis>
-    extern const char *cs_errlist&lsqb;&rsqb;;
+    const char *cs_errmsg(int n);
    </synopsis>
-
+   
    <para>
-    to get hold of the message, if you want to process it differently.
-    The function
+    It is also possible to get straight to the textual represenataion
+    without the error code by using 
+    <function>cs_strerror</function>.
    </para>
-
+   
    <synopsis>
-    const char *cs_stackerr(COMSTACK handle);
+    const char *cs_strerror(COMSTACK h);
    </synopsis>
-
-   <para>
-    Returns an error message from the lower layer, if one has been
-    provided.
-   </para>
+   
   </sect1>
   <sect1 id="comstack.summary"><title>Summary and Synopsis</title>
 
-   <synopsis>
-    #include &lt;yaz/comstack.h>
+   <synopsis><![CDATA[
+    #include <yaz/comstack.h>
     
-    #include &lt;yaz/tcpip.h>  /* this is for TCP/IP and SSL support */
-    #include &lt;yaz/unix.h>   /* this is for UNIX sockeL support */
+    #include <yaz/tcpip.h>  /* this is for TCP/IP and SSL support */
+    #include <yaz/unix.h>   /* this is for UNIX socket support */
     
-     
     COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
      
     COMSTACK cs_createbysocket(int s, CS_TYPE type, int blocking,
                                int protocol);
-    COMSTACK cs_create_host (const char *str, int blocking,
-                             void **vp);
+    COMSTACK cs_create_host(const char *str, int blocking,
+                            void **vp);
      
     int cs_bind(COMSTACK handle, int mode);
      
@@ -565,21 +610,14 @@ if (buf)
 
     int cs_more(COMSTACK handle);
 
-    int cs_close(COMSTACK handle);
+    void cs_close(COMSTACK handle);
 
     int cs_look(COMSTACK handle);
 
     void *cs_straddr(COMSTACK handle, const char *str);
 
-    char *cs_addrstr(COMSTACK h);
-
-    extern int cs_errno;
-
-    void cs_perror(COMSTACK handle char *message);
-
-    const char *cs_stackerr(COMSTACK handle);
-
-    extern const char *cs_errlist[];
+    const char *cs_addrstr(COMSTACK h);
+]]>
    </synopsis>
   </sect1>