Transport-independent communication endpoints for BER and HTTP. More...

#include <yaz/yconfig.h>
#include <yaz/oid_util.h>
#include <yaz/xmalloc.h>

Data Structures
struct	comstack
	Public endpoint state and transport dispatch table. More...

Macros
#define	CS_ST_UNBND 0
#define	CS_ST_IDLE 1
#define	CS_ST_INCON 2
#define	CS_ST_OUTCON 3
#define	CS_ST_DATAXFER 4
#define	CS_ST_ACCEPT 5
#define	CS_ST_CONNECTING 6
#define	CS_NONE 0
#define	CS_CONNECT 1
#define	CS_DISCON 2
#define	CS_LISTEN 3
#define	CS_DATA 4
#define	CS_CLIENT 0
#define	CS_SERVER 1
#define	cs_put(handle, buf, size)
	Sends a complete message.
#define	cs_get(handle, buf, size)
	Receives a BER or HTTP message.
#define	cs_more(handle)
	Tests whether buffered input can be processed without another read.
#define	cs_connect(handle, address)
	Starts an outgoing connection.
#define	cs_rcvconnect(handle)
	Continues a pending outgoing connection, including TLS or CONNECT.
#define	cs_bind(handle, ad, mo)
	Binds an endpoint to a local address.
#define	cs_listen(handle, ap, al)
	Receives an incoming connection for subsequent cs_accept.
#define	cs_listen_check(handle, ap, al, cf, cd)
	Receives an incoming connection with an optional access check.
#define	cs_accept(handle)
	Creates an endpoint for a connection received by cs_listen.
#define	cs_close(handle)
	Closes the socket and frees the endpoint and its transport state.
#define	cs_create(type, flags, proto)
	Creates an endpoint using a transport constructor.
#define	cs_createbysocket(sock, type, flags, proto)
	Creates an endpoint around an existing socket.
#define	cs_type(handle)
	Returns the endpoint's CS_TYPE transport constructor.
#define	cs_fileno(handle)
	Returns the socket descriptor, or -1 if none has been created.
#define	cs_getstate(handle)
	Legacy accessor intended to return the connection state.
#define	cs_errno(handle)
	Returns the last COMSTACK error code.
#define	cs_getproto(handle)
	Returns the application protocol (enum oid_proto).
#define	cs_addrstr(handle)
	Formats the peer address as text.
#define	cs_straddr(handle, str)
	Parses a transport-specific address and prepares the endpoint.
#define	cs_want_read(handle)
	Tests whether a pending operation needs socket readability.
#define	cs_want_write(handle)
	Tests whether a pending operation needs socket writability.
#define	cs_set_blocking(handle, blocking)
	Updates endpoint flags and socket blocking mode.
#define	CS_WANT_READ 1
#define	CS_WANT_WRITE 2
#define	CSNONE 0
#define	CSYSERR 1
#define	CSOUTSTATE 2
#define	CSNODATA 3
#define	CSWRONGBUF 4
#define	CSDENY 5
#define	CSERRORSSL 6
#define	CSBUFSIZE 7
#define	CSPROTERR 8
#define	CSLASTERROR CSPROTERR
#define	CS_FLAGS_BLOCKING 1
#define	CS_FLAGS_NUMERICHOST 2
#define	CS_FLAGS_DNS_NO_BLOCK 4
#define	CS_FLAGS_CHECK_CERT 8

Typedefs
typedef struct comstack *	COMSTACK
	Communication endpoint; release with cs_close.
typedef COMSTACK(*)	CS_TYPE(int s, int flags, int protocol, void *vp)
	Transport constructor and transport identity.

Functions
int	cs_look (COMSTACK)
	Returns the last recorded event (CS_NONE, CS_CONNECT, etc.).
const char *	cs_strerror (COMSTACK h)
	Returns a static message for the endpoint's last error.
const char *	cs_errmsg (int n)
	Returns a static message for a COMSTACK error code.
int	cs_get_error (COMSTACK cs, const char **details)
	Returns the last COMSTACK error and optional transport details.
