API: RCF

Overview

// typedefs

typedef enum rcf_call_mode rcf_call_mode_t;
typedef enum rcf_trrecv_mode rcf_trrecv_mode;

typedef void (*rcf_pkt_handler)(
    const char *pkt,
    void *user_param
    );

typedef struct rcf_trpoll_csap rcf_trpoll_csap;

typedef te_errno rcf_ta_cb(
    const char *ta,
    void *cookie
    );

// enums

enum rcf_call_mode;
enum rcf_reboot_type;
enum rcf_ta_flags;
enum rcf_trrecv_mode;

// structs

struct rcf_trpoll_csap;

// global functions

static const char* rcf_server_name(void);
static const char* rcf_call_mode2str(rcf_call_mode_t mode);
te_errno rcf_add_ta(const char* name, const char* type, const char* rcflib, const char* confstr, unsigned int flags);
te_errno rcf_add_ta_unix(const char* name, const char* type, const char* host, uint16_t port, unsigned int copy_timeout, unsigned int kill_timeout, unsigned int flags);
te_errno rcf_del_ta(const char* name);
te_errno rcf_get_ta_list(char* buf, size_t* len);
te_errno rcf_ta_name2type(const char* ta_name, char* ta_type);
te_errno rcf_ta_create_session(const char* ta_name, int* session);
te_errno rcf_ta_reboot(const char* ta_name, const char* boot_params, const char* image, rcf_reboot_type reboot_type);
void rcf_log_cfg_changes(bool enable);
te_errno rcf_ta_cfg_get(const char* ta_name, int session, const char* oid, char* val_buf, size_t len);
te_errno rcf_ta_cfg_set(const char* ta_name, int session, const char* oid, const char* val);
te_errno rcf_ta_cfg_add(const char* ta_name, int session, const char* oid, const char* val);
te_errno rcf_ta_cfg_del(const char* ta_name, int session, const char* oid);
te_errno rcf_ta_cfg_group(const char* ta_name, int session, bool is_start);
te_errno rcf_get_sniffer_dump(const char* ta_name, const char* snif_id, char* fname, unsigned long long* offset);
te_errno rcf_ta_get_sniffers(const char* ta_name, const char* snif_id, char** buf, size_t* len, bool sync);
te_errno rcf_ta_get_log(const char* ta_name, char* log_file);
te_errno rcf_ta_get_var(const char* ta_name, int session, const char* var_name, rcf_var_type_t var_type, size_t var_len, void* val);
te_errno rcf_ta_set_var(const char* ta_name, int session, const char* var_name, rcf_var_type_t var_type, const char* val);
te_errno rcf_ta_get_file(const char* ta_name, int session, const char* rfile, const char* lfile);
te_errno rcf_ta_put_file(const char* ta_name, int session, const char* lfile, const char* rfile);
te_errno rcf_ta_del_file(const char* ta_name, int session, const char* rfile);
te_errno rcf_tr_op_log(bool ring);
bool rcf_tr_op_log_get(void);
te_errno rcf_ta_csap_create(const char* ta_name, int session, const char* stack_id, const char* params, csap_handle_t* csap_id);
te_errno rcf_ta_csap_destroy(const char* ta_name, int session, csap_handle_t csap_id);
te_errno rcf_ta_csap_param(const char* ta_name, int session, csap_handle_t csap_id, const char* var, size_t var_len, char* val);
te_errno rcf_ta_trsend_start(const char* ta_name, int session, csap_handle_t csap_id, const char* templ, rcf_call_mode_t blk_mode);
te_errno rcf_ta_trsend_stop(const char* ta_name, int session, csap_handle_t csap_id, int* num);
te_errno rcf_ta_trrecv_start(const char* ta_name, int session, csap_handle_t csap_id, const char* pattern, unsigned int timeout, unsigned int num, unsigned int mode);
te_errno rcf_ta_trrecv_wait(const char* ta_name, int session, csap_handle_t csap_id, rcf_pkt_handler handler, void* user_param, unsigned int* num);
te_errno rcf_ta_trrecv_stop(const char* ta_name, int session, csap_handle_t csap_id, rcf_pkt_handler handler, void* user_param, unsigned int* num);
te_errno rcf_ta_trrecv_get(const char* ta_name, int session, csap_handle_t csap_id, rcf_pkt_handler handler, void* user_param, unsigned int* num);
te_errno rcf_ta_trsend_recv(const char* ta_name, int session, csap_handle_t csap_id, const char* templ, rcf_pkt_handler handler, void* user_param, unsigned int timeout, int* error);
te_errno rcf_trpoll(rcf_trpoll_csap* csaps, unsigned int n_csaps, unsigned int timeout);
te_errno rcf_ta_call(const char* ta_name, int session, const char* rtn, int* error, int argc, bool argv, ...);
te_errno rcf_ta_start_task(const char* ta_name, int session, int priority, const char* rtn, pid_t* pid, int argc, bool argv, ...);
te_errno rcf_ta_start_thread(const char* ta_name, int session, int priority, const char* rtn, int* tid, int argc, bool argv, ...);
te_errno rcf_ta_kill_task(const char* ta_name, int session, pid_t pid);
te_errno rcf_ta_kill_thread(const char* ta_name, int session, int tid);
te_errno rcf_ta_call_rpc(const char* ta_name, int session, const char* rpcserver, int timeout, const char* rpc_name, void* in, void* out);
te_errno rcf_check_agent(const char* ta_name);
te_errno rcf_check_agents(void);
te_errno rcf_shutdown_call(void);
void rcf_api_cleanup(void);
te_errno rcf_foreach_ta(rcf_ta_cb* cb, void* cookie);
te_errno rcf_get_dead_agents(te_vec* dead_agents);

