Implements Generic COMSTACK functions. More...

#include <string.h>
#include <errno.h>
#include <limits.h>
#include <yaz/yaz-iconv.h>
#include <yaz/log.h>
#include "comstack-p.h"
#include <yaz/tcpip.h>
#include <yaz/unix.h>
#include <yaz/odr.h>
#include <yaz/matchstr.h>
#include <yaz/atoi.h>

Functions
const char *	cs_errmsg (int n)
	Returns a static message for a COMSTACK error code.
const char *	cs_strerror (COMSTACK h)
	Returns a static message for the endpoint's last error.
int	cs_get_error (COMSTACK cs, const char **details)
	Returns the last COMSTACK error and optional transport details.
void	cs_get_host_args (const char type_and_host, const char *args)
	Extracts application arguments from a host or URI specification.
int	cs_parse_host (const char uri, const char host, CS_TYPE t, enum oid_proto proto, char *connect_host)
	Parses transport and protocol prefixes without resolving an address.
COMSTACK	cs_create_host (const char vhost, int flags, void *vp)
	Creates an endpoint from a host or URI specification.
COMSTACK	cs_create_host_proxy (const char vhost, int flags, void vp, const char proxy_host)
	Creates an endpoint with an optional proxy.
COMSTACK	cs_create_host2 (const char vhost, int flags, void vp, const char proxy_host, int *proxy_mode)
	Creates an endpoint and selects direct or proxy connection handling.
int	cs_look (COMSTACK cs)
	Returns the last recorded event (CS_NONE, CS_CONNECT, etc.).
static int	skip_crlf (const char buf, int len, int i)
static int	http_token_char (char c)
int	yaz_http_parse_chunks (const char buf, int len, char content_buf, int *content_len)
static int	cs_complete_http (const char *buf, int len, int head_only)
static int	cs_complete_auto_x (const char *buf, int len, int head_only)
int	cs_complete_auto (const char *buf, int len)
	Finds the length of a complete BER or HTTP message.
int	cs_complete_auto_head (const char *buf, int len)
	Finds the length of a BER message or HTTP headers.
int	cs_set_head_only (COMSTACK cs, int head_only)
	Selects HTTP header-only framing for TCP/IP, SSL or UNIX transports.
void	cs_set_max_recv_bytes (COMSTACK cs, int max_recv_bytes)
	Sets the maximum incoming message size.

Variables
static const char *	cs_errlist []

Detailed Description

Implements Generic COMSTACK functions.

Definition in file comstack.c.

Function Documentation

◆ cs_complete_auto()

int cs_complete_auto	(	const char *	buf,
		int	len )

Finds the length of a complete BER or HTTP message.

Parameters

buf	input bytes
len	number of available bytes

Returns: message length, 0 if incomplete, -1 on protocol error

Examines the first message only; does not modify the input.

Definition at line 514 of file comstack.c.

References cs_complete_auto(), and cs_complete_auto_x().

Referenced by cs_complete_auto(), tcpip_rcvconnect(), tcpip_state_create(), unix_type(), yaz_tcpip_set_head_only(), and yaz_unix_set_head_only().

◆ cs_complete_auto_head()

int cs_complete_auto_head	(	const char *	buf,
		int	len )

Finds the length of a BER message or HTTP headers.

Parameters

buf	input bytes
len	number of available bytes

Returns: message length, 0 if incomplete, -1 on protocol error

Examines the first message only; does not modify the input.

Definition at line 519 of file comstack.c.

References cs_complete_auto_head(), and cs_complete_auto_x().

Referenced by cs_complete_auto_head(), tcpip_rcvconnect(), yaz_tcpip_set_head_only(), and yaz_unix_set_head_only().

◆ cs_complete_auto_x()

int cs_complete_auto_x	(	const char *	buf,
		int	len,
		int	head_only )

static

Definition at line 501 of file comstack.c.

References completeBER_n(), cs_complete_auto_x(), and cs_complete_http().

Referenced by cs_complete_auto(), cs_complete_auto_head(), and cs_complete_auto_x().

◆ cs_complete_http()

int cs_complete_http	(	const char *	buf,
		int	len,
		int	head_only )

static

Definition at line 403 of file comstack.c.

References cs_complete_http(), skip_crlf(), yaz_atoi(), yaz_http_parse_chunks(), and yaz_strncasecmp().

