Command Handler: Configuration support

Overview

A set of functions exported by a Test Agent to support interface of Command Handler for Test Agent configuration. More…

// typedefs

typedef te_errno (*rcf_ch_cfg_get)(
    unsigned int gid,
    const char *oid,
    char *value,
    ...
    );

typedef te_errno (*rcf_ch_cfg_set)(
    unsigned int gid,
    const char *oid,
    const char *value,
    ...
    );

typedef te_errno (*rcf_ch_cfg_add)(
    unsigned int gid,
    const char *oid,
    const char *value,
    ...
    );

typedef te_errno (*rcf_ch_cfg_del)(
    unsigned int gid,
    const char *oid,
    ...
    );

typedef te_errno (*rcf_ch_cfg_list)(
    unsigned int gid,
    const char *oid,
    const char *sub_id,
    char **list,
    ...
    );

typedef te_errno (*rcf_ch_cfg_commit)(
    unsigned int gid,
    const cfg_oid *p_oid
    );

typedef te_errno (*rcf_ch_substitution_apply)(
    te_string *src,
    const char *new,
    const char *old
    );

typedef struct rcf_pch_cfg_substitution rcf_pch_cfg_substitution;
typedef struct rcf_pch_cfg_object rcf_pch_cfg_object;

// enums

enum rcf_ch_cfg_op_t;

// structs

struct rcf_pch_cfg_object;
struct rcf_pch_cfg_substitution;

// global functions

int rcf_ch_configure(struct rcf_comm_connection* handle, char* cbuf, size_t buflen, size_t answer_plen, const uint8_t* ba, size_t cmdlen, rcf_ch_cfg_op_t op, const char* oid, const char* val);
int rcf_ch_conf_init(void);
void rcf_ch_conf_fini(void);
const char* rcf_ch_conf_agent(void);

Detailed Documentation

A set of functions exported by a Test Agent to support interface of Command Handler for Test Agent configuration.

Typedefs

typedef te_errno (*rcf_ch_cfg_get)(
    unsigned int gid,
    const char *oid,
    char *value,
    ...
    )

Prototype for get instance value routine.

Parameters:

gid	group identifier
oid	full object instance identifier
value	location for the value (a buffer of RCF_MAX_VAL bytes size)
…	Up to 10 instance names (if there are less instances in configuration path than arguments, extra arguments will be set to `NULL`)

Returns:

Status code

typedef te_errno (*rcf_ch_cfg_set)(
    unsigned int gid,
    const char *oid,
    const char *value,
    ...
    )

Prototype for set instance value routine.

Parameters:

gid	group identifier
oid	full object instance identifier
value	value to set
…	Up to 10 instance names (if there are less instances in configuration path than arguments, extra arguments will be set to `NULL`)

Returns:

Status code

typedef te_errno (*rcf_ch_cfg_add)(
    unsigned int gid,
    const char *oid,
    const char *value,
    ...
    )

Prototype for add instance routine.

Parameters:

gid	group identifier
oid	full object instance identifier
value	value to set or NULL
…	Up to 10 instance names (if there are less instances in configuration path than arguments, extra arguments will be set to `NULL`)

Returns:

Status code

typedef te_errno (*rcf_ch_cfg_del)(
    unsigned int gid,
    const char *oid,
    ...
    )

Prototype for delete instance routine.

Parameters:

gid	group identifier
oid	full object instance identifier
…	Up to 10 instance names (if there are less instances in configuration path than arguments, extra arguments will be set to `NULL`)

Returns:

Status code

typedef te_errno (*rcf_ch_cfg_list)(
    unsigned int gid,
    const char *oid,
    const char *sub_id,
    char **list,
    ...
    )

Prototype for a routine that returns the list of instance names for an object. The routine should allocate memory for instance list with malloc(). Caller is responsible for releasing of this memory.

Parameters:

gid	group identifier
oid	full object instance identifier of the parent
sub_id	ID (name) of the object to be listed
list	location for the returned list pointer (list entries should be separated with SPACE character. For example if we need to return names ‘a’, ‘b’, ‘c’, then returned string would be “a b c”
…	Up to 10 instance names (if there are less instances in configuration path than arguments, extra arguments will be set to `NULL`)

Returns:

Status code

typedef te_errno (*rcf_ch_cfg_commit)(
    unsigned int gid,
    const cfg_oid *p_oid
    )

Propotype of the commit function.

Parameters:

gid	group identifier
p_oid	parsed object instance identifier

Returns:

Status code

typedef te_errno (*rcf_ch_substitution_apply)(
    te_string *src,
    const char *new,
    const char *old
    )

Type of the function to apply the substitution.

Parameters:

src	The string in which the substitution is performed.
new	The string to replace.
old	The string to be replaced.

Returns:

Status code

typedef struct rcf_pch_cfg_object rcf_pch_cfg_object

Configuration tree node

Global Functions

int rcf_ch_configure(struct rcf_comm_connection* handle, char* cbuf, size_t buflen, size_t answer_plen, const uint8_t* ba, size_t cmdlen, rcf_ch_cfg_op_t op, const char* oid, const char* val)

Configure the Test Agent or NUT served by it.

If Test Agent does not want to support their own handler for configure operations, then a Test Agent shall implement this function as returning -1 telling PCH that we rely on generic function available in PCH.

Parameters:

handle	connection handle
cbuf	command buffer
buflen	length of the command buffer
answer_plen	number of bytes in the command buffer to be copied to the answer
ba	pointer to location of binary attachment in the command buffer or NULL if no binary attachment is provided
cmdlen	full length of the command including binary attachment
op	configure operation
oid	object instance identifier or NULL
val	object instance value or NULL
0	command is supported
-1	command is not supported
other	error returned by communication library

Returns:

Indication of command support or error code

int rcf_ch_conf_init(void)

Initialize configuration support of Command Handler (Test Agent specific initialization).

In this function a Test Agent calls rcf_pch_add_node() in order to register nodes that it will support during its operation.

Parameters:

0	initialization successfully completed
-1	initialization failed

Returns:

Status of the operation

void rcf_ch_conf_fini(void)

Release resources allocated for configuration support.

const char* rcf_ch_conf_agent(void)

Returns name of the Test Agent (caller does not free or change the memory where the name is located).

Returns:

Agent name