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(te_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, te_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, te_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(te_bool ring);
te_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, te_bool argv, ...);
te_errno rcf_ta_start_task(const char* ta_name, int session, int priority, const char* rtn, pid_t* pid, int argc, te_bool argv, ...);
te_errno rcf_ta_start_thread(const char* ta_name, int session, int priority, const char* rtn, int* tid, int argc, te_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(te_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, te_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, te_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(te_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.

te_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, te_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, te_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, te_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