command.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <kfsw/services/parameter.h>

Data Structures
struct	kfsw_command_stats
struct	kfsw_command_arg
struct	kfsw_command_source
struct	kfsw_command_result
struct	kfsw_command_definition
struct	kfsw_command_definition_set
struct	kfsw_command_info

Macros
#define	KFSW_COMMAND_MAX_ARGS   4U
#define	KFSW_COMMAND_MAX_TEXT_SIZE   64U
#define	KFSW_COMMAND_MAX_DETAIL_SIZE   96U
#define	KFSW_COMMAND_TIMEOUT_MIN_MS   1000U
#define	KFSW_COMMAND_TIMEOUT_MAX_MS   120000U
#define	KFSW_COMMAND_FLAG_MUTATING   BIT(0)
#define	KFSW_COMMAND_PARAM_TABLE_ID   28U
#define	KFSW_COMMAND_PARAM_TABLE_NAME   "command"

Types
typedef int(*	kfsw_command_handler_t) (const struct kfsw_command_arg *args, size_t arg_count, const struct kfsw_command_source *source, struct kfsw_command_result *result)
typedef bool(*	kfsw_command_visitor_t) (const struct kfsw_command_info *info, void *context)
typedef void(*	kfsw_command_echo_handler_t) (bool enabled)

Enumerations
enum	kfsw_command_type { KFSW_COMMAND_TYPE_U32 = 1 , KFSW_COMMAND_TYPE_I32 = 2 , KFSW_COMMAND_TYPE_TEXT = 3 }
enum	kfsw_command_status {   KFSW_COMMAND_OK = 0 , KFSW_COMMAND_UNKNOWN = 1 , KFSW_COMMAND_INVALID_ARGUMENT = 2 , KFSW_COMMAND_DENIED = 3 ,   KFSW_COMMAND_BUSY = 4 , KFSW_COMMAND_FAILED = 5 , KFSW_COMMAND_UNAVAILABLE = 6 }
enum	kfsw_event_command_id { KFSW_EVENT_COMMAND_INVOKED = 1 , KFSW_EVENT_COMMAND_UNKNOWN = 2 , KFSW_EVENT_COMMAND_REJECTED = 3 }

Functions
int	kfsw_command_init (const struct kfsw_command_definition_set *const *sets, size_t set_count)
bool	kfsw_command_is_initialized (void)
void	kfsw_command_visit (kfsw_command_visitor_t visitor, void *context)
int	kfsw_command_parse_arg (const char *text, enum kfsw_command_type type, struct kfsw_command_arg *arg)
int	kfsw_command_find (const char *name, struct kfsw_command_info *info)
int	kfsw_command_invoke (const char *name, const struct kfsw_command_arg *args, size_t arg_count, struct kfsw_command_result *result)
int	kfsw_command_invoke_id (uint16_t id, const struct kfsw_command_arg *args, size_t arg_count, const struct kfsw_command_source *source, struct kfsw_command_result *result)
const char *	kfsw_command_status_name (enum kfsw_command_status status)
int	kfsw_command_get_stats (struct kfsw_command_stats *stats)
void	kfsw_command_set_echo_handler (kfsw_command_echo_handler_t handler)
bool	kfsw_command_echo_enabled (void)
void	kfsw_command_set_echo (bool enabled)

Variables
const struct kfsw_param_definition_set	kfsw_command_param_definitions

Description

Command registry and its two front ends.

Commands called by name from the shell and by ID over CSP.

Both use the same definition, validation and handler. Definitions are registered at build time, and the registry is fixed before startup ends.

Macro Documentation

KFSW_COMMAND_FLAG_MUTATING

#define KFSW_COMMAND_FLAG_MUTATING   BIT(0)

Command flags.

KFSW_COMMAND_PARAM_TABLE_ID

#define KFSW_COMMAND_PARAM_TABLE_ID   28U

Parameter table of this service, in the service band.

KFSW_COMMAND_PARAM_TABLE_NAME

#define KFSW_COMMAND_PARAM_TABLE_NAME   "command"

Parameter table name.

Type Documentation

kfsw_command_echo_handler_t