// macros

#define RCF_SERVER
#define RCF_TRRECV_REPORT_MASK

Detailed Documentation

Typedefs

typedef enum rcf_call_mode rcf_call_mode_t

List of modes that can be used while calling RCF functions especially for those that deal with traffic application domain

typedef enum rcf_trrecv_mode rcf_trrecv_mode

List of modes that can be used while calling RCF traffic receive operation.

typedef void (*rcf_pkt_handler)(
    const char *pkt,
    void *user_param
    )

Function - handler of received packets

typedef struct rcf_trpoll_csap rcf_trpoll_csap

CSAP parameters to be used for polling of many CSAPs.

typedef te_errno rcf_ta_cb(
    const char *ta,
    void *cookie
    )

Prototype of the function to be called for each Test Agent.

Iterator terminates if callback returns non zero.

Parameters:

ta	Test agent
cookie	Callback opaque data

Returns:

Status code.

Global Functions

static const char* rcf_server_name(void)

Discover name of the RCF IPC server

static const char* rcf_call_mode2str(rcf_call_mode_t mode)

Convert mode of RCF traffic operation to string.

Parameters:

mode	Mode to convert

Returns:

Mode as string

te_errno rcf_add_ta(const char* name, const char* type, const char* rcflib, const char* confstr, unsigned int flags)

Add a new Test Agent to RCF.

Parameters:

name	Test Agent name
type	Test Agent type
rcflib	Name of RCF TA-specific shared library to be used to control Test Agent
confstr	TA-specific configuration string (kvpairs)
flags	Test Agent control flags (see rcf_ta_flags)
0	success
TE_EEXIST	Test Agent with such name exists and running
TE_ETOOMANY	Too many Test Agents are added, no more space

Returns:

Error code

te_errno rcf_add_ta_unix(const char* name, const char* type, const char* host, uint16_t port, unsigned int copy_timeout, unsigned int kill_timeout, unsigned int flags)

Add a new Test Agent controlled using rcfunix TA-specific shared library.

Parameters:

