-<!-- $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, &buf, &size);
-if (!length_incoming) {
- fprintf(stderr, "Connection closed\n");
- exit(1);
-} else if (length_incoming < 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>
</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);
</para>
<synopsis>
- int cs_close(COMSTACK handle);
+ void cs_close(COMSTACK handle);
</synopsis>
<para>
</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);
</para>
<synopsis>
- char *cs_addrstr(COMSTACK);
+ const char *cs_addrstr(COMSTACK);
</synopsis>
<para>
</para>
<synopsis>
- <host> [ ':' <portnum> ]
+ <host> [ ':' <portnum> ]
</synopsis>
<para>
</para>
<synopsis>
- char *cs_addrstr(COMSTACK h);
+ const char *cs_addrstr(COMSTACK h);
</synopsis>
<para>
</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>
</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[];
+ 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 <yaz/comstack.h>
+ <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 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);
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>