From 733dc40da2770d3ecb98d2d2cdc66b05a89bb390 Mon Sep 17 00:00:00 2001 From: Adam Dickmeiss Date: Tue, 6 Nov 2001 17:04:32 +0000 Subject: [PATCH] Mentions SSL and cs_create_host. Remove stuff about XTImOSI. --- doc/comstack.xml | 153 +++++++++++++++++++++++++++--------------------------- 1 file changed, 76 insertions(+), 77 deletions(-) diff --git a/doc/comstack.xml b/doc/comstack.xml index 741429c..e79871b 100644 --- a/doc/comstack.xml +++ b/doc/comstack.xml @@ -1,25 +1,28 @@ - + The COMSTACK Module Synopsis (blocking mode) -COMSTACK *stack; +COMSTACK stack; char *buf = 0; int size = 0, length_incoming; char *protocol_package; int protocol_package_length; -char server_address[] = "myserver.com:2100"; +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"); /* note use of perror() here since we have no stack yet */ + perror("cs_create"); /* use perror() here since we have no stack yet */ exit(1); } -status = cs_connect(stack, server_address); +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); @@ -58,14 +61,21 @@ 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 + RFC1729 method (BER over TCP/IP), 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 +87,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. @@ -97,19 +108,20 @@ if (buf) Creates an instance of the protocol stack - a communications endpoint. - The type parameter determines the mode of communication. + The type parameter determines the mode + of communication. At present, the values tcpip_type and - mosi_type + ssl_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. + 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. + Protocol PROTO_SR is no longer supported. - int cs_close(COMSTACK handle); @@ -227,7 +239,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 +252,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. @@ -308,13 +322,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); @@ -388,9 +402,7 @@ if (buf) - struct sockaddr_in *tcpip_strtoaddr(char *str); - - struct netbuf *mosi_strtoaddr(char *str); + void *cs_straddr(COMSTACK handle, const char *str); @@ -402,67 +414,53 @@ if (buf) - 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 OSI, the format is + In all 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. - - [ <t-selector> '/' ] <host> [ ':' <port> ] - - - The transport selector is given as an even number of hex digits. + When a connection has been established, you can use - - 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. - + + char *cs_addrstr(COMSTACK h); + - 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. + 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. - When a connection has been established, you can use + A fairly recent addition to the &comstack; module is the utility + function - - char cs_addrstr(COMSTACK h); + COMSTACK cs_create_host (const char *str, int blocking, void **vp); - - 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. + which is just a wrapper around 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: and ssl: for + TCP/IP 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. + For SSL (ssl_type) vp is an already create + OpenSSL CTX. For TCP/IP vp is unused (can be + set to NULL. - - - 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. - - - Diagnostics @@ -515,13 +513,14 @@ if (buf) #include <comstack.h> - #include <tcpip.h> /* this is for TCP/IP support */ - #include <xmosi.h> /* and this is for mOSI support */ + #include <tcpip.h> /* this is for TCP/IP and SSL 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); @@ -543,9 +542,9 @@ if (buf) int cs_look(COMSTACK handle); - struct sockaddr_in *tcpip_strtoaddr(char *str); + void *cs_straddr(COMSTACK handle, const char *str); - struct netbuf *mosi_strtoaddr(char *str); + char *cs_addrstr(COMSTACK h); extern int cs_errno; -- 1.7.10.4