Generic TAD API

Overview

Definition of Test API for common Traffic Application Domain features. More…

// typedefs

typedef void (*tapi_tad_trrecv_cb)(
    asn_value *packet,
    void *user_data
    );

typedef struct tapi_tad_trrecv_cb_data tapi_tad_trrecv_cb_data;

// structs

struct tapi_tad_trrecv_cb_data;

// global functions

int tapi_csap_get_status(const char* ta_name, int ta_sid, csap_handle_t csap_id, tad_csap_status_t* status);
int tapi_csap_get_total_bytes(const char* ta_name, int ta_sid, csap_handle_t csap_id, unsigned long long int* p_bytes);
int tapi_csap_get_duration(const char* ta_name, int ta_sid, csap_handle_t csap_id, struct timeval* p_dur);
int tapi_csap_param_get_llint(const char* ta_name, int ta_sid, csap_handle_t csap_id, const char* param_name, int64_t* p_llint);
int tapi_csap_param_get_timestamp(const char* ta_name, int ta_sid, csap_handle_t csap_id, const char* param_name, struct timeval* p_timestamp);
int tapi_tad_csap_create(const char* ta_name, int session, const char* stack_id, const asn_value* csap_spec, csap_handle_t* handle);
te_errno tapi_tad_csap_destroy(const char* ta_name, int session, csap_handle_t handle);
int tapi_tad_trsend_start(const char* ta_name, int session, csap_handle_t csap, const asn_value* templ, rcf_call_mode_t blk_mode);
te_errno tapi_tad_trrecv_start(const char* ta_name, int session, csap_handle_t handle, const asn_value* pattern, unsigned int timeout, unsigned int num, unsigned int mode);
tapi_tad_trrecv_cb_data* tapi_tad_trrecv_make_cb_data(tapi_tad_trrecv_cb callback, void* user_data);
te_errno tapi_tad_trrecv_wait(const char* ta_name, int session, csap_handle_t handle, tapi_tad_trrecv_cb_data* cb_data, unsigned int* num);
te_errno tapi_tad_trrecv_stop(const char* ta_name, int session, csap_handle_t handle, tapi_tad_trrecv_cb_data* cb_data, unsigned int* num);
te_errno tapi_tad_trrecv_get(const char* ta_name, int session, csap_handle_t handle, tapi_tad_trrecv_cb_data* cb_data, unsigned int* num);
te_errno tapi_tad_trrecv_wait_pkts_exec_cb_get_num(const char* ta_name, int session, csap_handle_t handle, unsigned int nb_pkts, unsigned int timeout_max_ms, tapi_tad_trrecv_cb_data* cb_data, unsigned int* num);
te_errno tapi_tad_trrecv_wait_pkts_exec_cb(const char* ta_name, int session, csap_handle_t handle, unsigned int nb_pkts, unsigned int timeout_max_ms, tapi_tad_trrecv_cb_data* cb_data);
te_errno tapi_tad_trrecv_wait_pkts_get_num(const char* ta_name, int session, csap_handle_t handle, unsigned int nb_pkts, unsigned int timeout_max_ms, unsigned int* num);
te_errno tapi_tad_trrecv_wait_pkts(const char* ta_name, int session, csap_handle_t handle, unsigned int nb_pkts, unsigned int timeout_max_ms);
int tapi_tad_add_iterator_for(asn_value* templ, int begin, int end, int step);
int tapi_tad_add_iterator_ints(asn_value* templ, int* array, size_t length);
int tapi_tad_forward_all(const char* ta_name, int session, csap_handle_t csap_rcv, csap_handle_t csap_fwd, asn_value* pattern, unsigned int timeout, unsigned int* forwarded);
te_errno tapi_tad_socket_add_csap_layer(asn_value** csap_spec, int fd);
te_errno tapi_tad_csap_get_no_match_pkts(const char* ta_name, int session, csap_handle_t csap_id, unsigned int* val);
te_errno tapi_tad_csap_destroy_all(int session);
te_errno tapi_tad_get_pkt_rx_ts(asn_value* pkt, struct timeval* tv);

Detailed Documentation

Definition of Test API for common Traffic Application Domain features.

Typedefs

typedef void (*tapi_tad_trrecv_cb)(
    asn_value *packet,
    void *user_data
    )

Type for callback which will receive catched packets.

Parameters:

packet	ASN value with received packet
user_data	Pointer to opaque data, specified by user for his callback,

Returns:

none

typedef struct tapi_tad_trrecv_cb_data tapi_tad_trrecv_cb_data

Structure for with parameters for receiving packets

Global Functions

int tapi_csap_get_status(const char* ta_name, int ta_sid, csap_handle_t csap_id, tad_csap_status_t* status)

Get status parameter of CSAP.

Parameters:

ta_name	name of the Test Agent
ta_sid	session identifier to be used
csap_id	CSAP handle
status	location for status of csap (OUT)

Returns:

Status code.

