X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fcomstack.xml;h=436d84a0bef383dd9e4c18020ca1cf52f2503057;hp=9ae8df09538d89a092cbf93bc1c553b493e2073c;hb=053367cbe356fb3ce0def34b065dae589d700daf;hpb=33c05384cfbca55da4ff97e5b2047b16596c72f7 diff --git a/doc/comstack.xml b/doc/comstack.xml index 9ae8df0..436d84a 100644 --- a/doc/comstack.xml +++ b/doc/comstack.xml @@ -1,54 +1,62 @@ - The COMSTACK Module Synopsis (blocking mode) - - -COMSTACK *stack; -char *buf = 0; -int size = 0, length_incoming; -char *protocol_package; -int protocol_package_length; -char server_address[] = "myserver.com:2100"; -int status; - -stack = cs_create(tcpip_type, 1, PROTO_Z3950); -if (!stack) { - perror("cs_create"); /* note use of perror() here since we have no stack yet */ - exit(1); -} - -status = cs_connect(stack, server_address); -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); - + @@ -57,15 +65,23 @@ if (buf) 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 Peter Furniss' XTImOSI - stack are supported, but others may be added in time. The philosophy of the + stacks for the exchange of BER-encoded data and HTTP packets. + At present, 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. + + + There hasn't been interest in the XTImOSI stack for some years. + Therefore, it is no longer supported. + + + The interface is implemented in such a fashion that only the sub-layers constructed to the transport methods that you wish to @@ -77,11 +93,12 @@ if (buf) the interface is still orders of magnitudes more complex than the transport systems found in many other packages. One reason is that the interface needs to support the somewhat different requirements of - the different lower-layer communications stacks; another important reason is - that the interface seeks to provide a more or less industrial-strength - approach to asynchronous event-handling. When no function is allowed - to block, things get more complex - particularly on the server - side. We urge you to have a look at the demonstration client and server + the different lower-layer communications stacks; another important + reason is that the interface seeks to provide a more or less + industrial-strength approach to asynchronous event-handling. + When no function is allowed to block, things get more complex - + particularly on the server side. + We urge you to have a look at the demonstration client and server provided with the package. They are meant to be easily readable and instructive, while still being at least moderately useful. @@ -89,7 +106,7 @@ if (buf) Common Functions - Managing Endpoints + Managing Endpoints COMSTACK cs_create(CS_TYPE type, int blocking, int protocol); @@ -97,21 +114,41 @@ if (buf) Creates an instance of the protocol stack - a communications endpoint. - The type parameter determines the mode of communication. - At present, the values - tcpip_type - and - mosi_type - are recognized. The function returns a null-pointer if a system error - occurs. The blocking parameter should be one if you wish - the association to operate in blocking mode, zero otherwise. The - protocol field should be one of - PROTO_SR or PROTO_Z3950. + The type parameter determines the mode + of communication. At present the following values are supported: + + tcpip_type + TCP/IP (BER over TCP/IP or HTTP over TCP/IP) + + + ssl_type + Secure Socket Layer (SSL). This COMSTACK + is experimental and is not fully implemented. If + HTTP is used, this effectively is HTTPS. + + + unix_type + Unix socket (unix only). Local Transfer via + file socket. See unix + 7. + + + + + + The cs_create function returns a null-pointer + if a system error occurs. + The blocking parameter should be one if + you wish the association to operate in blocking mode, zero otherwise. + The protocol field should be + PROTO_Z3950 or PROTO_HTTP. + Protocol PROTO_SR is no longer supported. + - int cs_close(COMSTACK handle); + void cs_close(COMSTACK handle); @@ -130,7 +167,7 @@ if (buf) - Data Exchange + Data Exchange int cs_put(COMSTACK handle, char *buf, int len); @@ -155,8 +192,9 @@ if (buf) - 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 or HTTP Response 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 @@ -227,7 +265,8 @@ if (buf) CS_NONE - No event is pending. The data found on the line was not a complete package. + No event is pending. The data found on the line was not a + complete package. CS_CONNECT @@ -239,17 +278,18 @@ if (buf) CS_DISCON The other side has closed the connection (or maybe sent a disconnect request - but do we care? Maybe later). Call - cs_close to close your end of the association as well. + cs_close to close your end of the association + as well. CS_LISTEN - A connect request has been received. Call cs_listen - to process the event. + A connect request has been received. + Call cs_listen to process the event. CS_DATA - There's data to be found on the line. Call cs_get - to get it. + There's data to be found on the line. + Call cs_get to get it. @@ -285,12 +325,12 @@ if (buf) Initiate a connection with the target at address - (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 cs_rcvconnect to complete the operation, - when select(2) reports input pending on the - association. + when select(2) or poll(2) + reports input pending on the association. @@ -308,13 +348,13 @@ if (buf) Server Side - To establish a server under the inetd server, you - can use + To establish a server under the inetd + server, you can use COMSTACK cs_createbysocket(int socket, CS_TYPE type, int blocking, - int protocol); + int protocol); @@ -364,7 +404,7 @@ if (buf) - char *cs_addrstr(COMSTACK); + const char *cs_addrstr(COMSTACK); @@ -388,80 +428,113 @@ if (buf) - struct sockaddr_in *tcpip_strtoaddr(char *str); - - struct netbuf *mosi_strtoaddr(char *str); + void *cs_straddr(COMSTACK handle, const char *str); - The format for TCP/IP addresses is straightforward: + The format for TCP/IP and SSL addresses is: - <host> [ ':' <portnum> ] + <host> [ ':' <portnum> ] - The hostname can be either a domain name or an IP address. - The port number, if omitted, defaults to 210. + The hostname can be either a domain name or an + IP address. The port number, if omitted, defaults to 210. + + + + For TCP/IP and SSL, the special hostnames @, + maps to IN6ADDR_ANY_INIT with + IPV4 binding as well (bindv6only=0), + The special hostname @4 binds to + INADDR_ANY (IPV4 only listener). + The special hostname @6 binds to + IN6ADDR_ANY_INIT with bindv6only=1 (IPV6 only listener). - For OSI, the format is + For UNIX sockets, the format of an address is the socket filename. + + + + When a connection has been established, you can use - [ <t-selector> '/' ] <host> [ ':' <port> ] + const char *cs_addrstr(COMSTACK h); - The transport selector is given as an even number of hex digits. + to retrieve the host name of the peer system. The function returns + a pointer to a static area, which is overwritten on the next call + to the function. - You'll note that the address format for the OSI mode are just a subset - of full presentation addresses. We use presentation addresses because - xtimosi doesn't, in itself, allow access to the X.500 Directory - service. We use a limited form, because we haven't yet come across an - implementation that used more of the elements of a full p-address. It - is a fairly simple matter to add the rest of the elements to the - address format as needed, however: Xtimosi does - support the full P-address structure. + A fairly recent addition to the &comstack; module is the utility + function - + + COMSTACK cs_create_host (const char *str, int blocking, void **vp); + - In both transport modes, the special hostname "@" is mapped - to any local address (the manifest constant INADDR_ANY). - It is used to establish local listening endpoints in the server role. + which is just a wrapper for cs_create and + cs_straddr. The str + is similar to that described for cs_straddr + but with a prefix denoting the &comstack; type. Prefixes supported + are tcp:, unix: and + ssl: for TCP/IP, UNIX and SSL respectively. + If no prefix is given, then TCP/IP is used. + The blocking is passed to + function cs_create. The third parameter + vp is a pointer to &comstack; stack type + specific values. + Parameter vp is reserved for future use. + Set it to NULL. + + + SSL - When a connection has been established, you can use + + void *cs_get_ssl(COMSTACK cs); + + Returns the SSL handle, SSL * for comstack. If comstack + is not of type SSL, NULL is returned. - - char cs_addrstr(COMSTACK h); - + + + int cs_set_ssl_ctx(COMSTACK cs, void *ctx); + + Sets SSL context for comstack. The parameter is expected to be of type + SSL_CTX *. This function should be called just + after comstack has been created (before connect, bind, etc). + This function returns 1 for success; 0 for failure. + - to retrieve the host name of the peer system. The function returns a pointer - to a static area, which is overwritten on the next call to the function. + + int cs_set_ssl_certificate_file(COMSTACK cs, const char *fname); + + Sets SSL certificate for comstack as a PEM file. This function + returns 1 for success; 0 for failure. - - - We have left the issue of X.500 name-to-address mapping open, for the - moment. It would be a simple matter to provide a table-based mapping, - if desired. Alternately, we could use the X.500 client-function that - is provided with the ISODE (although this would defeat some of the - purpose of using ThinOSI in the first place. We have been told that it - should be within the realm of the possible to implement a lightweight - implementation of the necessary X.500 client capabilities on top of - ThinOSI. This would be the ideal solution, we feel. On the other hand, it - still remains to be seen just what role the Directory will play in a world - populated by ThinOSI and other pragmatic solutions. - - + + + + int cs_get_ssl_peer_certificate_x509(COMSTACK cs, char **buf, int *len); + + This function returns the peer certificate. If successful, + *buf and *len holds + X509 buffer and length respectively. Buffer should be freed + with xfree. This function returns 1 for success; + 0 for failure. + @@ -476,59 +549,59 @@ if (buf) - When a function (including the data exchange functions) reports an - error condition, use the function - cs_errno() to determine the cause of the - problem. The function + The error code for the COMSTACK can be retrieved using C macro + cs_errno which will return one + of the error codes CSYSERR, + CSOUTSTATE, + CSNODATA, ... - void cs_perror(COMSTACK handle char *message); + int cs_errno(COMSTACK handle); - works like perror(2) and prints the - message argument, along with a system message, to - stderr. Use the character array + You can the textual representation of the error code + by using cs_errmsg - which + works like strerror(3) - extern const char *cs_errlist[]; + const char *cs_errmsg(int n); - 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 + cs_strerror. - const char *cs_stackerr(COMSTACK handle); + const char *cs_strerror(COMSTACK h); - - Returns an error message from the lower layer, if one has been - provided. - Summary and Synopsis - - #include <comstack.h> - - #include <tcpip.h> /* this is for TCP/IP support */ - #include <xmosi.h> /* and this is for mOSI support */ - + + + #include /* this is for TCP/IP and SSL support */ + #include /* 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); + 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); @@ -539,21 +612,14 @@ if (buf) int cs_more(COMSTACK handle); - int cs_close(COMSTACK handle); + void cs_close(COMSTACK handle); int cs_look(COMSTACK handle); - struct sockaddr_in *tcpip_strtoaddr(char *str); - - struct netbuf *mosi_strtoaddr(char *str); - - extern int cs_errno; - - void cs_perror(COMSTACK handle char *message); - - const char *cs_stackerr(COMSTACK handle); + void *cs_straddr(COMSTACK handle, const char *str); - extern const char *cs_errlist[]; + const char *cs_addrstr(COMSTACK h); +]]> @@ -569,7 +635,7 @@ if (buf) sgml-indent-step:1 sgml-indent-data:t sgml-parent-document: "yaz.xml" - sgml-local-catalogs: "../../docbook/docbook.cat" + sgml-local-catalogs: nil sgml-namecase-general:t End: -->