xcm_addr.h File Reference

API for parsing and building XCM addresses. More...

#include <errno.h>
#include <inttypes.h>
#include <netinet/in.h>
#include <stdbool.h>
#include <sys/socket.h>
#include <sys/types.h>
#include <xcm_addr_compat.h>

Go to the source code of this file.

Data Structures
struct	xcm_addr_ip
struct	xcm_addr_host

Macros
#define	XCM_UTLS_PROTO   "utls"
#define	XCM_TLS_PROTO   "tls"
#define	XCM_TCP_PROTO   "tcp"
#define	XCM_SCTP_PROTO   "sctp"
#define	XCM_UX_PROTO   "ux"
#define	XCM_UXF_PROTO   "uxf"
#define	XCM_BTLS_PROTO   "btls"
#define	XCM_BTCP_PROTO   "btcp"

Enumerations
enum	xcm_addr_type { xcm_addr_type_name , xcm_addr_type_ip }

Functions
bool	xcm_addr_is_valid (const char *xcm_addr_s)
bool	xcm_addr_is_supported (const char *xcm_addr_s)
int	xcm_addr_parse_proto (const char *addr_s, char *proto, size_t capacity)
int	xcm_addr_parse_utls (const char *utls_addr_s, struct xcm_addr_host *host, uint16_t *port)
int	xcm_addr_parse_tls (const char *tls_addr_s, struct xcm_addr_host *host, uint16_t *port)
int	xcm_addr_parse_tcp (const char *tcp_addr_s, struct xcm_addr_host *host, uint16_t *port)
int	xcm_addr_parse_sctp (const char *sctp_addr_s, struct xcm_addr_host *host, uint16_t *port)
int	xcm_addr_parse_ux (const char *ux_addr_s, char *ux_path, size_t capacity)
int	xcm_addr_parse_uxf (const char *uxf_addr_s, char *uxf_path, size_t capacity)
int	xcm_addr_parse_btcp (const char *btcp_addr_s, struct xcm_addr_host *host, uint16_t *port)
int	xcm_addr_parse_btls (const char *btls_addr_s, struct xcm_addr_host *host, uint16_t *port)
int	xcm_addr_make_utls (const struct xcm_addr_host *host, unsigned short port, char *utls_addr_s, size_t capacity)
int	xcm_addr_make_tls (const struct xcm_addr_host *host, unsigned short port, char *tls_addr_s, size_t capacity)
int	xcm_addr_make_tcp (const struct xcm_addr_host *host, unsigned short port, char *tcp_addr_s, size_t capacity)
int	xcm_addr_make_sctp (const struct xcm_addr_host *host, unsigned short port, char *sctp_addr_s, size_t capacity)
int	xcm_addr_make_ux (const char *ux_name, char *ux_addr_s, size_t capacity)
int	xcm_addr_make_uxf (const char *uxf_name, char *uxf_addr_s, size_t capacity)
int	xcm_addr_make_btcp (const struct xcm_addr_host *host, unsigned short port, char *btcp_addr_s, size_t capacity)
int	xcm_addr_make_btls (const struct xcm_addr_host *host, unsigned short port, char *btls_addr_s, size_t capacity)

Detailed Description

API for parsing and building XCM addresses.

Macro Definition Documentation

XCM_UTLS_PROTO

#define XCM_UTLS_PROTO   "utls"

Protocol string for the combined TLS+UX transport.

XCM_TLS_PROTO

#define XCM_TLS_PROTO   "tls"

Protocol string for the Transport Layer Security (TLS) message-oriented transport.

XCM_TCP_PROTO

#define XCM_TCP_PROTO   "tcp"

Protocol string for the TCP messaging transport.

XCM_SCTP_PROTO

#define XCM_SCTP_PROTO   "sctp"

Protocol string for the SCTP messaging transport.

XCM_UX_PROTO

#define XCM_UX_PROTO   "ux"

Protocol string for the UNIX Domain socket (AF_UNIX SEQPACKET) messaging transport (using the abstract namespace).

XCM_UXF_PROTO

#define XCM_UXF_PROTO   "uxf"

Protocol string for the UNIX Domain socket (AF_UNIX SEQPACKET) messaging transport (using file system-based naming).

XCM_BTLS_PROTO

#define XCM_BTLS_PROTO   "btls"

Protocol string for the Transport Layer Security (TLS) byte-stream transport.

XCM_BTCP_PROTO

#define XCM_BTCP_PROTO   "btcp"

Protocol string for the TCP byte-stream transport.

Function Documentation

xcm_addr_is_valid()

bool xcm_addr_is_valid

(

const char *

xcm_addr_s

)

Checks if an XCM address is valid.

Checks if a string is a syntactically correct XCM address for a known (but not necessarily supported) XCM transport.