Referenced by cs_complete_auto_x(), and cs_complete_http().

◆ cs_create_host()

COMSTACK cs_create_host	(	const char *	type_and_host,
		int	flags,
		void **	vp )

Creates an endpoint from a host or URI specification.

Parameters

type_and_host	host or URI; see cs_create_host2 for syntax
flags	combination of CS_FLAGS_* bits; zero for nonblocking I/O
vp	required address output pointer; owned by the returned COMSTACK

Returns: new COMSTACK, or NULL on failure

Equivalent to cs_create_host2 with no proxy_host and with the proxy mode output discarded. This creates an endpoint but does not connect it. Pass the address of a void * variable as vp, then use *vp with cs_connect or cs_bind. Do not free *vp; cs_straddr may replace it and cs_close releases it. Do not use *vp on failure. Close the endpoint with cs_close.

See also: cs_create_host2

Definition at line 177 of file comstack.c.

References cs_create_host(), and cs_create_host_proxy().

Referenced by add_listener(), and cs_create_host().

◆ cs_create_host2()

COMSTACK cs_create_host2	(	const char *	vhost,
		int	flags,
		void **	vp,
		const char *	proxy_host,
		int *	proxy_mode )

Creates an endpoint and selects direct or proxy connection handling.

Parameters

vhost	target host or URI specification (required)
flags	combination of CS_FLAGS_* bits; zero for nonblocking I/O
vp	required address output pointer; owned by the returned COMSTACK
proxy_host	proxy host or URI, or NULL for no separate proxy
proxy_mode	required output pointer: 0 for direct/CONNECT, 1 for application-level proxying; only use this value on success

Returns: new COMSTACK, or NULL on failure

Supported case-sensitive target forms are:

host[:port] or tcp:host[:port] for Z39.50 over TCP/IP (default port 210).
ssl:host[:port] for Z39.50 over TLS (default port 210).
http://host[:port][/path] for HTTP (default port 80).
https://host[:port][/path] for HTTPS (default port 443).
unix:path for Z39.50 over a UNIX socket.
unix:path:target to use a UNIX socket with the protocol and arguments from target, for example unix:/tmp/yaz.sock:http://localhost/sru. Use an unencrypted target to retain the UNIX transport.
connect:[user:password]proxy-host:proxy-port,target for an explicit HTTP CONNECT tunnel to a TCP/IP or TLS target.

Bracket IPv6 addresses, for example tcp:[::1]:210. Only HTTP/HTTPS prefixes strip leading slashes; tcp://host is not the TCP syntax. Network address resolution ignores suffixes starting with / or ?; the application interprets paths, queries, and database names. These specifications are not percent-decoded. Direct URI user information and fragments are not interpreted. TLS requires GnuTLS support, and UNIX sockets are unavailable on Windows. UNIX addresses also accept file=path,user=name-or-id,group=name-or-id,umask=mode, with file required and the other keys optional. The octal umask value sets socket permissions directly when binding; it is not a mask to subtract.

A local source address may follow the first space in vhost for TCP/IP or TLS. Put a path slash before the space, for example "tcp:server.example:210/ 192.0.2.10", so resolution excludes the suffix. The source port is forced to zero; for an IPv6 source include a port placeholder, for example "http://[::1]/ [::1]:0".

A separate proxy_host must select TCP/IP, not TLS or UNIX sockets, and must not contain another proxy specification. TLS targets always use CONNECT. A Z39.50 target with an HTTP proxy also uses CONNECT. Other TCP/IP target/proxy combinations use application-level proxying. In that case *proxy_mode is 1 and the caller must supply the proxy protocol messages (for example absolute HTTP request URIs). With CONNECT, proxy_mode is 0 and cs_connect/cs_rcvconnect perform the tunnel handshake. Explicit connect: and unix:path:target forms override proxy_host.

Specify both proxy and target ports explicitly for CONNECT: the target authority is sent without adding a default port, and an omitted proxy port defaults according to the target transport/protocol. Credentials before @ generate a Basic Proxy-Authorization header for CONNECT only; they may also appear in proxy_host when CONNECT is selected.

This function does not establish a connection. On success, pass *vp to cs_connect or cs_bind and eventually release the endpoint with cs_close. Do not free *vp; cs_straddr may replace it. Do not use *vp on failure. With CS_FLAGS_DNS_NO_BLOCK and resolver thread support, resolution errors may be reported later during connection establishment.