name	Test Agent name
type	Test Agent type
host	Host name or IPv4 address in dotted notation
port	TCP port to be used on Test Agent to listen to
copy_timeout	Test Agent image coping timeout or 0 for default
kill_timeout	Test Agent kill timeout or 0 for default
flags	Test Agent control flags (see rcf_ta_flags)

Returns:

Error code See ‘rcf_add_ta’ error codes

te_errno rcf_del_ta(const char* name)

Delete Test Agent from RCF.

Parameters:

name	Test Agent name
0	success
TE_ENOENT	Test Agent with such name does not exist
TE_EPERM	Test Agent with such name exists but is specified in RCF configuration file

Returns:

Error code

te_errno rcf_get_ta_list(char* buf, size_t* len)

This function returns list of Test Agents (names) running.

Parameters:

buf	location for the name list; names are put to the buffer one-by-one and are separated by “’0’”; the list is finished by “’0’” as well
len	pointer to length variable (should be set to the length the buffer by caller; is filled to amount of space used for the name list by the routine)
0	success
TE_ESMALLBUF	the buffer is too small
TE_EIPC	cannot interact with RCF
TE_ENOMEM	out of memory

Returns:

error code

te_errno rcf_ta_name2type(const char* ta_name, char* ta_type)

This function maps name of the Test Agent to its type.

Parameters:

ta_name	Test Agent name
ta_type	Test Agent type location (should point to the buffer at least of RCF_MAX_NAME length)
0	success
TE_EINVAL	name of non-running Test Agent is provided
TE_EIPC	cannot interact with RCF
TE_ENOMEM	out of memory

Returns:

error code

te_errno rcf_ta_create_session(const char* ta_name, int* session)

This function returns unique session identifier for the Test Agent. This session identifier may be passed to all other TA-related routines. Command with session identifier X will be passed to the Test Agent before obtaining of answer on the command with session identifier Y (X != Y). However if the Test Agent does not support simultaneous processing of several commands, this mechanism does not give any advantage.

Parameters:

ta_name	Test Agent name
session	location for the session identifier
0	success
TE_EINVAL	name of non-running Test Agent is provided
TE_EIPC	cannot interact with RCF
TE_ENOMEM	out of memory

Returns:

error code

te_errno rcf_ta_reboot(const char* ta_name, const char* boot_params, const char* image, rcf_reboot_type reboot_type)

This function reboots the Test Agent or NUT served by it. It sends “reboot” command to the Test Agent, calls reboot function provided by RCF TA-specific library, restarts the TA and re-connects to it. The function may be called by Configurator only. It is prohibited to call the function for the TA running on the Testing Node.

Parameters:

ta_name	Test Agent name
boot_params	complete parameter string to be passed to the TA in the “reboot” command and to the reboot function of RCF TA-specific library (without quotes) or NULL
image	name of the bootable image (without path) to be passed to the Test Agent as binary attachment or NULL (it is assumed that NUT images are located in ${TE_INSTALL_NUT}/bin or ${TE_INSTALL}/nuts/bin)
reboot_type	Reboot type
0	success
TE_EINVAL	name of non-running or located on TN Test Agent is provided or parameter string is too long
TE_EIPC	cannot interact with RCF
TE_EINPROGRESS	operation is in progress
TE_ENOENT	cannot open NUT image file
TE_ENOMEM	out of memory
TE_EPERM	operation is not allowed (please check that you enabled `rebootable` attribute in RCF configuration file)

Returns:

error code

void rcf_log_cfg_changes(bool enable)

Enable/disable logging of TA configuration changes.

Parameters:

enable

if true, enable loging

te_errno rcf_ta_cfg_get(const char* ta_name, int session, const char* oid, char* val_buf, size_t len)

This function is used to obtain value of object instance by its identifier. The function may be called by Configurator only.

Parameters:

ta_name	Test Agent name
session	TA session or 0
oid	object instance identifier
val_buf	location for the object instance value
len	location length
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided or OID string is too long
TE_EIPC	cannot interact with RCF
TE_ESMALLBUF	the buffer is too small
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_ta_cfg_set(const char* ta_name, int session, const char* oid, const char* val)

This function is used to change value of object instance. The function may be called by Configurator only.

Parameters:

ta_name	Test Agent name
session	TA session or 0
oid	object instance identifier
val	object instance value
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided or too OID or value strings are too long
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_ta_cfg_add(const char* ta_name, int session, const char* oid, const char* val)

This function is used to create new object instance and assign the value to it. The function may be called by Configurator only.

Parameters:

ta_name	Test Agent name
session	TA session or 0
oid	object instance identifier
val	object instance value
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided or too OID or value strings are too long
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_ta_cfg_del(const char* ta_name, int session, const char* oid)

This function is used to remove the object instance. The function may be called by Configurator only.

Parameters:

ta_name	Test Agent name
session	TA session or 0
oid	object instance identifier
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided or OID string is too long
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_ta_cfg_group(const char* ta_name, int session, bool is_start)

This function is used to begin/finish group of configuration commands. The function may be called by Configurator only.

Parameters:

ta_name	Test Agent name
session	TA session or 0
is_start	Is start (`true`) or end (`false`) of a group?
0	success
TE_EIPC	cannot interact with RCF
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_get_sniffer_dump(const char* ta_name, const char* snif_id, char* fname, unsigned long long* offset)

This function is used to pull out capture logs from the sniffer. The only user of this calls is Logger.

Parameters:

ta_name	Test agent name
snif_id	The sniffer ID
fname	File name for the capture logs (IN/OUT)
offset	The absolute offset of the received part of capture.
0	success
TE_EINVAL	name of non-running TN Test Agent or bad sniffer ID are provided
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

Status code

te_errno rcf_ta_get_sniffers(const char* ta_name, const char* snif_id, char** buf, size_t* len, bool sync)

This function is used to get list of sniffers from the Test Agent. The function may be called by Logger only.

Parameters:

ta_name	Test Agent name
snif_id	Used to get offset of last captured packet for the sniffer
buf	Pointer to buffer for the list of sniffers (OUT). Memory for this buffer should be allocated by caller from heap, size should be specified in ‘len’ param. The memory may be reallocated by function. Caller is responsible to free this memory.
len	Size of incoming buffer and length of outgoing (IN/OUT)
sync	Sync sniffers offsets.
0	success
TE_EINVAL	name of non-running TN Test Agent or bad sniffer ID are provided
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
TE_ENOPROTOOPT	Agent side sniffer support is not available
other	error returned by command handler on the TA

Returns:

Status code

te_errno rcf_ta_get_log(const char* ta_name, char* log_file)

This function is used to get bulk of log from the Test Agent. The function may be called by Logger only.

Parameters:

ta_name	Test Agent name
log_file	name of the local file where log should be put (the file is truncated to zero length before updating)
0	success
TE_EINVAL	name of non-running TN Test Agent or bad file name are provided
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_ta_get_var(const char* ta_name, int session, const char* var_name, rcf_var_type_t var_type, size_t var_len, void* val)

This function is used to obtain value of the variable from the Test Agent or NUT served by it.

Parameters:

ta_name	Test Agent name
session	TA session or 0
var_name	name of the variable to be read
var_type	type according to which string returned from the TA should be converted
var_len	length of the location buffer
val	location for variable value
0	success
TE_EINVAL	one of arguments is invalid (NULL, too long or has inappropriate value)
TE_ENOENT	no such variable
TE_EIPC	cannot interact with RCF
TE_ESMALLBUF	the buffer is too small
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_ta_set_var(const char* ta_name, int session, const char* var_name, rcf_var_type_t var_type, const char* val)

This function is used to change value of the variable from the Test Agent or NUT served by it.

Parameters:

ta_name	Test Agent name
session	TA session or 0
var_name	name of the variable to be changed
var_type	type according to which variable value should appear in the protocol command
val	new value of the variable
0	success
TE_EINVAL	one of arguments is invalid (NULL, too long or has inappropriate value)
TE_ENOENT	no such variable
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_ta_get_file(const char* ta_name, int session, const char* rfile, const char* lfile)

This function loads file from Test Agent or NUT served by it to the testing node.

Parameters:

ta_name	Test Agent name
session	TA session or 0
rfile	full name of the file in the TA/NUT file system
lfile	full name of the file in the TN file system
0	success
TE_EINVAL	name of non-running TN Test Agent, non-existent session identifier or bad file name are provided
TE_EIPC	cannot interact with RCF
TE_ENOENT	no such file
TE_EPERM	operation not permitted
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

te_errno rcf_ta_put_file(const char* ta_name, int session, const char* lfile, const char* rfile)

This function loads file from the testing node to Test Agent or NUT served by it.

Parameters:

ta_name	Test Agent name
session	TA session or 0
lfile	full name of the file in the TN file system
rfile	full name of the file in the TA/NUT file system
0	success
TE_EINVAL	name of non-running TN Test Agent, non-existent session identifier or bad file name are provided
TE_EIPC	cannot interact with RCF
TE_ENOENT	no such file
TE_EPERM	operation not permitted
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

te_errno rcf_ta_del_file(const char* ta_name, int session, const char* rfile)

This function deletes file from the Test Agent or NUT served by it.

Parameters:

ta_name	Test Agent name
session	TA session or 0
rfile	full name of the file in the TA/NUT file system
0	success
TE_EINVAL	name of non-running TN Test Agent, non-existent session identifier or bad file name are provided
TE_EIPC	cannot interact with RCF
TE_ENOENT	no such file
TE_EPERM	operation not permitted
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

te_errno rcf_tr_op_log(bool ring)

Switch traffic operations logging among RING (enabled) and INFO (disabled) levels.

Parameters:

ring	`true` log using RING level, `false` log using INFO level

Returns:

Status code.

bool rcf_tr_op_log_get(void)

Get traffic operations logging level.

Returns:

true - log using RING level, false - log using INFO level.

te_errno rcf_ta_csap_create(const char* ta_name, int session, const char* stack_id, const char* params, csap_handle_t* csap_id)

This function creates CSAP (communication service access point) on the Test Agent.

Parameters:

ta_name	Test Agent name
session	TA session or 0
stack_id	protocol stack identifier
params	parameters necessary for CSAP creation (string or file name); if file with *params name exists, it is attached to the CSAP creation command as a binary attachment; otherwise the string is appended to the command
csap_id	location for unique CSAP handle
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

See also:

rcf_ta_csap_destroy

te_errno rcf_ta_csap_destroy(const char* ta_name, int session, csap_handle_t csap_id)

This function destroys CSAP.

Parameters:

ta_name	Test Agent name
session	TA session or 0
csap_id	CSAP handle
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_EIPC	cannot interact with RCF
TE_EBADF	no such CSAP
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

See also:

rcf_ta_csap_create

te_errno rcf_ta_csap_param(const char* ta_name, int session, csap_handle_t csap_id, const char* var, size_t var_len, char* val)

This function is used to obtain CSAP parameter value.

Parameters:

ta_name	Test Agent name
session	TA session or 0
csap_id	CSAP handle
var	parameter name
var_len	length of the location buffer
val	location for variable value
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_EIPC	cannot interact with RCF
TE_EBADF	no such CSAP
TE_ETAREBOOTED	Test Agent is rebooted
TE_ESMALLBUF	the buffer is too small

Returns:

error code

te_errno rcf_ta_trsend_start(const char* ta_name, int session, csap_handle_t csap_id, const char* templ, rcf_call_mode_t blk_mode)

This function is used to force sending of traffic via already created CSAP.

