-<!-- $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>
-
-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);
-
+
+ <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>
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.
</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);
</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>
</para></listitem>
</varlistentry>
</variablelist>
-
+
<para>
The <function>cs_create</function> function returns a null-pointer
if a system error occurs.
</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>
<para>
- For TCP/IP and SSL transport modes, the special hostname "@"
- 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>
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>
+
+ <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>
</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>
-
- #include <yaz/tcpip.h> /* this is for TCP/IP and SSL support */
- #include <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);
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>
projects / yaz-moved-to-github.git / blobdiff