control_if.h File Reference

#include <osmocom/core/write_queue.h>
#include <osmocom/ctrl/control_cmd.h>

Go to the source code of this file.

Data Structures
struct	ctrl_handle

Typedefs
typedef int(*	ctrl_cmd_lookup) (void *data, vector vline, int *node_type, void **node_data, int *i)
typedef void(*	ctrl_cmd_reply_cb) (struct ctrl_handle *ctrl, struct ctrl_cmd *cmd, void *data)

Functions
int	ctrl_parse_get_num (vector vline, int i, long *num)
	Parse ascii-encoded decimal number at vline[i]. More...
int	ctrl_cmd_send (struct osmo_wqueue *queue, struct ctrl_cmd *cmd) OSMO_DEPRECATED("Use ctrl_cmd_send2() instead.")
	Encode a CTRL command and append it to the given ctrl_connection. More...
int	ctrl_cmd_send2 (struct ctrl_connection *ccon, struct ctrl_cmd *cmd)
	Encode a CTRL command and append it to the given ctrl_connection. More...
int	ctrl_cmd_send_trap (struct ctrl_handle *ctrl, const char *name, char *value)
	Send TRAP over given Control Interface. More...
struct ctrl_handle *	ctrl_handle_alloc (void *ctx, void *data, ctrl_cmd_lookup lookup)
	Allocate a CTRL interface handle. More...
struct ctrl_handle *	ctrl_handle_alloc2 (void *ctx, void *data, ctrl_cmd_lookup lookup, unsigned int node_count)
	Allocate a CTRL interface handle. More...
struct ctrl_handle *	ctrl_interface_setup (void *data, uint16_t port, ctrl_cmd_lookup lookup)
struct ctrl_handle *	ctrl_interface_setup2 (void *data, uint16_t default_port, ctrl_cmd_lookup lookup, unsigned int node_count)
	Initializes CTRL interface using the configured bind addr/port. More...
struct ctrl_handle *	ctrl_interface_setup_dynip (void *data, const char *bind_addr, uint16_t port, ctrl_cmd_lookup lookup) OSMO_DEPRECATED_OUTSIDE_LIBOSMOCORE
	Setup CTRL interface on a given address. More...
struct ctrl_handle *	ctrl_interface_setup_dynip2 (void *data, const char *bind_addr, uint16_t port, ctrl_cmd_lookup lookup, unsigned int node_count) OSMO_DEPRECATED_OUTSIDE_LIBOSMOCORE
	Setup CTRL interface on a given address. More...
struct ctrl_connection *	osmo_ctrl_conn_alloc (void *ctx, void *data)
	Allocate CTRL connection. More...
int	ctrl_cmd_handle (struct ctrl_handle *ctrl, struct ctrl_cmd *cmd, void *data)
struct ctrl_cmd *	ctrl_cmd_exec_from_string (struct ctrl_handle *ch, const char *cmdstr)
	Helper for "local execution" of a CTRL command from a string The function will parse + execute the given control command string and return a corresponding ctrl_cmd. More...
int	ctrl_lookup_register (ctrl_cmd_lookup lookup)
	Install a lookup helper function for control nodes This function is used by e.g. More...
int	ctrl_handle_msg (struct ctrl_handle *ctrl, struct ctrl_connection *ccon, struct msgb *msg)
	Handle a received CTRL command contained in a Message buffers. More...

Typedef Documentation

ctrl_cmd_lookup

typedef int(* ctrl_cmd_lookup) (void *data, vector vline, int *node_type, void **node_data, int *i)

ctrl_cmd_reply_cb

typedef void(* ctrl_cmd_reply_cb) (struct ctrl_handle *ctrl, struct ctrl_cmd *cmd, void *data)

Function Documentation

ctrl_cmd_exec_from_string()

struct ctrl_cmd * ctrl_cmd_exec_from_string	(	struct ctrl_handle *	ch,
		const char *	cmdstr
	)

Helper for "local execution" of a CTRL command from a string The function will parse + execute the given control command string and return a corresponding ctrl_cmd.