It may block caller according to “blk_mode” parameter value

Parameters:

ta_name	Test Agent name
session	TA session or 0
csap_id	CSAP handle
templ	full name of the file with traffic template
blk_mode	mode of the operation: in blocking mode it suspends the caller until sending of all the traffic finishes
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_EIPC	cannot interact with RCF
TE_EBADF	no such CSAP
TE_EINPROGRESS	operation is already in progress
TE_EBUSY	CSAP is used for receiving now
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

See also:

rcf_ta_trsend_stop

te_errno rcf_ta_trsend_stop(const char* ta_name, int session, csap_handle_t csap_id, int* num)

This function is used to stop sending of traffic started by rcf_ta_trsend_start called in non-blocking mode.

Parameters:

ta_name	Test Agent name
session	session identifier
csap_id	CSAP handle
num	location where number of sent packets should be placed
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_EIPC	cannot interact with RCF
TE_EBADF	no such CSAP
TE_EALREADY	traffic sending is not in progress now
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

See also:

rcf_ta_trsend_start

te_errno rcf_ta_trrecv_start(const char* ta_name, int session, csap_handle_t csap_id, const char* pattern, unsigned int timeout, unsigned int num, unsigned int mode)

This function is used to force receiving of traffic via already created CSAP.

Parameters:

ta_name	Test Agent name
session	TA session or 0
csap_id	CSAP handle
pattern	Full name of the file with traffic pattern
timeout	Timeout (in milliseconds) for traffic receive operation. After this time interval CSAP stops capturing any traffic on the agent and will be waiting until rcf_ta_trrecv_stop() or rcf_ta_trrecv_wait() are called
num	Number of packets that needs to be captured; if it is zero, the number of received packets is not limited
mode	The flags allows to specify the receive mode. Count received packets only, store packets to get to the test side later or use pattern sequence matching.
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_EIPC	cannot interact with RCF
TE_EBADF	no such CSAP
TE_EINPROGRESS	operation is already in progress
TE_EBUSY	CSAP is used for sending now
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	not enough memory in the system
other	error returned by command handler on the TA

Returns:

error code

See also:

rcf_ta_trrecv_stop rcf_ta_trrecv_wait

te_errno rcf_ta_trrecv_wait(const char* ta_name, int session, csap_handle_t csap_id, rcf_pkt_handler handler, void* user_param, unsigned int* num)

Blocks the caller until all the traffic, which is being captured, is received by the CSAP or timeout occurred (timeout specified with rcf_ta_trrecv_start()). If handler is specified, it is called for all received packets. This function can only be called after rcf_ta_trrecv_start().

Parameters:

ta_name	Test Agent name
session	Session identifier
csap_id	CSAP handle
handler	Address of function to be used to process received packets or NULL
user_param	User parameter to be passed to the handler
num	Number of received packets (OUT)
0	success
TE_ETIMEDOUT	timeout occurred before all the requested traffic received - this means that TAD has captured less than the number of packets specified with rcf_ta_trrecv_start. Nevertheless, number of captured packets is set to “num” parameter.

Returns:

error code

See also:

rcf_ta_trrecv_start

te_errno rcf_ta_trrecv_stop(const char* ta_name, int session, csap_handle_t csap_id, rcf_pkt_handler handler, void* user_param, unsigned int* num)

This function is used to stop receiving of traffic started by rcf_ta_trrecv_start. If handler is specified, it is called for all received packets.

Parameters:

ta_name	Test Agent name
session	Session identifier
csap_id	CSAP handle
handler	Address of function to be used to process received packets or NULL
user_param	User parameter to be passed to the handler
num	Location where number of received packets should be placed (OUT)
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_EIPC	cannot interact with RCF
TE_EBADF	no such CSAP
TE_EALREADY	traffic receiving is not in progress now
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

See also:

rcf_ta_trrecv_start

