X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fcomstack.xml;h=846b50729cc1275b6def23daa5c542fce8b3673f;hp=0be19367559a21c6417430dec56e2fee4a20937e;hb=d51b21c6f41a021f21078921a0de50106264d55e;hpb=c2317ad6444bd2a90a45fd519f286a7cef49c776

diff --git a/doc/comstack.xml b/doc/comstack.xml
index 0be1936..846b507 100644
--- a/doc/comstack.xml
+++ b/doc/comstack.xml
@@ -1,56 +1,67 @@
  <chapter id="comstack"><title>The COMSTACK Module</title>
-  
+
   <sect1 id="comstack.synopsis"><title>Synopsis (blocking mode)</title>
-   
-   <programlisting>
-    
-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);
-    
+
+   <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;
+    }
+
+    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) {
+        fprintf(stderr, "cs_connect: %s\n", cs_strerror(stack));
+        return -1;
+    }
+
+    status = cs_rcvconnect(stack);
+    if (status) {
+        fprintf(stderr, "cs_rcvconnect: %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)
+        xfree(buf);
+    return 0;
+]]>
    </programlisting>
 
   </sect1>
@@ -68,7 +79,7 @@ if (buf)
     of losing generality, and it may prove that the interface will need
     extension later on.
    </para>
-   
+
    <note>
     <para>
      There hasn't been interest in the XTImOSI stack for some years.
@@ -105,20 +116,20 @@ if (buf)
     <synopsis>
      COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
     </synopsis>
-    
+
     <para>
      Creates an instance of the protocol stack - a communications endpoint.
      The <literal>type</literal> parameter determines the mode
      of communication. At present the following values are supported:
     </para>
-    
+
     <variablelist>
      <varlistentry><term><literal>tcpip_type</literal></term>
       <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 
+      <listitem><para>Secure Socket Layer (SSL). This COMSTACK
         is experimental and is not fully implemented. If
         HTTP is used, this effectively is HTTPS.
        </para></listitem>
@@ -130,7 +141,7 @@ if (buf)
        </para></listitem>
       </varlistentry>
      </variablelist>
-     
+
     <para>
      The <function>cs_create</function> function returns a null-pointer
      if a system error occurs.
@@ -142,7 +153,7 @@ if (buf)
     </para>
 
     <synopsis>
-     int cs_close(COMSTACK handle);
+     void cs_close(COMSTACK handle);
     </synopsis>
 
     <para>
@@ -398,7 +409,7 @@ if (buf)
    </para>
 
    <synopsis>
-    char *cs_addrstr(COMSTACK);
+    const char *cs_addrstr(COMSTACK);
    </synopsis>
 
    <para>
@@ -439,22 +450,25 @@ if (buf)
    </para>
 
    <para>
-    For TCP/IP and SSL transport modes, the special hostname &quot;@&quot;
-    is mapped to any local address
-    (the manifest constant <literal>INADDR_ANY</literal>).
-    It is used to establish local listening endpoints in the server role.
+    For TCP/IP and SSL, the special hostnames <literal>@</literal>,
+    maps to <literal>IN6ADDR_ANY_INIT</literal> with
+    IPV4 binding as well (bindv6only=0),
+    The special hostname <literal>@4</literal> binds to
+    <literal>INADDR_ANY</literal> (IPV4 only listener).
+    The special hostname <literal>@6</literal> binds to
+    <literal>IN6ADDR_ANY_INIT</literal> with bindv6only=1 (IPV6 only listener).
    </para>
 
    <para>
     For UNIX sockets, the format of an address is the socket filename.
    </para>
-   
+
    <para>
     When a connection has been established, you can use
    </para>
 
    <synopsis>
-    char *cs_addrstr(COMSTACK h);
+    const char *cs_addrstr(COMSTACK h);
    </synopsis>
 
    <para>
@@ -482,9 +496,8 @@ if (buf)
     function <function>cs_create</function>. The third parameter
     <parameter>vp</parameter> is a pointer to &comstack; stack type
     specific values.
-    For SSL (ssl_type) <parameter>vp</parameter> is an already create
-    OpenSSL CTX. For TCP/IP and UNIX <parameter>vp</parameter>
-    is unused (can be set to <literal>NULL</literal>.
+    Parameter <parameter>vp</parameter> is reserved for future use.
+    Set it to <literal>NULL</literal>.
    </para>
 
   </sect1>
@@ -529,7 +542,7 @@ if (buf)
    </para>
 
   </sect1>
-  
+
   <sect1 id="comstack.diagnostics"><title>Diagnostics</title>
 
    <para>
@@ -561,40 +574,39 @@ if (buf)
    <synopsis>
     const char *cs_errmsg(int n);
    </synopsis>
-   
+
    <para>
     It is also possible to get straight to the textual represenataion
-    without the error code by using 
+    without the error code by using
     <function>cs_strerror</function>.
    </para>
-   
+
    <synopsis>
     const char *cs_strerror(COMSTACK h);
    </synopsis>
-   
+
   </sect1>
   <sect1 id="comstack.summary"><title>Summary and Synopsis</title>
 
-   <synopsis>
-    #include &lt;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 */
-    
-     
+   <synopsis><![CDATA[
+    #include <yaz/comstack.h>
+
+    #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);
-     
+
     int cs_connect(COMSTACK handle, void *address);
-     
+
     int cs_rcvconnect(COMSTACK handle);
-     
+
     int cs_listen(COMSTACK handle);
 
     COMSTACK cs_accept(COMSTACK handle);
@@ -605,21 +617,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>