Caller is responsible to talloc_free() the return value.

Parameters

[in]

Control

Interface Command String

Returns

parsed command, including reply; NULL on error

References ctrl_cmd_handle(), CTRL_CMD_HANDLED, ctrl_cmd_parse2(), CTRL_TYPE_ERROR, msg, msgb_alloc(), msgb_free(), msgb_put(), msgb_tailroom(), osmo_strlcpy(), and ctrl_cmd::type.

ctrl_cmd_handle()

int ctrl_cmd_handle	(	struct ctrl_handle *	ctrl,
		struct ctrl_cmd *	cmd,
		void *	data
	)

References ctrl_cmd_def::cmd, cmd_free_strvec(), cmd_make_strvec(), cmdvec, CTRL_CMD_ERROR, ctrl_cmd_exec(), CTRL_CMD_HANDLED, CTRL_CMD_REPLY, CTRL_NODE_ROOT, ctrl_node_vec, CTRL_TYPE_ERROR, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET_REPLY, ctrl_type_vals, data, DLCTRL, get_value_string(), ctrl_cmd::id, list, llist_for_each_entry, LOGL_DEBUG, LOGL_ERROR, LOGL_NOTICE, LOGP, ctrl_handle::lookup, lookup_helper::lookup, node, ctrl_cmd::node, ctrl_cmd::reply, ctrl_handle::reply_cb, ctrl_cmd::type, ctrl_cmd::variable, vector_active, vector_free(), vector_init(), vector_lookup(), vector_set(), and vector_slot.

Referenced by ctrl_cmd_exec_from_string(), and ctrl_handle_msg().

ctrl_cmd_send()

int ctrl_cmd_send	(	struct osmo_wqueue *	queue,
		struct ctrl_cmd *	cmd
	)

Encode a CTRL command and append it to the given ctrl_connection.

Parameters

[in,out]	queue	write queue to which encoded cmd shall be appended
[in]	cmd	decoded command representation

Returns

0 in case of success; negative on error

ctrl_cmd_send2()

int ctrl_cmd_send2	(	struct ctrl_connection *	ccon,
		struct ctrl_cmd *	cmd
	)

Encode a CTRL command and append it to the given ctrl_connection.

Parameters

[in,out]	queue	write queue to which encoded cmd shall be appended
[in]	cmd	decoded command representation

Returns

0 in case of success; negative on error

References ctrl_cmd_make(), DLCTRL, ipa_prepend_header(), ipa_prepend_header_ext(), IPAC_PROTO_EXT_CTRL, IPAC_PROTO_OSMO, LOGL_ERROR, LOGP, msg, msgb_free(), osmo_wqueue_enqueue(), and ctrl_connection::write_queue.

Referenced by ctrl_cmd_def_send(), ctrl_cmd_send(), ctrl_cmd_send_to_all(), and ctrl_handle_msg().

ctrl_cmd_send_trap()

int ctrl_cmd_send_trap	(	struct ctrl_handle *	ctrl,
		const char *	name,
		char *	value
	)

Send TRAP over given Control Interface.

Parameters

[in]	ctrl	Control Interface over which TRAP will be sent
[in]	name	Name of the TRAP variable
[in]	value	Value of the TRAP variable

Returns

Negative value on error, result of ctrl_cmd_send_to_all() otherwise

References ctrl_cmd_create(), ctrl_cmd_send_to_all(), CTRL_CMD_TRAP_ID, CTRL_TYPE_TRAP, ctrl_cmd::id, name, ctrl_cmd::reply, ctrl_cmd::value, and ctrl_cmd::variable.

ctrl_handle_alloc()

struct ctrl_handle * ctrl_handle_alloc	(	void *	ctx,
		void *	data,
		ctrl_cmd_lookup	lookup
	)

Allocate a CTRL interface handle.

Parameters

[in]	ctx	Talloc allocation context to be used
[in]	data	Pointer which will be made available to each set_..() get_..() verify_..() control command function
[in]	lookup	Lookup function pointer, can be NULL