COMSTACK	cs_create_host (const char type_and_host, 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.
void	cs_get_host_args (const char type_and_host, const char *args)
	Extracts application arguments from a host or URI specification.
int	cs_complete_auto_head (const char *buf, int len)
	Finds the length of a BER message or HTTP headers.
int	cs_complete_auto (const char *buf, int len)
	Finds the length of a complete BER or HTTP message.
void *	cs_get_ssl (COMSTACK cs)
	Legacy OpenSSL session accessor.
int	cs_set_ssl_ctx (COMSTACK cs, void *ctx)
	Legacy OpenSSL context setter.
int	cs_set_ssl_certificate_file (COMSTACK cs, const char *fname)
	Selects certificate and private key files for a TLS endpoint.
int	cs_get_peer_certificate_x509 (COMSTACK cs, char *buf, int len)
	Gets a human-readable description of the first peer X.509 certificate.
void	cs_set_max_recv_bytes (COMSTACK cs, int max_recv_bytes)
	Sets the maximum incoming message size.
void	cs_print_session_info (COMSTACK cs)
	Prints TLS peer certificate information to standard output.
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.
int	cs_set_head_only (COMSTACK cs, int head_only)
	Selects HTTP header-only framing for TCP/IP, SSL or UNIX transports.

Detailed Description

Transport-independent communication endpoints for BER and HTTP.

Most operations dispatch through transport callbacks. Unless stated otherwise, handles and output pointers must be non-NULL. Macro arguments must not have side effects: a handle expression can be evaluated more than once.

Definition in file comstack.h.

Macro Definition Documentation

◆ cs_accept

#define cs_accept ( handle )

Value:

((*(handle)->f_accept)(handle))

Creates an endpoint for a connection received by cs_listen.

Parameters

handle listener, or an accepted endpoint with a pending TLS handshake

Returns: connected or pending endpoint, or NULL on failure

The original listener remains usable. If the returned endpoint has pending I/O, wait for the indicated directions and call cs_accept on that endpoint again to continue its TLS handshake. A failed TLS handshake releases the pending endpoint. Close a successfully accepted endpoint with cs_close.

Definition at line 217 of file comstack.h.

Referenced by ir_session(), and listener().

◆ cs_addrstr

#define cs_addrstr ( handle )

Value:

((*(handle)->f_addrstr)(handle))

Formats the peer address as text.

Parameters

handle endpoint

Returns: borrowed transport-owned string; do not free it

Subsequent calls may overwrite the result. Network transports may perform reverse DNS unless CS_FLAGS_NUMERICHOST is set.

Definition at line 270 of file comstack.h.

Referenced by assoc_init_reset(), inetd_connection(), listener(), and new_session().

◆ cs_bind

#define cs_bind	(	handle,
		ad,
		mo )

Value:

((*(handle)->f_bind)(handle, ad, mo))

Binds an endpoint to a local address.

Parameters

handle	endpoint
ad	transport address returned by cs_straddr or cs_create_host
mo	CS_SERVER to bind and listen, CS_CLIENT to bind only

Returns: 0 on success, -1 on error

Definition at line 183 of file comstack.h.

Referenced by add_listener().

◆ CS_CLIENT

#define CS_CLIENT 0

Bind a local address without listening.

Definition at line 114 of file comstack.h.

◆ cs_close

#define cs_close ( handle )

Value:

((*(handle)->f_close)(handle))

Closes the socket and frees the endpoint and its transport state.

Parameters

handle endpoint, which must not be used after this call

Does not free application data in user or the caller's cs_get buffer.

Definition at line 223 of file comstack.h.

Referenced by add_listener(), cs_create_host2(), do_connect_host(), ir_read(), ir_session(), listener(), tcpip_accept(), yaz_url_exec(), and ZOOM_connection_destroy().

◆ CS_CONNECT

#define CS_CONNECT 1

Connection establishment event.

Definition at line 93 of file comstack.h.

Referenced by tcpip_connect(), tcpip_rcvconnect(), unix_connect(), and ZOOM_connection_do_io().

◆ cs_connect

#define cs_connect	(		handle,
			address )

Value:

((*(handle)->f_connect)(handle, address))

Starts an outgoing connection.

Parameters

handle	endpoint
address	transport address returned by cs_straddr or cs_create_host

Returns: 0 when connected, 1 when pending, -1 on error