See also: cs_create_host, cs_create_host_proxy, cs_parse_host, cs_get_host_args

Definition at line 189 of file comstack.c.

References cs_close, cs_create, cs_create_host2(), cs_parse_host(), cs_straddr, PROTO_HTTP, PROTO_Z3950, ssl_type(), tcpip_type(), xfree, xstrdup, yaz_ssl_create(), and yaz_tcpip_create3().

Referenced by cs_create_host2(), cs_create_host_proxy(), do_connect_host(), and yaz_url_exec().

◆ cs_create_host_proxy()

COMSTACK cs_create_host_proxy	(	const char *	vhost,
		int	flags,
		void **	vp,
		const char *	proxy_host )

Creates an endpoint with an optional proxy.

Parameters

vhost	target host or URI; see cs_create_host2 for syntax
flags	combination of CS_FLAGS_* bits; zero for nonblocking I/O
vp	required address output pointer; owned by the returned COMSTACK
proxy_host	proxy host or URI, or NULL for no separate proxy

Returns: new COMSTACK, or NULL on failure

Equivalent to cs_create_host2 with the proxy mode output discarded. Address ownership and connection handling are as for cs_create_host.

See also: cs_create_host2

Definition at line 182 of file comstack.c.

References cs_create_host2(), and cs_create_host_proxy().

Referenced by cs_create_host(), and cs_create_host_proxy().

◆ cs_errmsg()

const char * cs_errmsg ( int n )

Returns a static message for a COMSTACK error code.

Parameters

n	error code (CSNONE through CSLASTERROR)

Returns: borrowed string; unknown codes use the CSNONE message

Definition at line 39 of file comstack.c.

References cs_errlist, cs_errmsg(), CSLASTERROR, and CSNONE.

Referenced by add_comstack_details(), cs_errmsg(), cs_strerror(), do_read(), ir_read(), and log_comstack_error().

◆ cs_get_error()

int cs_get_error	(	COMSTACK	cs,
		const char **	details )

Returns the last COMSTACK error and optional transport details.

Parameters

cs	endpoint
details	optional output pointer; set to borrowed text or NULL

Returns: error code (CSNONE through CSLASTERROR)

Details are currently available for TCP/IP and TLS. Do not free the text; it can be overwritten by a later error and is released by cs_close.

Definition at line 51 of file comstack.c.

References comstack::cerrno, cs_get_error(), and yaz_tcpip_get_error_details().

Referenced by add_comstack_details(), cs_get_error(), and log_comstack_error().

◆ cs_get_host_args()

void cs_get_host_args	(	const char *	type_and_host,
		const char **	args )

Extracts application arguments from a host or URI specification.

Parameters

type_and_host	host or URI specification (required)
args	required output pointer to borrowed arguments, or an empty string

Returns the portion after the first path slash, skipping a :// separator. For unix:path:args, returns args directly if that part contains no colon; otherwise extracts the target path. For example tcp:localhost:210/books yields books, and http://localhost/sru?version=1.2 yields sru?version=1.2. No decoding is performed. Do not free *args; a nonempty result points into type_and_host and is valid only while that input remains valid.

Definition at line 58 of file comstack.c.

References cs_get_host_args().

Referenced by cs_get_host_args(), yaz_check_location(), and ZOOM_connection_get_databases().

◆ cs_look()

int cs_look ( COMSTACK cs )

Returns the last recorded event (CS_NONE, CS_CONNECT, etc.).

The argument is the endpoint. This function does not poll for new events.

Definition at line 280 of file comstack.c.

References cs_look(), and comstack::event.

Referenced by cs_look(), and ZOOM_connection_do_io().

◆ cs_parse_host()

int cs_parse_host	(	const char *	uri,
		const char **	host,
		CS_TYPE *	t,
		enum oid_proto *	proto,
		char **	connect_host )

Parses transport and protocol prefixes without resolving an address.

Parameters

uri	host or URI specification (required); see cs_create_host2
host	required output pointer into uri after recognized prefixes
t	required transport output pointer
proto	required protocol output pointer: PROTO_Z3950 or PROTO_HTTP
connect_host	required output pointer to an allocated proxy/socket address, or NULL when no such address is specified

Returns: 1 on success, 0 for an unavailable transport

