X-Git-Url: http://git.indexdata.com/?p=yaz-moved-to-github.git;a=blobdiff_plain;f=doc%2Fcomstack.xml;h=846b50729cc1275b6def23daa5c542fce8b3673f;hp=ae62b5e939a8e95e3396ed7a3278f170c2f9b485;hb=d51b21c6f41a021f21078921a0de50106264d55e;hpb=f0fff840ae259cab0b1c17297c4367172a7cd229 diff --git a/doc/comstack.xml b/doc/comstack.xml index ae62b5e..846b507 100644 --- a/doc/comstack.xml +++ b/doc/comstack.xml @@ -1,57 +1,67 @@ - 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_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); - + + @@ -69,7 +79,7 @@ if (buf) 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. @@ -101,25 +111,25 @@ if (buf) Common Functions - Managing Endpoints + Managing Endpoints COMSTACK cs_create(CS_TYPE type, int blocking, int protocol); - + Creates an instance of the protocol stack - a communications endpoint. 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 + Secure Socket Layer (SSL). This COMSTACK is experimental and is not fully implemented. If HTTP is used, this effectively is HTTPS. @@ -131,7 +141,7 @@ if (buf) - + The cs_create function returns a null-pointer if a system error occurs. @@ -143,7 +153,7 @@ if (buf) - int cs_close(COMSTACK handle); + void cs_close(COMSTACK handle); @@ -162,7 +172,7 @@ if (buf) - Data Exchange + Data Exchange int cs_put(COMSTACK handle, char *buf, int len); @@ -399,7 +409,7 @@ if (buf) - char *cs_addrstr(COMSTACK); + const char *cs_addrstr(COMSTACK); @@ -431,7 +441,7 @@ if (buf) - <host> [ ':' <portnum> ] + <host> [ ':' <portnum> ] @@ -440,22 +450,25 @@ if (buf) - For TCP/IP and SSL 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. + 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 UNIX sockets, the format of an address is the socket filename. - + When a connection has been established, you can use - char *cs_addrstr(COMSTACK h); + const char *cs_addrstr(COMSTACK h); @@ -483,9 +496,8 @@ if (buf) 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 and UNIX vp - is unused (can be set to NULL. + Parameter vp is reserved for future use. + Set it to NULL. @@ -530,7 +542,7 @@ if (buf) - + Diagnostics @@ -542,62 +554,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 <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 /* 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); - + 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); @@ -608,30 +617,31 @@ if (buf) 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); +]]> - - +