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

diff --git a/doc/comstack.xml b/doc/comstack.xml
index 335eb0d..65e3d1d 100644
--- a/doc/comstack.xml
+++ b/doc/comstack.xml
@@ -1,57 +1,62 @@
-<!-- $Id: comstack.xml,v 1.10 2003-02-21 12:06:05 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>
@@ -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);
@@ -143,7 +148,7 @@ if (buf)
     </para>
 
     <synopsis>
-     int cs_close(COMSTACK handle);
+     void cs_close(COMSTACK handle);
     </synopsis>
 
     <para>
@@ -162,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);
@@ -399,7 +404,7 @@ if (buf)
    </para>
 
    <synopsis>
-    char *cs_addrstr(COMSTACK);
+    const char *cs_addrstr(COMSTACK);
    </synopsis>
 
    <para>
@@ -431,7 +436,7 @@ if (buf)
    </para>
 
    <synopsis>
-    &lt;host> &lsqb; ':' &lt;portnum> &rsqb;
+    &lt;host> [ ':' &lt;portnum> ]
    </synopsis>
 
    <para>
@@ -455,7 +460,7 @@ if (buf)
    </para>
 
    <synopsis>
-    char *cs_addrstr(COMSTACK h);
+    const char *cs_addrstr(COMSTACK h);
    </synopsis>
 
    <para>
@@ -490,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>
@@ -501,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);
      
@@ -567,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>