Returns

ctrl_handle pointer or NULL in case of errors

References ctrl_handle_alloc2(), data, and ctrl_handle::lookup.

ctrl_handle_alloc2()

struct ctrl_handle * ctrl_handle_alloc2	(	void *	ctx,
		void *	data,
		ctrl_cmd_lookup	lookup,
		unsigned int	node_count
	)

Allocate a CTRL interface handle.

Parameters

[in]	ctx	Talloc allocation context to be used
[in]	data	Pointer which will be made available to each set_..() get_..() verify_..() control command function
[in]	lookup	Lookup function pointer, can be NULL
[in]	node_count	Number of CTRL nodes to allocate, 0 for default.

Returns

ctrl_handle pointer or NULL in case of errors

Please see ctrl_interface_setup_dynip2() for a detailed description of node_count semantics.

References ctrl_handle::ccon_list, ctrl_init(), data, ctrl_handle::data, INIT_LLIST_HEAD, and ctrl_handle::lookup.

Referenced by ctrl_handle_alloc(), and ctrl_interface_setup_dynip2().

ctrl_handle_msg()

int ctrl_handle_msg	(	struct ctrl_handle *	ctrl,
		struct ctrl_connection *	ccon,
		struct msgb *	msg
	)

Handle a received CTRL command contained in a Message buffers.

Parameters

[in]	ctrl	CTRL interface handle
[in]	ccon	CTRL connection through which the command was received
[in]	msg	message buffer containing CTRL command including IPA+IPA_EXT headers

Returns

0 on success; negative on error

References osmo_wqueue::bfd, ctrl_cmd::ccon, ctrl_cmd_handle(), CTRL_CMD_HANDLED, ctrl_cmd_parse3(), ctrl_cmd_send2(), CTRL_TYPE_ERROR, ctrl_type_vals, ipaccess_head::data, ipaccess_head_ext::data, ctrl_handle::data, ctrl_cmd::defer, DLCTRL, DLINP, osmo_fd::fd, get_value_string(), ctrl_cmd::id, if(), ipa_ccm_send_id_ack(), ipa_ccm_send_pong(), IPAC_MSGT_ID_ACK, IPAC_MSGT_PING, IPAC_MSGT_PONG, IPAC_PROTO_EXT_CTRL, IPAC_PROTO_IPACCESS, IPAC_PROTO_OSMO, LOGL_DEBUG, LOGL_ERROR, LOGP, msg, msg_type, msgb_hexdump(), ipaccess_head::proto, ipaccess_head_ext::proto, ctrl_cmd::reply, ctrl_cmd::type, ctrl_cmd::variable, and ctrl_connection::write_queue.

Referenced by handle_control_read().

ctrl_interface_setup()

struct ctrl_handle * ctrl_interface_setup	(	void *	data,
		uint16_t	port,
		ctrl_cmd_lookup	lookup
	)

References ctrl_interface_setup2(), data, and ctrl_handle::lookup.

ctrl_interface_setup2()

struct ctrl_handle * ctrl_interface_setup2	(	void *	data,
		uint16_t	default_port,
		ctrl_cmd_lookup	lookup,
		unsigned int	node_count
	)

Initializes CTRL interface using the configured bind addr/port.

Parameters

[in]	data	Pointer which will be made available to each set_..() get_..() verify_..() control command function
[in]	default_port	TCP port number to bind to if not explicitly configured
[in]	lookup	Lookup function pointer, can be NULL
[in]	node_count	Number of CTRL nodes to allocate, 0 for default.

References ctrl_interface_setup_dynip2(), ctrl_vty_get_bind_addr(), ctrl_vty_get_bind_port(), data, and ctrl_handle::lookup.

Referenced by ctrl_interface_setup().

ctrl_interface_setup_dynip()

struct ctrl_handle * ctrl_interface_setup_dynip	(	void *	data,
		const char *	bind_addr,
		uint16_t	port,
		ctrl_cmd_lookup	lookup
	)

