xcm_attr.h File Reference

This file contains the XCM attribute access API. See Socket Attributes for an overview. More...

#include <stdbool.h>
#include <xcm.h>
#include <xcm_attr_types.h>

Go to the source code of this file.

Typedefs
typedef void(*	xcm_attr_cb) (const char *attr_name, enum xcm_attr_type type, void *value, size_t value_len, void *cb_data)

Functions
int	xcm_attr_set (struct xcm_socket *socket, const char *name, enum xcm_attr_type type, const void *value, size_t len)
int	xcm_attr_set_bool (struct xcm_socket *socket, const char *name, bool value)
int	xcm_attr_set_int64 (struct xcm_socket *socket, const char *name, int64_t value)
int	xcm_attr_set_str (struct xcm_socket *socket, const char *name, const char *value)
int	xcm_attr_get (struct xcm_socket *socket, const char *name, enum xcm_attr_type *type, void *value, size_t capacity)
int	xcm_attr_get_bool (struct xcm_socket *socket, const char *name, bool *value)
int	xcm_attr_get_int64 (struct xcm_socket *socket, const char *name, int64_t *value)
int	xcm_attr_get_str (struct xcm_socket *socket, const char *name, char *value, size_t capacity)
void	xcm_attr_get_all (struct xcm_socket *socket, xcm_attr_cb cb, void *cb_data)

Detailed Description

This file contains the XCM attribute access API. See Socket Attributes for an overview.

Typedef Documentation

xcm_attr_cb

typedef void(* xcm_attr_cb) (const char *attr_name, enum xcm_attr_type type, void *value, size_t value_len, void *cb_data)

The signature of the user-supplied callback used in xcm_attr_get_all().

Function Documentation

xcm_attr_set()

int xcm_attr_set	(	struct xcm_socket *	socket,
		const char *	name,
		enum xcm_attr_type	type,
		const void *	value,
		size_t	len
	)

Sets the value of a socket attribute.

Only attributes marked as writable may be set. For a list of available attributes for different socket and transport types, see Generic Attributes, TCP Socket Attributes and TLS Socket Attributes.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	type	The value type of the new value.
[in]	value	The new value.
[in]	len	The length of the value.

Returns

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

errno	Description
ENOENT	The attribute does not exist.
EACCES	The attribute exists, but is read-only.
EINVAL	The attribute name is too long, the attribute value type, value or value length is not valid for the specified attribute.

xcm_attr_set_bool()

int xcm_attr_set_bool	(	struct xcm_socket *	socket,
		const char *	name,
		bool	value
	)

Sets the value of a boolean socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	value	The new boolean value.

Returns

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

See xcm_attr_set() for possible errno values.

xcm_attr_set_int64()

int xcm_attr_set_int64	(	struct xcm_socket *	socket,
		const char *	name,
		int64_t	value
	)

Sets the value of an integer socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	value	The new integer value.

Returns

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

See xcm_attr_set() for possible errno values.

xcm_attr_set_str()

int xcm_attr_set_str	(	struct xcm_socket *	socket,
		const char *	name,
		const char *	value
	)

Sets the value of a string socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[in]	value	The new string value.

Returns

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

See xcm_attr_set() for possible errno values.

xcm_attr_get()

int xcm_attr_get	(	struct xcm_socket *	socket,
		const char *	name,
		enum xcm_attr_type *	type,
		void *	value,
		size_t	capacity
	)

Retrieves the value of a socket attribute.

For a list of available attributes for different socket and transport types, see Generic Attributes, TCP Socket Attributes and TLS Socket Attributes.

For a description of the C types and buffer capacity requirements of the attribute types, see xcm_attr_types.h.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	type	A pointer to a location where the type of the attribute will be stored. May be left to NULL, in case the type is known a priori.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.
[in]	capacity	The length of the buffer (in bytes).

Returns

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

errno	Description
ENOENT	The attribute does not exist.
EACCES	The attribute exists, but is write-only.
EOVERFLOW	The user-supplied buffer was too small to fit the value.

xcm_attr_get_bool()

int xcm_attr_get_bool	(	struct xcm_socket *	socket,
		const char *	name,
		bool *	value
	)

Retrieves the value of a boolean socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.

Returns

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

errno	Description
ENOENT	The attribute does not exist, or is not boolean.

See xcm_attr_get() for other possible errno values.

xcm_attr_get_int64()

int xcm_attr_get_int64	(	struct xcm_socket *	socket,
		const char *	name,
		int64_t *	value
	)

Retrieves the value of an integer socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	value	A user-supplied buffer where the value of the attribute will be stored.

Returns

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

errno	Description
ENOENT	The attribute does not exist, or is not an integer.

See xcm_attr_get() for other possible errno values.

xcm_attr_get_str()

int xcm_attr_get_str	(	struct xcm_socket *	socket,
		const char *	name,
		char *	value,
		size_t	capacity
	)

Retrieves the value of a string socket attribute.

Parameters

[in]	socket	The connection or server socket.
[in]	name	The name of the attribute.
[out]	value	A user-supplied buffer where the string value of the attribute will be stored.
[in]	capacity	The length of the buffer (in bytes).

Returns

Returns the length of the string value (including the terminating NUL character) on success, or -1 if an error occured (in which case errno is set).

errno	Description
ENOENT	The attribute does not exist, or is not a string.

See xcm_attr_get() for other possible errno values.

xcm_attr_get_all()

void xcm_attr_get_all	(	struct xcm_socket *	socket,
		xcm_attr_cb	cb,
		void *	cb_data
	)

Retrieves all XCM socket attributes.

This function retrieves all available attribute names, types and their current values on a particular connection or server socket.

The memory locations refered to by the attr_name and attr_value pointers is only guaranteed to be valid for the execution of the callback. If needed later, they need to be copied.

Parameters

[in]	socket	The connection or server socket.
[in]	cb	The function to be called for every attribute on the socket.
[in]	cb_data	An opaque (for XCM) pointer returned back to the application in the callback. cb_data may be NULL.