typedef void(* kfsw_command_echo_handler_t) (bool enabled)

Applies console echo; provided by the application.

kfsw_command_handler_t

typedef int(* kfsw_command_handler_t) (const struct kfsw_command_arg *args, size_t arg_count, const struct kfsw_command_source *source, struct kfsw_command_result *result)

Command implementation.

Runs in the caller's thread under the command mutex. Remote requests use the command server thread, not the CSP router. Arguments have been checked for count and type. Text is NUL-terminated and valid only during the call.

Enumeration Documentation

kfsw_command_status

enum kfsw_command_status

Outcome of one command invocation.

kfsw_command_type

enum kfsw_command_type

Argument and result value kinds carried on the wire.

kfsw_event_command_id

enum kfsw_event_command_id

Event IDs of the command service.

IDs are never reused. Payload: command ID and source node as big-endian u16, then the status byte.

Enumerator
KFSW_EVENT_COMMAND_INVOKED	A command ran, whatever its outcome.
KFSW_EVENT_COMMAND_UNKNOWN	A request named a command this node does not implement.
KFSW_EVENT_COMMAND_REJECTED	A request failed validation before any handler ran.

Function Documentation

kfsw_command_echo_enabled()

bool kfsw_command_echo_enabled

(

void

)

Whether console echo is enabled.

Off by default.

kfsw_command_find()

int kfsw_command_find	(	const char *	name,
		struct kfsw_command_info *	info
	)

Look up one registered command by name.

Returns -ENOENT when absent.

kfsw_command_get_stats()

int kfsw_command_get_stats

(

struct kfsw_command_stats *

stats

)

Read the lifetime totals.

Returns -EINVAL for a NULL destination.

kfsw_command_init()

int kfsw_command_init	(	const struct kfsw_command_definition_set *const *	sets,
		size_t	set_count
	)

Aggregate the supplied definition sets and freeze the registry.

Rejects duplicate identifiers, duplicate names, missing handlers, and argument counts above KFSW_COMMAND_MAX_ARGS.

kfsw_command_invoke()

int kfsw_command_invoke	(	const char *	name,
		const struct kfsw_command_arg *	args,
		size_t	arg_count,
		struct kfsw_command_result *	result
	)

Invoke a command on this node by name.

kfsw_command_invoke_id()

int kfsw_command_invoke_id	(	uint16_t	id,
		const struct kfsw_command_arg *	args,
		size_t	arg_count,
		const struct kfsw_command_source *	source,
		struct kfsw_command_result *	result
	)

Invoke a command on this node by wire identifier.

kfsw_command_is_initialized()

bool kfsw_command_is_initialized

(

void

)

Return whether the registry was built successfully.

kfsw_command_parse_arg()

int kfsw_command_parse_arg	(	const char *	text,
		enum kfsw_command_type	type,
		struct kfsw_command_arg *	arg
	)

Convert one text argument to the type a command declares.

A text argument is not copied: text must outlive the invocation.

Parameters

	text	Argument as written.
	type	Type the command declares for that position.
[out]	arg	Destination.

Return values

0	Converted.
-EINVAL	text is not a number where one is required, or a NULL was given.
-ENAMETOOLONG	The text is longer than KFSW_COMMAND_MAX_TEXT_SIZE.
-ENOTSUP	The type is not one this service carries.

kfsw_command_set_echo()

void kfsw_command_set_echo

(

bool

enabled

)

Change console echo and apply it through the registered handler.

kfsw_command_set_echo_handler()

void kfsw_command_set_echo_handler

(

kfsw_command_echo_handler_t

handler

)

Register the function that applies console echo, and apply the current value.

kfsw_command_status_name()

const char * kfsw_command_status_name

(

enum kfsw_command_status

status

)

Human-readable name for a status, for shell output and logs.

kfsw_command_visit()

void kfsw_command_visit	(	kfsw_command_visitor_t	visitor,
		void *	context
	)

Visit each registered command.

Variable Documentation

kfsw_command_param_definitions

const struct kfsw_param_definition_set kfsw_command_param_definitions

extern

Command counters and reply timeout.