The correctness of the complete address is verified, including the transport-specific part (e.g., port number for TCP/IP-based transports).

Parameters

[in]

xcm_addr_s

The XCM address string.

Returns

Returns true if valid, false if not.

xcm_addr_is_supported()

bool xcm_addr_is_supported

(

const char *

xcm_addr_s

)

Checks if an XCM address is a valid and supported.

Checks if a string is a valid address for an XCM transport supported by this library instance.

Parameters

[in]

xcm_addr_s

The XCM address string.

Returns

Returns true if valid and supported, false if not.

xcm_addr_parse_proto()

int xcm_addr_parse_proto	(	const char *	addr_s,
		char *	proto,
		size_t	capacity
	)

Parses the protocol part of an XCM address.

Parameters

[in]	addr_s	The XCM address string.
[out]	proto	The buffer where to store the protocol part of the address.
[in]	capacity	The buffer length in bytes.

Returns

Returns 0 on success, or -1 on error (in which case errno is set).

errno	Description
EINVAL	Malformed address.
ENAMETOOLONG	The user-supplied buffer is too small to fit the protocol.

xcm_addr_parse_utls()

int xcm_addr_parse_utls	(	const char *	utls_addr_s,
		struct xcm_addr_host *	host,
		uint16_t *	port
	)

Parses a UTLS XCM address.

Parameters

[in]	utls_addr_s	The string to sparse.
[out]	host	The host (either DNS domain name or IPv4/v6 adress).
[out]	port	The TLS port in network byte order.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
EINVAL	Malformed address.

xcm_addr_parse_tls()

int xcm_addr_parse_tls	(	const char *	tls_addr_s,
		struct xcm_addr_host *	host,
		uint16_t *	port
	)

Parses a TLS XCM address.

Parameters

[in]	tls_addr_s	The string to sparse.
[out]	host	The host (either DNS domain name or IPv4/v6 adress).
[out]	port	The TLS port in network byte order.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
EINVAL	Malformed address.

xcm_addr_parse_tcp()

int xcm_addr_parse_tcp	(	const char *	tcp_addr_s,
		struct xcm_addr_host *	host,
		uint16_t *	port
	)

Parses a TCP XCM address.

Parameters

[in]	tcp_addr_s	The string to sparse.
[out]	host	The host (either DNS domain name or IPv4/v6 adress).
[out]	port	The TCP port in network byte order.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
EINVAL	Malformed address.

xcm_addr_parse_sctp()

int xcm_addr_parse_sctp	(	const char *	sctp_addr_s,
		struct xcm_addr_host *	host,
		uint16_t *	port
	)

Parse a SCTP XCM address.

Parameters

[in]	sctp_addr_s	The string to sparse.
[out]	host	The host (either DNS domain name or IPv4/v6 adress).
[out]	port	The SCTP port in network byte order.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
EINVAL	Malformed address.

xcm_addr_parse_ux()

int xcm_addr_parse_ux	(	const char *	ux_addr_s,
		char *	ux_path,
		size_t	capacity
	)

Parses an UX (UNIX Domain Socket) XCM address.

Parameters

[in]	ux_addr_s	The string to sparse.
[out]	ux_path	The UNIX (NUL-terminated) abstract name portion of the UX address.
[in]	capacity	The length of the user-supplied path buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
EINVAL	Malformed address.

xcm_addr_parse_uxf()

int xcm_addr_parse_uxf	(	const char *	uxf_addr_s,
		char *	uxf_path,
		size_t	capacity
	)

Parses an UXF (UNIX Domain Socket) XCM address.

Parameters

[in]	uxf_addr_s	The string to sparse.
[out]	uxf_path	The UNIX (NUL-terminated) path name portion of the UXF address.
[in]	capacity	The length of the user-supplied path buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
EINVAL	Malformed address.

xcm_addr_parse_btcp()

int xcm_addr_parse_btcp	(	const char *	btcp_addr_s,
		struct xcm_addr_host *	host,
		uint16_t *	port
	)

Parses a BTCP XCM address.

Parameters

[in]	btcp_addr_s	The string to sparse.
[out]	host	The host (either DNS domain name or IPv4/v6 adress).
[out]	port	The TCP port in network byte order.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
EINVAL	Malformed address.

xcm_addr_parse_btls()

int xcm_addr_parse_btls	(	const char *	btls_addr_s,
		struct xcm_addr_host *	host,
		uint16_t *	port
	)

Parses a BTLS XCM address.

Parameters

[in]	btls_addr_s	The string to sparse.
[out]	host	The host (either DNS domain name or IPv4/v6 adress).
[out]	port	The TCP port in network byte order.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
EINVAL	Malformed address.

xcm_addr_make_utls()

