-<!-- $Id: comstack.xml,v 1.7 2002-02-24 12:23:43 adam Exp $ -->
+<!-- $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>
-
+
COMSTACK stack;
char *buf = 0;
int size = 0, length_incoming;
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), and an experimental SSL stack
- are supported, but others may be added in time. The philosophy of 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
facilities of the underlying libraries. This is always done at the risk
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.
<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 values
- <literal>tcpip_type</literal>
- and
- <literal>ssl_type</literal>
- are recognized. The function returns a null-pointer if a system error
- occurs. The <literal>blocking</literal> parameter should be one if
+ 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)
+ </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.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry><term><literal>unix_type</literal></term>
+ <listitem><para>Unix socket (unix only). Fast local transfer via
+ file socket. See <citerefentry><refentrytitle>unix</refentrytitle>
+ <manvolnum>7</manvolnum></citerefentry>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <function>cs_create</function> function returns a null-pointer
+ if a system error occurs.
+ 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>.
</synopsis>
<para>
- Receives a PDU from the peer. Returns the number of bytes
- read. In nonblocking mode, it is possible that not all of the packet can be
+ Receives a PDU 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
responsible for managing the size of the buffer. It will be reallocated
<para>
Initiate a connection with the target at <literal>address</literal>
- (more onaddresses below). The function will return 0 on success, and 1 if
+ (more on addresses below). The function will return 0 on success, and 1 if
the operation does not complete immediately (this will only
happen on a nonblocking endpoint). In this case, use
<function>cs_rcvconnect</function> to complete the operation,
- when <function>select(2)</function> reports input pending on the
- association.
+ when <function>select(2)</function> or <function>poll(2)</function>
+ reports input pending on the association.
</para>
<synopsis>
</synopsis>
<para>
- The format for TCP/IP addresses is straightforward:
+ The format for TCP/IP and SSL addresses is:
</para>
<synopsis>
</para>
<para>
- In all transport modes, the special hostname "@" is mapped
- to any local address (the manifest constant <literal>INADDR_ANY</literal>).
+ 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.
</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>
COMSTACK cs_create_host (const char *str, int blocking, void **vp);
</synopsis>
<para>
- which is just a wrapper around <function>cs_create</function> and
+ which is just a wrapper for <function>cs_create</function> and
<function>cs_straddr</function>. The <parameter>str</parameter>
is similar to that described for <function>cs_straddr</function>
but with a prefix denoting the &comstack; type. Prefixes supported
- are <literal>tcp:</literal> and <literal>ssl:</literal> for
- TCP/IP and SSL respectively. If no prefix is given, then TCP/IP
- is used. The <parameter>blocking</parameter> is passed to
+ are <literal>tcp:</literal>, <literal>unix:</literal> and
+ <literal>ssl:</literal> for TCP/IP, UNIX and SSL respectively.
+ If no prefix is given, then TCP/IP is used.
+ The <parameter>blocking</parameter> is passed to
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 <parameter>vp</parameter> is unused (can be
- set to <literal>NULL</literal>.
+ OpenSSL CTX. For TCP/IP and UNIX <parameter>vp</parameter>
+ is unused (can be set to <literal>NULL</literal>.
</para>
</sect1>
</sect1>
<sect1 id="comstack.summary"><title>Summary and Synopsis</title>
- <synopsis>
- #include <comstack.h>
-
- #include <tcpip.h> /* this is for TCP/IP and SSL support */
+ <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 */
+
COMSTACK cs_create(CS_TYPE type, int blocking, int protocol);
projects / yaz-moved-to-github.git / blobdiff