For a pending connection, wait as indicated by cs_want_read/cs_want_write and continue with cs_rcvconnect.

Definition at line 171 of file comstack.h.

Referenced by do_connect_host(), and yaz_url_exec().

◆ cs_create

#define cs_create	(	type,
		flags,
		proto )

Value:

((*type)(-1, flags, proto, 0))

Creates an endpoint using a transport constructor.

Parameters

type	CS_TYPE constructor, such as tcpip_type or unix_type
flags	combination of CS_FLAGS_* bits
proto	application protocol (enum oid_proto)

Returns: new endpoint, or NULL on failure; release with cs_close

Definition at line 230 of file comstack.h.

Referenced by cs_create_host2().

◆ cs_createbysocket

#define cs_createbysocket	(	sock,
		type,
		flags,
		proto )

Value:

((*type)(sock, flags, proto, 0))

Creates an endpoint around an existing socket.

Parameters

sock	socket descriptor; ownership transfers on success
type	CS_TYPE transport constructor
flags	combination of CS_FLAGS_* bits
proto	application protocol (enum oid_proto)

Returns: new endpoint, or NULL on failure; cs_close closes the socket

Definition at line 238 of file comstack.h.

Referenced by inetd_connection().

◆ CS_DATA

#define CS_DATA 4

Data transfer event.

Definition at line 99 of file comstack.h.

Referenced by tcpip_accept(), tcpip_put(), tcpip_rcvconnect(), unix_accept(), unix_put(), unix_rcvconnect(), and ZOOM_connection_do_io().

◆ CS_DISCON

#define CS_DISCON 2

Disconnection event.

Definition at line 95 of file comstack.h.

◆ cs_errno

#define cs_errno ( handle )

Value:

((handle)->cerrno)

Returns the last COMSTACK error code.

Parameters

handle endpoint

See also: cs_get_error, cs_errmsg

Definition at line 258 of file comstack.h.

Referenced by add_listener(), do_read(), and ir_read().

◆ cs_fileno

#define cs_fileno ( handle )

Value:

((handle)->iofile)

Returns the socket descriptor, or -1 if none has been created.

Parameters

handle endpoint

Definition at line 247 of file comstack.h.

Referenced by add_listener(), inetd_connection(), new_session(), and yaz_url_exec().

◆ CS_FLAGS_BLOCKING

#define CS_FLAGS_BLOCKING 1

Use blocking I/O; without this bit operations may remain pending.

Definition at line 560 of file comstack.h.

Referenced by tcpip_connect(), tcpip_get(), tcpip_put(), tcpip_rcvconnect(), tcpip_set_blocking(), unix_accept(), unix_set_blocking(), and unix_type().

◆ CS_FLAGS_CHECK_CERT

#define CS_FLAGS_CHECK_CERT 8

Verify the TLS server certificate and hostname when connecting.

Definition at line 566 of file comstack.h.

Referenced by do_connect_host(), tcpip_rcvconnect(), and yaz_url_exec().

◆ CS_FLAGS_DNS_NO_BLOCK

#define CS_FLAGS_DNS_NO_BLOCK 4

Resolve asynchronously when resolver thread support is available.

Definition at line 564 of file comstack.h.

Referenced by do_connect_host(), and tcpip_straddr().

◆ CS_FLAGS_NUMERICHOST

#define CS_FLAGS_NUMERICHOST 2

Use numeric peer addresses instead of reverse DNS in cs_addrstr.

Definition at line 562 of file comstack.h.

Referenced by add_listener(), and tcpip_addrstr().

◆ cs_get

#define cs_get	(	handle,
		buf,
		size )

Value:

((*(handle)->f_get)(handle, buf, size))

Receives a BER or HTTP message.

Parameters

handle	endpoint
buf	address of a receive buffer pointer; initialize *buf to NULL
size	address of its allocated capacity; initialize *size to zero

Returns: message length (>1), 1 when incomplete, 0 on EOF, -1 on error

The transport allocates, resizes, or replaces *buf and updates *size. Retain both values for subsequent calls and eventually free *buf with xfree. A pending read may need either readability or writability; consult cs_want_read and cs_want_write.

Definition at line 155 of file comstack.h.

