summaryrefslogtreecommitdiffstats
path: root/src/ctrl
diff options
context:
space:
mode:
Diffstat (limited to 'src/ctrl')
-rw-r--r--src/ctrl/control_cmd.c49
-rw-r--r--src/ctrl/control_if.c22
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;