int tapi_csap_get_total_bytes(const char* ta_name, int ta_sid, csap_handle_t csap_id, unsigned long long int* p_bytes)

Get total number of bytes parameter of CSAP.

Parameters:

ta_name	name of the Test Agent
ta_sid	session identifier to be used
csap_id	CSAP handle
p_bytes	location for total number of bytes (OUT)

Returns:

Status code.

int tapi_csap_get_duration(const char* ta_name, int ta_sid, csap_handle_t csap_id, struct timeval* p_dur)

Get duration of the last traffic receiving session on TA CSAP.

Returned value is calculated as difference between timestamp of the last packet and timestamp of the first packet.

Parameters:

ta_name	name of the Test Agent
ta_sid	session identifier to be used
csap_id	CSAP handle
p_dur	location for duration (OUT)

Returns:

Status code.

int tapi_csap_param_get_llint(const char* ta_name, int ta_sid, csap_handle_t csap_id, const char* param_name, int64_t* p_llint)

Get ‘long long int’ CSAP parameter from TA.

Parameters:

ta_name	name of the Test Agent
ta_sid	session identifier to be used
csap_id	CSAP handle
param_name	parameter name
p_llint	location for ‘long long int’

Returns:

Status code.

int tapi_csap_param_get_timestamp(const char* ta_name, int ta_sid, csap_handle_t csap_id, const char* param_name, struct timeval* p_timestamp)

Get timestamp CSAP parameter from TA in format “<sec>.<usec>”.

Parameters:

ta_name	name of the Test Agent
ta_sid	session identifier to be used
csap_id	CSAP handle
param_name	parameter name
p_timestamp	location for timestamp

Returns:

Status code.

int tapi_tad_csap_create(const char* ta_name, int session, const char* stack_id, const asn_value* csap_spec, csap_handle_t* handle)

Creates CSAP (communication service access point) on the Test Agent.

If stack_id is NULL, then it will be determined by csap_spec

Parameters:

ta_name	Test Agent name
session	TA session or 0
stack_id	protocol stack identifier or `NULL`
csap_spec	ASN value of type CSAP-spec
handle	location for unique CSAP handle

Returns:

zero on success or error code

te_errno tapi_tad_csap_destroy(const char* ta_name, int session, csap_handle_t handle)

Destroys CSAP (communication service access point) on the Test Agent.

In comparison with rcf_ta_csap_destroy() the function synchronizes /agent/csap subtree of the corresponding Test Agent.

Parameters:

ta_name	Test Agent name
session	TA session or 0
handle	CSAP handle

Returns:

Status code.

int tapi_tad_trsend_start(const char* ta_name, int session, csap_handle_t csap, const asn_value* templ, rcf_call_mode_t blk_mode)

This function is used to force sending of traffic via already created CSAP. Started sending process may be managed via standard function rcf_ta_*.

Parameters:

ta_name	Test Agent name
session	TA session or 0
csap	CSAP handle
templ	ASN value of type Traffic-Template
blk_mode	mode of the operation: in blocking mode it suspends the caller until sending of all the traffic finishes

Returns:

zero on success or error code

te_errno tapi_tad_trrecv_start(const char* ta_name, int session, csap_handle_t handle, const asn_value* pattern, unsigned int timeout, unsigned int num, unsigned int mode)

Start receiving of traffic via already created CSAP. Started receiving process may be managed via standard function rcf_ta_*.

Parameters:

ta_name	Test Agent name
session	TA session or 0
handle	CSAP handle
pattern	ASN value of type Traffic-Pattern
timeout	Timeout 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.

Returns:

Zero on success or error code

tapi_tad_trrecv_cb_data* tapi_tad_trrecv_make_cb_data(tapi_tad_trrecv_cb callback, void* user_data)

Standard method to make struct with parameters for receiving packet.

Parameters:

callback	User callback
user_data	Pointer to user data for it

Returns:

pointer to new instance of structure.

te_errno tapi_tad_trrecv_wait(const char* ta_name, int session, csap_handle_t handle, tapi_tad_trrecv_cb_data* cb_data, unsigned int* num)

Continue already started receiving process on CSAP. Blocks until reception is finished.

Parameters:

ta_name	Test Agent name
session	TA session or 0
handle	CSAP handle
cb_data	Struct with user-specified data for catching packets
num	Location for number of received packets

Returns:

status code

te_errno tapi_tad_trrecv_stop(const char* ta_name, int session, csap_handle_t handle, tapi_tad_trrecv_cb_data* cb_data, unsigned int* num)

Stops already started receiving process on CSAP.

Parameters:

ta_name	Test Agent name
session	TA session or 0
handle	CSAP handle
cb_data	Struct with user-specified data for catching packets
num	Location for number of received packets

Returns:

status code

te_errno tapi_tad_trrecv_get(const char* ta_name, int session, csap_handle_t handle, tapi_tad_trrecv_cb_data* cb_data, unsigned int* num)