Referenced by do_read(), ir_read(), and yaz_url_exec().

◆ cs_getproto

#define cs_getproto ( handle )

Value:

((handle)->protocol)

Returns the application protocol (enum oid_proto).

Parameters

handle endpoint

Definition at line 262 of file comstack.h.

Referenced by create_association().

◆ cs_getstate

#define cs_getstate ( handle )

Value:

((handle)->getstate)

Legacy accessor intended to return the connection state.

Parameters

handle endpoint

Warning: This macro refers to a nonexistent getstate member. Read the public comstack::state member instead.

Definition at line 253 of file comstack.h.

◆ CS_LISTEN

#define CS_LISTEN 3

Listen event.

Definition at line 97 of file comstack.h.

Referenced by tcpip_bind(), and unix_bind().

◆ cs_listen

#define cs_listen	(	handle,
		ap,
		al )

Value:

((*(handle)->f_listen)(handle, ap, al, 0, 0))

Receives an incoming connection for subsequent cs_accept.

Parameters

handle	listening endpoint
ap	optional buffer for the transport's binary peer address
al	address buffer capacity on input, copied length on output; NULL to discard the address (ap may then be NULL)

Returns: 0 when a connection is ready, -1 on error (including CSNODATA when a nonblocking listener has no connection available)

An insufficient address buffer produces an output length of zero.

Definition at line 194 of file comstack.h.

◆ cs_listen_check

#define cs_listen_check	(	handle,
		ap,
		al,
		cf,
		cd )

Value:

((*(handle)->f_listen)(handle, ap, al, cf, cd))

Receives an incoming connection with an optional access check.

Parameters

handle	listening endpoint
ap	optional peer address buffer, as for cs_listen
al	address buffer capacity/result length, as for cs_listen
cf	callback or NULL; nonzero rejects the connection with CSDENY
cd	application data passed to cf

Returns: 0 when a connection is ready, -1 on error

The callback receives cd, a binary peer address, its byte length, and its address family. The check is supported by TCP/IP and TLS on non-Windows systems; the UNIX transport ignores it.

Definition at line 207 of file comstack.h.

Referenced by listener().

◆ cs_more

#define cs_more ( handle )

Value:

((*(handle)->f_more)(handle))

Tests whether buffered input can be processed without another read.

Parameters

handle endpoint

Returns: nonzero if a complete message or framing error is buffered

Does not poll the socket. Call before waiting for socket readability.

Definition at line 162 of file comstack.h.

Referenced by ir_read().

◆ CS_NONE

#define CS_NONE 0

No event recorded.

Definition at line 91 of file comstack.h.

Referenced by tcpip_type(), unix_accept(), unix_type(), and ZOOM_connection_do_io().

◆ cs_put

#define cs_put	(	handle,
		buf,
		size )

Value:

((*(handle)->f_put)(handle, buf, size))

Sends a complete message.

Parameters

handle	endpoint
buf	message bytes; keep valid until the write completes
size	number of bytes to send

Returns: 0 when complete, 1 when pending, -1 on error

Retry pending writes with the same buffer and size after waiting for the directions indicated by cs_want_read and cs_want_write.

Definition at line 143 of file comstack.h.

Referenced by do_write_ex(), ir_session(), and yaz_url_exec().

◆ cs_rcvconnect

#define cs_rcvconnect ( handle )

Value:

((*(handle)->f_rcvconnect)(handle))

Continues a pending outgoing connection, including TLS or CONNECT.

Parameters

handle endpoint

Returns: 0 when connected, 1 when pending, -1 on error

Definition at line 176 of file comstack.h.

Referenced by yaz_url_exec(), and ZOOM_connection_do_io().

◆ CS_SERVER

#define CS_SERVER 1

Bind a local address and listen for connections.

Definition at line 116 of file comstack.h.

Referenced by add_listener(), tcpip_bind(), and unix_bind().

◆ cs_set_blocking

#define cs_set_blocking	(		handle,
			blocking )

Value:

((handle)->f_set_blocking(handle, blocking))

Updates endpoint flags and socket blocking mode.

Parameters

handle	endpoint
blocking	complete set of CS_FLAGS_* bits, despite the parameter name

Returns: 1 on success, 0 on failure

