diff options
Diffstat (limited to 'src/ctrl')
| -rw-r--r-- | src/ctrl/control_cmd.c | 49 | ||||
| -rw-r--r-- | src/ctrl/control_if.c | 22 |
2 files changed, 67 insertions, 4 deletions
diff --git a/src/ctrl/control_cmd.c b/src/ctrl/control_cmd.c index fb0cd2b7..bff4d17d 100644 --- a/src/ctrl/control_cmd.c +++ b/src/ctrl/control_cmd.c @@ -89,6 +89,12 @@ static struct ctrl_cmd_element *ctrl_cmd_get_element_match(vector vline, vector return NULL; } +/*! Execute a given received command + * \param[in] vline vector representing the available/registered commands + * \param[inout] command parsed received command to be executed + * \param[in] node CTRL interface node + * \param[in] data opaque data passed to verify(), get() and set() call-backs + * \returns CTRL_CMD_HANDLED or CTRL_CMD_REPLY; CTRL_CMD_ERROR on error */ int ctrl_cmd_exec(vector vline, struct ctrl_cmd *command, vector node, void *data) { int ret = CTRL_CMD_ERROR; @@ -200,6 +206,10 @@ failure: talloc_free(cmd->command); } +/*! Install a given command definition at a given CTRL node. + * \param[in] node CTRL node at whihc \a cmd is to be installed + * \param[in] cmd command definition to be installed + * \returns 0 on success; negative on error */ int ctrl_cmd_install(enum ctrl_node_type node, struct ctrl_cmd_element *cmd) { vector cmds_vec; @@ -221,6 +231,10 @@ int ctrl_cmd_install(enum ctrl_node_type node, struct ctrl_cmd_element *cmd) return 0; } +/*! Allocate a control command of given \a type. + * \param[in] ctx talloc context from which to allocate + * \param[in] type command type to set after allocation + * \returns callee-allocated \ref ctrl_cmd. Caller must talloc_free() it. */ struct ctrl_cmd *ctrl_cmd_create(void *ctx, enum ctrl_type type) { struct ctrl_cmd *cmd; @@ -233,6 +247,10 @@ struct ctrl_cmd *ctrl_cmd_create(void *ctx, enum ctrl_type type) return cmd; } +/*! Perform a deepl copy of the given \a cmd, allocating memory from \a ctx. + * \param[in] ctx talloc context from which to allocate + * \param[in cmd CTRL command to be copied + * \returns deep copy of \a cmd on success; NULL on error */ struct ctrl_cmd *ctrl_cmd_cpy(void *ctx, struct ctrl_cmd *cmd) { struct ctrl_cmd *cmd2; @@ -269,7 +287,10 @@ err: return NULL; } -/*! Parse CTRL command struct from msgb, return NULL on any error. +/*! Parse/Decode CTRL from \ref msgb into command struct. + * \param[in] ctx talloc context from which to allocate + * \param[in] msg message buffer containing command to be decoded + * \returns callee-allocated decoded CTRL command; NULL on allocation or other failure * The caller is responsible to talloc_free() the returned struct pointer. */ struct ctrl_cmd *ctrl_cmd_parse(void *ctx, struct msgb *msg) { @@ -290,8 +311,11 @@ static bool id_str_valid(const char *str) return true; } -/*! Parse CTRL command struct from msgb, return ctrl->type == CTRL_TYPE_ERROR and an error message in - * ctrl->reply on any error. +/*! Parse/Decode CTRL from \ref msgb into command struct. + * \param[in] ctx talloc context from which to allocate + * \param[in] msg message buffer containing command to be decoded + * \returns callee-allocated decoded CTRL command; NULL on allocation failure, + * ctrl->type == CTRL_TYPE_ERROR and an error message in ctrl->reply on any error. * The caller is responsible to talloc_free() the returned struct pointer. */ struct ctrl_cmd *ctrl_cmd_parse2(void *ctx, struct msgb *msg) { @@ -466,6 +490,9 @@ err: return cmd; } +/*! Encode a given CTRL command from its parsed form into a message buffer. + * \param[in] cmd decoded/parsed form of to-be-encoded command + * \returns callee-allocated message buffer containing the encoded \a cmd; NULL on error */ struct msgb *ctrl_cmd_make(struct ctrl_cmd *cmd) { struct msgb *msg; @@ -556,6 +583,15 @@ err: return NULL; } +/*! Build a deferred control command state and keep it the per-connection list of deferred commands. + * This function is typically called by a ctrl command handler that wishes to defer returning a + * response. The reutnred state can later be used to check if the deferred command is still alive, + * and to respond to the specific command. This only works to defer the response to GET and SET. + * \param[in] ctx talloc context from whihc to allocate the ctrl_cmd_def + * \param[in] cmd the control command whose response is deferred + * \param[in] data opaque, user-defined pointer + * \param[in] secs number of seconds until the command times out + * \returns callee-allocated ctrl_cmd_def */ struct ctrl_cmd_def * ctrl_cmd_def_make(const void *ctx, struct ctrl_cmd *cmd, void *data, unsigned int secs) { @@ -576,6 +612,9 @@ ctrl_cmd_def_make(const void *ctx, struct ctrl_cmd *cmd, void *data, unsigned in return cd; } +/*! Determine if the given deferred control command is still alive or a zombie. + * \param[in] cd deferred ctrl command state + * \returns 0 is \a cd is still alive; 1 if it's a zombie */ int ctrl_cmd_def_is_zombie(struct ctrl_cmd_def *cd) { /* luckily we're still alive */ @@ -589,6 +628,10 @@ int ctrl_cmd_def_is_zombie(struct ctrl_cmd_def *cd) return 1; } +/*! Send the response to a deferred ctrl command. + * The command can only be a resply to a SET or a GET operation. + * \param[in] cd deferred ctrl command state + * \returns 0 if command sent successfully; negative on error */ int ctrl_cmd_def_send(struct ctrl_cmd_def *cd) { struct ctrl_cmd *cmd = cd->cmd; diff --git a/src/ctrl/control_if.c b/src/ctrl/control_if.c index 269b7b93..d3e6faca 100644 --- a/src/ctrl/control_if.c +++ b/src/ctrl/control_if.c @@ -75,6 +75,11 @@ struct lookup_helper { }; static LLIST_HEAD(ctrl_lookup_helpers); +/*! Parse ascii-encoded decimal number at vline[i] + * \param[in] vline vector containing a tokenized line + * \param[in] i index into the vector \a vline + * \param[out] num parsed decimal integer number at vline[i] + * \returns 1 on success; 0 in case of error */ int ctrl_parse_get_num(vector vline, int i, long *num) { char *token, *tmp; @@ -94,7 +99,10 @@ int ctrl_parse_get_num(vector vline, int i, long *num) return 1; } -/* Send command to all */ +/*! Send a CTRL command to all connections. + * \param[in] ctrl global control handle + * \param[in] cmd command to send to all connections in \ctrl + * \returns number of times the command has been sent */ int ctrl_cmd_send_to_all(struct ctrl_handle *ctrl, struct ctrl_cmd *cmd) { struct ctrl_connection *ccon; @@ -109,6 +117,10 @@ int ctrl_cmd_send_to_all(struct ctrl_handle *ctrl, struct ctrl_cmd *cmd) return ret; } +/*! Encode a CTRL command and append it to the given write queue + * \param[inout] queue write queue to which encoded \a cmd shall be appended + * \param[in] cmd decoded command representation + * \returns 0 in case of success; negative on error */ int ctrl_cmd_send(struct osmo_wqueue *queue, struct ctrl_cmd *cmd) { int ret; @@ -152,6 +164,9 @@ int ctrl_cmd_send_trap(struct ctrl_handle *ctrl, const char *name, char *value) return r; } +/*! Copy given \a cmd and convert copy to CTRL_TYPE_TRAP. + * \param[in] cmd command to be copied + * \returns pointer to newly-allocated copy of type TRAP. Allocated as sibling of \a cmd */ struct ctrl_cmd *ctrl_cmd_trap(struct ctrl_cmd *cmd) { struct ctrl_cmd *trap; @@ -361,6 +376,11 @@ close_fd: return -EBADF; } +/*! Handle a received CTRL command contained in a \ref msgb. + * \param[in] ctrl CTRL interface handle + * \param[in] ccon CTRL connection through which the command was received + * \param[in] msg message buffer containing CTRL command including IPA+IPA_EXT headers + * \returns 0 on success; negative on error */ int ctrl_handle_msg(struct ctrl_handle *ctrl, struct ctrl_connection *ccon, struct msgb *msg) { struct ctrl_cmd *cmd; |