te_errno rcf_ta_trrecv_get(const char* ta_name, int session, csap_handle_t csap_id, rcf_pkt_handler handler, void* user_param, unsigned int* num)

This function is used to force processing of received packets without stopping of traffic receiving. If handler is specified, it is called for all received packets.

Parameters:

ta_name	Test Agent name
session	Session identifier
csap_id	CSAP handle
handler	Address of function to be used to process received packets or NULL
user_param	User parameter to be passed to the handler
num	Location where number of processed packets should be placed
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_EIPC	cannot interact with RCF
TE_EBADF	no such CSAP
TE_EALREADY	traffic receiving is not in progress now
TE_ENODATA	no data available on TA, because handler was not specified in rcf_ta_trrecv_start
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

See also:

rcf_ta_trrecv_start

te_errno rcf_ta_trsend_recv(const char* ta_name, int session, csap_handle_t csap_id, const char* templ, rcf_pkt_handler handler, void* user_param, unsigned int timeout, int* error)

This function is used to send exactly one packet via CSAP and receive an answer (it may be used for CLI, SNMP, ARP, ICMP, DNS, etc.) This function blocks the caller until the packet is received by traffic application domain or timeout occurred.

Parameters:

ta_name	Test Agent name
session	TA session or 0
csap_id	CSAP handle
templ	Full name of the file with traffic template
handler	Callback function used in processing of received packet or NULL
user_param	User parameter to be passed to the handler
timeout	Timeout for answer waiting (in milliseconds)
error	Location for protocol-specific error extracted from the answer or NULL (if error is 0, then answer is positive; if error is -1, then it’s not possible to extract the error)
0	success
TE_ETIMEDOUT	timeout occurred before a packet that matches the template received
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided or flag blocking is used together with num 0
TE_EIPC	cannot interact with RCF
TE_EBADF	no such CSAP
TE_EBUSY	CSAP is busy
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory
other	error returned by command handler on the TA

Returns:

error code

te_errno rcf_trpoll(rcf_trpoll_csap* csaps, unsigned int n_csaps, unsigned int timeout)

Wait for completion of send and/or receive operation on one of CSAPs.

If csap_id in rcf_trpoll_csap structure is CSAP_INVALID_HANDLE, the entry is ignored (does not cause break of timeout) and TE_ETADCSAPNOTEX is returned in status.

status in rcf_trpoll_csap structure contains status code of the request to Test Agent. The following values are expected:

TE_ETADCSAPNOTEX - CSAP does not exist;
TE_ETADCSAPSTATE - CSAP is idle, no send and/or receive operations have been executed;
TE_ETIMEDOUT - send or receive operation is in progress and it has not finished until timeout or completion of another request;
0 - send or receive operation has been finished.

Parameters:

csaps	Array with CSAPs to be polled
n_csaps	Number of entries in csaps array
timeout	Timeout (in milliseconds) to wait for send or receive processing (may be TAD_TIMEOUT_INF)
0	One of requests has been finished before timeout
TE_ETIMEDOUT	Requests to all CSAPs are timed out

Returns:

Status code.

te_errno rcf_ta_call(const char* ta_name, int session, const char* rtn, int* error, int argc, bool argv, ...)

This function is used to call remotely a routine on the Test Agent or NUT served by it.

Usage example:

rcf_ta_call("loki.oktetlabs.ru", 25, "foo_rtn", &rc, 3, true,
            str, "foo", "bar");
rcf_ta_call("thor", 13, "bar_rtn", &rc, 3, false,
            RCF_INT8, 7, RCF_STRING, "foo", RCF_STRING, arg)

Parameters:

ta_name	Test Agent name
session	TA session or 0
rtn	routine name
error	location for the code returned by the routine
argc	number of parameters
argv	if `true`, rest of parameters are char *; otherwise pairs: type, value.
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_ENOENT	no such routine
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

te_errno rcf_ta_start_task(const char* ta_name, int session, int priority, const char* rtn, pid_t* pid, int argc, bool argv, ...)