Preserve other desired flag bits when setting or clearing CS_FLAGS_BLOCKING; this operation replaces the stored flags.

Definition at line 299 of file comstack.h.

◆ CS_ST_ACCEPT

#define CS_ST_ACCEPT 5

Accepted connection with a pending TLS handshake.

Definition at line 83 of file comstack.h.

Referenced by tcpip_accept(), and unix_accept().

◆ CS_ST_CONNECTING

#define CS_ST_CONNECTING 6

Outgoing connection establishment in progress.

Definition at line 85 of file comstack.h.

Referenced by tcpip_connect(), tcpip_rcvconnect(), unix_connect(), and unix_rcvconnect().

◆ CS_ST_DATAXFER

#define CS_ST_DATAXFER 4

Established connection ready for data transfer.

Definition at line 81 of file comstack.h.

Referenced by tcpip_accept(), tcpip_rcvconnect(), unix_accept(), and unix_rcvconnect().

◆ CS_ST_IDLE

#define CS_ST_IDLE 1

Bound endpoint ready to listen.

Definition at line 75 of file comstack.h.

Referenced by tcpip_accept(), tcpip_bind(), tcpip_listen(), tcpip_type(), unix_accept(), unix_bind(), unix_listen(), and unix_type().

◆ CS_ST_INCON

#define CS_ST_INCON 2

Incoming connection awaiting cs_accept.

Definition at line 77 of file comstack.h.

Referenced by tcpip_accept(), tcpip_listen(), unix_accept(), and unix_listen().

◆ CS_ST_OUTCON

#define CS_ST_OUTCON 3

Outgoing connection state (legacy).

Definition at line 79 of file comstack.h.

◆ CS_ST_UNBND

#define CS_ST_UNBND 0

Unbound endpoint.

Definition at line 73 of file comstack.h.

Referenced by cont_connect(), tcpip_connect(), tcpip_rcvconnect(), tcpip_straddr(), tcpip_type(), unix_connect(), and unix_type().

◆ cs_straddr

#define cs_straddr	(		handle,
			str )

Value:

((*(handle)->f_straddr)(handle, str))

Parses a transport-specific address and prepares the endpoint.

Parameters

handle	endpoint
str	address without a transport prefix; see cs_create_host2 for the higher-level host/URI interface

Returns: transport-owned address, or NULL on failure

May resolve names and create a socket. Do not free the result; another cs_straddr call may replace it, and cs_close releases it.

Definition at line 280 of file comstack.h.

Referenced by cs_create_host2().

◆ cs_type

#define cs_type ( handle )

Value:

((handle)->type)

Returns the endpoint's CS_TYPE transport constructor.

Parameters

handle endpoint

Definition at line 243 of file comstack.h.

◆ CS_WANT_READ

#define CS_WANT_READ 1

Pending operation needs socket readability.

Definition at line 302 of file comstack.h.

Referenced by do_connect_host(), do_write_ex(), ir_session(), new_session(), tcpip_connect(), tcpip_get(), unix_get(), yaz_url_exec(), and ZOOM_connection_do_io().

◆ cs_want_read

#define cs_want_read ( handle )

Value:

((handle)->io_pending & CS_WANT_READ)

CS_WANT_READ

#define CS_WANT_READ

Definition comstack.h:302

Tests whether a pending operation needs socket readability.

Parameters

handle endpoint

Returns: nonzero if readability is needed

Definition at line 285 of file comstack.h.

◆ CS_WANT_WRITE

#define CS_WANT_WRITE 2

Pending operation needs socket writability.

Definition at line 304 of file comstack.h.

Referenced by do_connect_host(), do_write_ex(), ir_read(), ir_session(), new_session(), tcpip_connect(), tcpip_put(), unix_connect(), unix_put(), yaz_url_exec(), and ZOOM_connection_do_io().

◆ cs_want_write

#define cs_want_write ( handle )

Value:

((handle)->io_pending & CS_WANT_WRITE)

CS_WANT_WRITE

#define CS_WANT_WRITE

Definition comstack.h:304

Tests whether a pending operation needs socket writability.

Parameters

handle endpoint

Returns: nonzero if writability is needed

Definition at line 290 of file comstack.h.