Get received packets from already started receiving process on CSAP. Don’t block, don’t stop receiving process. Received packets are removed from CSAP cache, and will not be returned again, on _wait, _stop or _get calls.

Parameters:

ta_name	Test Agent name
session	TA session or 0
handle	CSAP handle
cb_data	Struct with user-specified data for catching packets
num	Location for number of received packets

Returns:

status code

te_errno tapi_tad_trrecv_wait_pkts_exec_cb_get_num(const char* ta_name, int session, csap_handle_t handle, unsigned int nb_pkts, unsigned int timeout_max_ms, tapi_tad_trrecv_cb_data* cb_data, unsigned int* num)

Wait for a certain amount of packets to be received and execute specified callback for each of them.

The key goal of the function is to avoid waiting for extra time when everything required is received, but let the network and driver to do its job (which takes some time and we’re ready to wait for it). It allows to speed up tests execution because it avoids unnecessary waiting when everything is received.

The function returns success even if target number of packets is not received or more packets is received. Caller is responsible for checking the number of received expected (returned by tapi_tad_trrecv_stop()) and, if applicable, unexpected (returned by tapi_tad_csap_get_no_match_pkts()) packets.

Parameters:

ta_name	Test Agent name
session	TA session or `0`
handle	CSAP handle
nb_pkts	Target number of packets to be received
timeout_max_ms	Timeout to wait for target number of packets
cb_data	Struct with user-specified data for catching packets
num	Number of actually received packets by this function

Returns:

status code

te_errno tapi_tad_trrecv_wait_pkts_exec_cb(const char* ta_name, int session, csap_handle_t handle, unsigned int nb_pkts, unsigned int timeout_max_ms, tapi_tad_trrecv_cb_data* cb_data)

Wrapper for tapi_tad_trrecv_wait_pkts_exec_cb_get_num() with unspecified storage for amount of received packets.

te_errno tapi_tad_trrecv_wait_pkts_get_num(const char* ta_name, int session, csap_handle_t handle, unsigned int nb_pkts, unsigned int timeout_max_ms, unsigned int* num)

Wrapper for tapi_tad_trrecv_wait_pkts_exec_cb_get_num() with unspecified per-packet callback data.

te_errno tapi_tad_trrecv_wait_pkts(const char* ta_name, int session, csap_handle_t handle, unsigned int nb_pkts, unsigned int timeout_max_ms)

Wrapper for tapi_tad_trrecv_wait_pkts_get_num() with unspecified storage for amount of received packets.

int tapi_tad_add_iterator_for(asn_value* templ, int begin, int end, int step)

Insert arithmetical progression iterator argument into Traffic-Template ASN value, at the end of iterator list. New iterator became most internal.

Parameters:

templ	ASN value of Traffic-Template type
begin	start of arithmetic progression
end	end of arithmetic progression
step	step of arithmetic progression

Returns:

status code

int tapi_tad_add_iterator_ints(asn_value* templ, int* array, size_t length)

Insert ‘enumeration’ iterator argument into Traffic-Template ASN value, at the end of iterator list. New iterator became most internal.

Parameters:

templ	ASN value of Traffic-Template type
array	pointer to array with enumerated values
length	length of array

Returns:

status code

int tapi_tad_forward_all(const char* ta_name, int session, csap_handle_t csap_rcv, csap_handle_t csap_fwd, asn_value* pattern, unsigned int timeout, unsigned int* forwarded)

Receive all data which currently are waiting for receive in specified CSAP and forward them into another CSAP, without passing via RCF to test.

Parameters:

ta_name	TA name
session	RCF session id
csap_rcv	identifier of receive CSAP
csap_fwd	identifier of CSAP which should obtain data
pattern	traffic Pattern to receive data
timeout	timeout to wait data, in milliseconds
forwarded	number of forwarded PDUs (OUT)

Returns:

status code

te_errno tapi_tad_socket_add_csap_layer(asn_value** csap_spec, int fd)

Add socket layer over existing file descriptor in CSAP specification.

Parameters:

csap_spec	Location of CSAP specification pointer.
fd	File descriptor to read/write data
Status	code.

te_errno tapi_tad_csap_get_no_match_pkts(const char* ta_name, int session, csap_handle_t csap_id, unsigned int* val)

Get number of unmatched packets using a parameter of CSAP.

Parameters:

ta_name	name of the Test Agent
session	session identifier to be used
csap_id	CSAP handle
val	location for number of unmatched packets (OUT)

Returns:

Status code.

te_errno tapi_tad_csap_destroy_all(int session)

Finalise all CSAP instances on all Test Agents using RCF.

The function will synchronise /agent/csap subtrees for all the agents.

Parameters:

session

RCF session ID

Returns:

Status code.

te_errno tapi_tad_get_pkt_rx_ts(asn_value* pkt, struct timeval* tv)

Get timestamp from a packet captured by CSAP.

Parameters:

pkt	Packet captured by CSAP (described in ASN).
tv	Where to save obtained timestamp.

Returns:

Status code.