int xcm_addr_make_utls	(	const struct xcm_addr_host *	host,
		unsigned short	port,
		char *	utls_addr_s,
		size_t	capacity
	)

Builds a UTLS XCM address string from the supplied host and port.

Parameters

[in]	host	The host (either DNS domain name or IPv4/v6 adress).
[in]	port	The port in network byte order.
[out]	utls_addr_s	The user-supplied buffer where to store the result.
[in]	capacity	The length of the buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENAMETOOLONG	The user-supplied buffer is too small to fit the address.
EINVAL	Invalid IP address.

xcm_addr_make_tls()

int xcm_addr_make_tls	(	const struct xcm_addr_host *	host,
		unsigned short	port,
		char *	tls_addr_s,
		size_t	capacity
	)

Builds a TLS XCM address string from the supplied host and port.

Parameters

[in]	host	The host (either DNS domain name or IPv4/v6 adress).
[in]	port	The port in network byte order.
[out]	tls_addr_s	The user-supplied buffer where to store the result.
[in]	capacity	The length of the buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENAMETOOLONG	The user-supplied buffer is too small to fit the address.
EINVAL	Invalid IP address.

xcm_addr_make_tcp()

int xcm_addr_make_tcp	(	const struct xcm_addr_host *	host,
		unsigned short	port,
		char *	tcp_addr_s,
		size_t	capacity
	)

Builds a TCP XCM address string from the supplied host and port.

Parameters

[in]	host	The host (either DNS domain name or IPv4/v6 adress).
[in]	port	The port in network byte order.
[out]	tcp_addr_s	The user-supplied buffer where to store the result.
[in]	capacity	The length of the buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENAMETOOLONG	The user-supplied buffer is too small to fit the address.
EINVAL	Invalid IP address.

xcm_addr_make_sctp()

int xcm_addr_make_sctp	(	const struct xcm_addr_host *	host,
		unsigned short	port,
		char *	sctp_addr_s,
		size_t	capacity
	)

Builds a SCTP XCM address string from the supplied host and port.

Parameters

[in]	host	The host (either DNS domain name or IPv4/v6 adress).
[in]	port	The port in network byte order.
[out]	sctp_addr_s	The user-supplied buffer where to store the result.
[in]	capacity	The length of the buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENAMETOOLONG	The user-supplied buffer is too small to fit the address.
EINVAL	Invalid IP address.

xcm_addr_make_ux()

int xcm_addr_make_ux	(	const char *	ux_name,
		char *	ux_addr_s,
		size_t	capacity
	)

Builds an UX XCM address string from the supplied UNIX Domain Socket name.

Parameters

[in]	ux_name	The UNIX Domain Socket name.
[out]	ux_addr_s	The user-supplied buffer where to store the result.
[in]	capacity	The length of the buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENAMETOOLONG	The user-supplied buffer is too small to fit the address.
EINVAL	Invalid format of or too long UNIX Domain Socket address.

xcm_addr_make_uxf()

int xcm_addr_make_uxf	(	const char *	uxf_name,
		char *	uxf_addr_s,
		size_t	capacity
	)

Builds an UXF XCM address string from the supplied file system path.

Parameters

[in]	uxf_name	The UNIX Domain path.
[out]	uxf_addr_s	The user-supplied buffer where to store the result.
[in]	capacity	The length of the buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENAMETOOLONG	The user-supplied buffer is too small to fit the address.
EINVAL	Invalid format of or too long UNIX Domain Socket address.

xcm_addr_make_btcp()

int xcm_addr_make_btcp	(	const struct xcm_addr_host *	host,
		unsigned short	port,
		char *	btcp_addr_s,
		size_t	capacity
	)

Builds a BTCP XCM address string from the supplied host and port.

Parameters

[in]	host	The host (either DNS domain name or IPv4/v6 adress).
[in]	port	The port in network byte order.
[out]	btcp_addr_s	The user-supplied buffer where to store the result.
[in]	capacity	The length of the buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENAMETOOLONG	The user-supplied buffer is too small to fit the address.
EINVAL	Invalid IP address.

xcm_addr_make_btls()

int xcm_addr_make_btls	(	const struct xcm_addr_host *	host,
		unsigned short	port,
		char *	btls_addr_s,
		size_t	capacity
	)

Builds a BTLS XCM address string from the supplied host and port.

Parameters

[in]	host	The host (either DNS domain name or IPv4/v6 adress).
[in]	port	The port in network byte order.
[out]	btls_addr_s	The user-supplied buffer where to store the result.
[in]	capacity	The length of the buffer.

Returns

Returns 0 on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENAMETOOLONG	The user-supplied buffer is too small to fit the address.
EINVAL	Invalid IP address.