◆ CSBUFSIZE

#define CSBUFSIZE 7

Incoming data exceeds the configured receive limit.

Definition at line 553 of file comstack.h.

Referenced by do_read(), ir_read(), tcpip_get(), and unix_get().

◆ CSDENY

#define CSDENY 5

Incoming connection was rejected by the access callback.

Definition at line 549 of file comstack.h.

Referenced by tcpip_listen(), and tcpip_rcvconnect().

◆ CSERRORSSL

#define CSERRORSSL 6

TLS operation failed; cs_get_error may provide details.

Definition at line 551 of file comstack.h.

Referenced by tcpip_bind(), and tcpip_rcvconnect().

◆ CSLASTERROR

#define CSLASTERROR CSPROTERR

Highest COMSTACK error code; keep equal to the last error.

Definition at line 557 of file comstack.h.

Referenced by cs_errmsg().

◆ CSNODATA

#define CSNODATA 3

No incoming connection is available yet.

Definition at line 545 of file comstack.h.

Referenced by tcpip_listen(), and unix_listen().

◆ CSNONE

#define CSNONE 0

No error, or an unspecified error.

Definition at line 539 of file comstack.h.

Referenced by cs_errmsg().

◆ CSOUTSTATE

#define CSOUTSTATE 2

Operation is invalid for this state or transport.

Definition at line 543 of file comstack.h.

Referenced by cs_set_head_only(), tcpip_accept(), tcpip_connect(), tcpip_listen(), tcpip_rcvconnect(), unix_accept(), unix_connect(), unix_listen(), unix_rcvconnect(), yaz_tcpip_set_head_only(), and yaz_unix_set_head_only().

◆ CSPROTERR

#define CSPROTERR 8

Malformed protocol data.

Definition at line 555 of file comstack.h.

Referenced by do_read(), ir_read(), tcpip_get(), tcpip_rcvconnect(), and unix_get().

◆ CSWRONGBUF

#define CSWRONGBUF 4

A pending write was retried with a different buffer or size.

Definition at line 547 of file comstack.h.

Referenced by tcpip_put(), and unix_put().

◆ CSYSERR

#define CSYSERR 1

System call failed; consult the platform error information.

Definition at line 541 of file comstack.h.

Referenced by add_listener(), cont_connect(), create_net_socket(), tcpip_accept(), tcpip_addrstr(), tcpip_bind(), tcpip_get(), tcpip_listen(), tcpip_put(), unix_accept(), unix_bind(), unix_connect(), unix_get(), unix_listen(), and unix_put().

Typedef Documentation

◆ COMSTACK

typedef struct comstack* COMSTACK

Communication endpoint; release with cs_close.

Definition at line 48 of file comstack.h.

◆ CS_TYPE

typedef COMSTACK(*) CS_TYPE(int s, int flags, int protocol, void *vp)

Transport constructor and transport identity.

Parameters

s	existing socket, or -1 to create a new endpoint
flags	combination of CS_FLAGS_* bits
protocol	application protocol (enum oid_proto)
vp	transport-specific initialization data, or NULL

Returns: new endpoint, or NULL on failure

Definition at line 56 of file comstack.h.

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_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_get_peer_certificate_x509()

int cs_get_peer_certificate_x509	(	COMSTACK	cs,
		char **	buf,
		int *	len )

Gets a human-readable description of the first peer X.509 certificate.

Parameters

cs	endpoint with an established TLS session
buf	required output pointer to allocated, NUL-terminated text
len	required output pointer to text length, excluding the terminator

Returns: 1 on success, 0 if unavailable; outputs are unchanged on failure

Requires GnuTLS certificate printing support. Free *buf with xfree after success. The result is descriptive text, not a PEM-encoded certificate.

Definition at line 1733 of file tcpip.c.

References tcpip_state::buf, comstack::cprivate, cs_get_peer_certificate_x509(), ssl_type(), comstack::type, and xstrdup.

Referenced by cs_get_peer_certificate_x509(), and get_cert().

◆ cs_get_ssl()

void * cs_get_ssl ( COMSTACK cs )

Legacy OpenSSL session accessor.

Parameters

cs endpoint

Returns: NULL

Deprecated: OpenSSL support has been removed; this function is a no-op.