Recognizes connect: and unix: wrappers followed by tcp:, ssl:, http:, or https:. With no recognized protocol prefix, selects Z39.50. The default transport is TCP/IP. This function only parses prefixes; success does not imply that the address is valid or resolvable. On success, free a non-NULL *connect_host with xfree. Do not free *host; it is valid only while uri remains valid. On failure, *connect_host is NULL and the other outputs must not be used.

Definition at line 86 of file comstack.c.

References cs_parse_host(), PROTO_HTTP, PROTO_Z3950, ssl_type(), tcpip_type(), unix_type(), xfree, and xmalloc.

Referenced by cs_create_host2(), and cs_parse_host().

◆ cs_set_head_only()

int cs_set_head_only	(	COMSTACK	cs,
		int	head_only )

Selects HTTP header-only framing for TCP/IP, SSL or UNIX transports.

Parameters

cs	COMSTACK handle
head_only	nonzero to stop at the end of HTTP headers; zero to restore normal message framing

Returns: 0 on success, -1 with CSOUTSTATE for unsupported transports

Definition at line 524 of file comstack.c.

References comstack::cerrno, cs_set_head_only(), CSOUTSTATE, ssl_type(), tcpip_type(), comstack::type, unix_type(), yaz_tcpip_set_head_only(), and yaz_unix_set_head_only().

Referenced by cs_set_head_only(), and yaz_url_exec().

◆ cs_set_max_recv_bytes()

void cs_set_max_recv_bytes	(	COMSTACK	cs,
		int	max_recv_bytes )

Sets the maximum incoming message size.

Parameters

cs	endpoint
max_recv_bytes	receive limit in bytes (default 16777216)

Oversized input is reported as CSBUFSIZE by cs_get.

Definition at line 536 of file comstack.c.

References cs_set_max_recv_bytes(), and comstack::max_recv_bytes.

Referenced by control_association(), and cs_set_max_recv_bytes().

◆ cs_strerror()

const char * cs_strerror ( COMSTACK h )

Returns a static message for the endpoint's last error.

Parameters

h endpoint

Returns: borrowed error string; do not free it

Definition at line 46 of file comstack.c.

References comstack::cerrno, cs_errmsg(), and cs_strerror().

Referenced by cs_strerror().

◆ http_token_char()

int http_token_char ( char c )

static

Definition at line 303 of file comstack.c.

References http_token_char(), yaz_isdigit, yaz_islower, and yaz_isupper.

Referenced by http_token_char(), and yaz_http_parse_chunks().

◆ skip_crlf()

int skip_crlf	(	const char *	buf,
		int	len,
		int *	i )

static

Definition at line 285 of file comstack.c.

References skip_crlf().

Referenced by cs_complete_http(), skip_crlf(), and yaz_http_parse_chunks().

◆ yaz_http_parse_chunks()

int yaz_http_parse_chunks	(	const char *	buf,
		int	len,
		char *	content_buf,
		int *	content_len )

Definition at line 310 of file comstack.c.

References http_token_char(), skip_crlf(), yaz_atoi(), and yaz_http_parse_chunks().

Referenced by cs_complete_http(), decode_headers_content(), and yaz_http_parse_chunks().

Variable Documentation

◆ cs_errlist

const char* cs_errlist[]

static

Initial value:

                             =
{
    "No error or unspecified error",
    "System (lower-layer) error",
    "Operation out of state",
    "No data (operation would block)",
    "New data while half of old buffer is on the line (flow control)",
    "Permission denied",
    "SSL error",
    "Too large incoming buffer",
    "Protocol error in incoming data"
}

Definition at line 26 of file comstack.c.

Referenced by cs_errmsg().

Functions

Variables

Detailed Description

Function Documentation

◆ cs_complete_auto()

◆ cs_complete_auto_head()

◆ cs_complete_auto_x()

◆ cs_complete_http()

◆ cs_create_host()

◆ cs_create_host2()

◆ cs_create_host_proxy()

◆ cs_errmsg()

◆ cs_get_error()

◆ cs_get_host_args()

◆ cs_look()

◆ cs_parse_host()

◆ cs_set_head_only()

◆ cs_set_max_recv_bytes()

◆ cs_strerror()

◆ http_token_char()

◆ skip_crlf()

◆ yaz_http_parse_chunks()

Variable Documentation

◆ cs_errlist