Setup CTRL interface on a given address.

Parameters

[in]	data	Pointer which will be made available to each set_..() get_..() verify_..() control command function
[in]	bind_addr	Address on which CTRL socket shall listen
[in]	port	Port on which CTRL socket shall listen
[in]	lookup	Lookup function pointer, can be NULL

Returns

ctrl_handle pointer or NULL in case of errors

References ctrl_interface_setup_dynip2(), data, and ctrl_handle::lookup.

ctrl_interface_setup_dynip2()

struct ctrl_handle * ctrl_interface_setup_dynip2	(	void *	data,
		const char *	bind_addr,
		uint16_t	port,
		ctrl_cmd_lookup	lookup,
		unsigned int	node_count
	)

Setup CTRL interface on a given address.

Parameters

[in]	data	Pointer which will be made available to each set_..() get_..() verify_..() control command function
[in]	bind_addr	Address on which CTRL socket shall listen
[in]	port	Port on which CTRL socket shall listen
[in]	lookup	Lookup function pointer, can be NULL
[in]	node_count	Number of CTRL nodes to allocate, 0 for default.

Returns

ctrl_handle pointer or NULL in case of errors

Control interface nodes are identified by a node handle; some of these are defined in enum ctrl_node_type, here in libosmocore. However, applications defining own nodes may add own control nodes without having to extend the enum in libosmocore. For example, in the calling application, define an enum like "enum more_ctrl_nodes { CTRL_NODE_FOO = _LAST_CTRL_NODE, CTRL_NODE_BAR, _LAST_CTRL_NODE_EXTENDED }". In order to provide space for the additional control nodes, pass _LAST_CTRL_NODE_EXTENDED to the node_count parameter. Passing 0 is identical to passing _LAST_CTRL_NODE, i.e. to not define own control nodes apart from libosmocore ones.

References osmo_fd::cb, ctrl_handle_alloc2(), osmo_fd::data, data, DLCTRL, ctrl_handle::listen_fd, listen_fd_cb(), LOGL_NOTICE, LOGP, ctrl_handle::lookup, OSMO_SOCK_F_BIND, and osmo_sock_init_ofd().

Referenced by ctrl_interface_setup2(), and ctrl_interface_setup_dynip().

ctrl_lookup_register()

int ctrl_lookup_register

(

ctrl_cmd_lookup

lookup

)

Install a lookup helper function for control nodes This function is used by e.g.

library code to install lookup helpers for additional nodes in the control interface.

Parameters

[in]

lookup

The lookup helper function

Returns

- on success; negative on error.

References list, lookup_helper::list, llist_add_tail(), llist_for_each_entry, and lookup_helper::lookup.

Referenced by osmo_fsm_ctrl_cmds_install().

ctrl_parse_get_num()

int ctrl_parse_get_num	(	vector	vline,
		int	i,
		long *	num
	)

Parse ascii-encoded decimal number at vline[i].

Parameters

[in]	vline	vector containing a tokenized line
[in]	i	index into the vector vline
[out]	num	parsed decimal integer number at vline[i]

Returns

1 on success; 0 in case of error

References osmo_str_to_int64(), vector_active, and vector_slot.

osmo_ctrl_conn_alloc()

struct ctrl_connection * osmo_ctrl_conn_alloc	(	void *	ctx,
		void *	data
	)

Allocate CTRL connection.

Parameters

[in]	ctx	Context from which talloc should allocate it
[in]	data	caller's private data parameter which should assigned to write queue's file descriptor data parameter.

Returns

Allocated CTRL connection structure or NULL in case of errors

References osmo_wqueue::bfd, ctrl_connection::cmds, control_write_cb(), osmo_fd::data, data, ctrl_connection::def_cmds, osmo_fd::fd, handle_control_read(), INIT_LLIST_HEAD, osmo_wqueue_init(), osmo_wqueue::read_cb, osmo_wqueue::write_cb, and ctrl_connection::write_queue.

Referenced by listen_fd_cb().