Definition at line 1680 of file tcpip.c.

References cs_get_ssl().

Referenced by cs_get_ssl().

◆ 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_print_session_info()

void cs_print_session_info ( COMSTACK cs )

Prints TLS peer certificate information to standard output.

Parameters

cs endpoint

Does nothing for other transports or when no TLS session is available.

Definition at line 1638 of file tcpip.c.

References comstack::cprivate, cs_print_session_info(), ssl_type(), and comstack::type.

Referenced by cs_print_session_info().

◆ 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_set_ssl_certificate_file()

int cs_set_ssl_certificate_file	(	COMSTACK	cs,
		const char *	fname )

Selects certificate and private key files for a TLS endpoint.

Parameters

cs	endpoint, or NULL
fname	filename containing both certificate and key, or "certificate-file,key-file"; NULL or empty disables the default file

Returns: 1 if filenames were stored, 0 for an unsupported endpoint

Call before binding or connecting. Filenames are copied; success does not mean the files have been loaded or validated. This overrides the default server certificate filename yaz.pem.

Definition at line 1698 of file tcpip.c.

References comstack::cprivate, cs_set_ssl_certificate_file(), ssl_type(), and comstack::type.

Referenced by add_listener(), cs_set_ssl_certificate_file(), do_connect_host(), and yaz_url_exec().

◆ cs_set_ssl_ctx()

int cs_set_ssl_ctx	(	COMSTACK	cs,
		void *	ctx )

Legacy OpenSSL context setter.

Parameters

cs	endpoint, or NULL
ctx	ignored legacy context pointer

Returns: 1 for a TLS endpoint with GnuTLS support, otherwise 0

Deprecated: OpenSSL support has been removed; no context is installed.

Definition at line 1686 of file tcpip.c.

References cs_set_ssl_ctx(), ssl_type(), and comstack::type.

Referenced by cs_set_ssl_ctx().

◆ 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().

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ cs_accept

◆ cs_addrstr

◆ cs_bind

◆ CS_CLIENT

◆ cs_close

◆ CS_CONNECT

◆ cs_connect

◆ cs_create

◆ cs_createbysocket

◆ CS_DATA

◆ CS_DISCON

◆ cs_errno

◆ cs_fileno

◆ CS_FLAGS_BLOCKING

◆ CS_FLAGS_CHECK_CERT

◆ CS_FLAGS_DNS_NO_BLOCK

◆ CS_FLAGS_NUMERICHOST

◆ cs_get

◆ cs_getproto

◆ cs_getstate

◆ CS_LISTEN

◆ cs_listen

◆ cs_listen_check

◆ cs_more

◆ CS_NONE

◆ cs_put

◆ cs_rcvconnect

◆ CS_SERVER

◆ cs_set_blocking

◆ CS_ST_ACCEPT

◆ CS_ST_CONNECTING

◆ CS_ST_DATAXFER

◆ CS_ST_IDLE

◆ CS_ST_INCON

◆ CS_ST_OUTCON

◆ CS_ST_UNBND

◆ cs_straddr

◆ cs_type

◆ CS_WANT_READ

◆ cs_want_read

◆ CS_WANT_WRITE

◆ cs_want_write

◆ CSBUFSIZE

◆ CSDENY

◆ CSERRORSSL

◆ CSLASTERROR

◆ CSNODATA

◆ CSNONE

◆ CSOUTSTATE

◆ CSPROTERR

◆ CSWRONGBUF

◆ CSYSERR

Typedef Documentation

◆ COMSTACK

◆ CS_TYPE

Function Documentation

◆ cs_complete_auto()

◆ cs_complete_auto_head()

◆ cs_create_host()

◆ cs_create_host2()

◆ cs_create_host_proxy()

◆ cs_errmsg()

◆ cs_get_error()

◆ cs_get_host_args()

◆ cs_get_peer_certificate_x509()

◆ cs_get_ssl()

◆ cs_look()

◆ cs_parse_host()

◆ cs_print_session_info()

◆ cs_set_head_only()

◆ cs_set_max_recv_bytes()

◆ cs_set_ssl_certificate_file()

◆ cs_set_ssl_ctx()

◆ cs_strerror()