This function is used to start a process on the Test Agent or NUT served by it.

Usage example:

rcf_ta_start_task("loki.oktetlabs.ru", 25, HIGH_PRIORITY,
                  "foo_entry_pont", &pid, 3, true,
                  str, "foo", "bar");
rcf_ta_start_task("thor", 13, LOW_PRIORITY, "bar_entry_point",
                  &pid, 3, false,
                  RCF_INT8, 7, RCF_STRING, "foo", RCF_STRING, arg)

Parameters:

ta_name	Test Agent name
session	TA session or 0
priority	priority of the new process
rtn	routine name (task entry point)
pid	location for process identifier
argc	number of parameters
argv	if `true`, rest of parameters are char *; otherwise pairs: type, value.
0	success
TE_EINVAL	name of non-running TN Test Agent or non-existent session identifier is provided
TE_ENOENT	no such routine
TE_EIPC	cannot interact with RCF
TE_ETAREBOOTED	Test Agent is rebooted
TE_ENOMEM	out of memory

Returns:

error code

See also:

rcf_ta_kill_process

te_errno rcf_ta_start_thread(const char* ta_name, int session, int priority, const char* rtn, int* tid, int argc, bool argv, ...)

This function is similar to rcf_ta_start_task, but the task should be started as a separate thread, not a process

See also:

rcf_ta_start_task

te_errno rcf_ta_kill_task(const char* ta_name, int session, pid_t pid)

This function is used to kill a process on the Test Agent or NUT served by it.

Parameters:

ta_name	Test Agent name
session	TA session or 0
pid	identifier of the process to be killed

Returns:

Status code

te_errno rcf_ta_kill_thread(const char* ta_name, int session, int tid)

This function is used to kill a thread on the Test Agent or NUT served by it.

Parameters:

ta_name	Test Agent name
session	TA session or 0
tid	identifier of the thread to be killed

Returns:

Status code

te_errno rcf_ta_call_rpc(const char* ta_name, int session, const char* rpcserver, int timeout, const char* rpc_name, void* in, void* out)

Call SUN RPC on the TA.

Parameters:

ta_name	Test Agent name
session	TA session or 0
rpcserver	Name of the RPC server
timeout	RPC timeout in milliseconds or 0 (unlimited)
rpc_name	Name of the RPC (e.g. “bind”)
in	Input parameter C structure
out	Output parameter C structure

Returns:

Status code

te_errno rcf_check_agent(const char* ta_name)

Check that given agent is still working.

Parameters:

ta_name	Test Agent name
0	success
TE_ETAREBOOTED	if the test agent has been normally rebooted
TE_ETADEAD	if the agent was dead
TE_EIPC	cannot interact with RCF

Returns:

error code

te_errno rcf_check_agents(void)

Check that all running agents are still working.

Parameters:

0	success
TE_ETAREBOOTED	if at least one test agent has been normally rebooted
TE_ETADEAD	if at least one agent was dead
TE_EIPC	cannot interact with RCF

Returns:

error code

te_errno rcf_shutdown_call(void)

This function is used to shutdown the RCF.

Returns:

error code

void rcf_api_cleanup(void)

Clean up resources allocated by RCF API. This routine should be called from each thread used RCF API.

Usually user should not worry about calling of the function, since it is called automatically using atexit() or similar mechanism.

te_errno rcf_foreach_ta(rcf_ta_cb* cb, void* cookie)

Execute callback for each Test Agent

Parameters:

cb	Callback function
cookie	Callback opaque data

Returns:

Status code.

te_errno rcf_get_dead_agents(te_vec* dead_agents)

Get vector of the dead agents.

Parameters:

dead_agents

Vector of the dead agents

Returns:

Status code

Macros

#define RCF_SERVER

IPC RCF Server name

#define RCF_TRRECV_REPORT_MASK

Bit mask for report flag of receiving mode