SNMP

Overview

Traffic Application Domain Command Handler SNMP protocol implementaion internal declarations. More…

// typedefs

typedef enum tapi_snmp_version_t tapi_snmp_version_t;
typedef enum tapi_snmp_sec_model_t tapi_snmp_sec_model_t;
typedef enum tapi_snmp_sec_level_t tapi_snmp_sec_level_t;
typedef enum tapi_snmp_auth_proto_t tapi_snmp_auth_proto_t;
typedef enum tapi_snmp_priv_proto_t tapi_snmp_priv_proto_t;
typedef enum tapi_snmp_vartypes_t tapi_snmp_vartypes_t;
typedef enum tapi_snmp_gen_trap_t tapi_snmp_gen_trap_t;
typedef enum tapi_snmp_mib_access tapi_snmp_mib_access;
typedef enum tapi_snmp_mib_status tapi_snmp_mib_status;
typedef struct tapi_snmp_var_access tapi_snmp_var_access;
typedef enum tapi_snmp_truth_value tapi_snmp_truth_value;
typedef struct tapi_snmp_common_table_row_s tapi_snmp_common_table_row_t;
typedef struct tapi_snmp_security_s tapi_snmp_security_t;

typedef int (*walk_callback)(
    const tapi_snmp_varbind_t *varbind,
    void *userdata
    );

typedef void (*tapi_snmp_trap_callback)(
    const tapi_snmp_message_t *trap,
    void *user_data
    );

typedef struct tapi_snmp_pkt_handler_data tapi_snmp_pkt_handler_data;

// enums

enum snmp_obj_type;
enum tapi_snmp_auth_proto_t;
enum tapi_snmp_gen_trap_t;
enum tapi_snmp_get_type_t;
enum tapi_snmp_mib_access;
enum tapi_snmp_mib_status;
enum tapi_snmp_priv_proto_t;
enum tapi_snmp_sec_level_t;
enum tapi_snmp_sec_model_t;
enum tapi_snmp_truth_value;
enum tapi_snmp_vartypes_t;
enum tapi_snmp_vb_cmp_type;
enum tapi_snmp_version_t;

// structs

struct tapi_snmp_common_table_row_s;
struct tapi_snmp_message_t;
struct tapi_snmp_oct_string_t;
struct tapi_snmp_oid_t;
struct tapi_snmp_pkt_handler_data;
struct tapi_snmp_security_s;
struct tapi_snmp_v1_gen_trap_name;
struct tapi_snmp_var_access;
struct tapi_snmp_varbind_t;

// global functions

int tapi_snmp_cat_oid(tapi_snmp_oid_t* base, const tapi_snmp_oid_t* suffix);
int tapi_snmp_is_sub_oid(const tapi_snmp_oid_t* tree, const tapi_snmp_oid_t* node);
void tapi_snmp_free_varbind(tapi_snmp_varbind_t* varbind);
void tapi_snmp_free_message(tapi_snmp_message_t* snmp_message);
tapi_snmp_oct_string_t* tapi_snmp_mk_oct_string(uint8_t* data, size_t data_len);
void tapi_snmp_free_oct_string(tapi_snmp_oct_string_t* oct_string);
int tapi_snmp_packet_to_plain(asn_value* pkt, tapi_snmp_message_t* snmp_message);
te_errno tapi_snmp_csap_create(const char* ta, int sid, const char* snmp_agent, const char* community, tapi_snmp_version_t snmp_version, csap_handle_t* csap_id);
te_errno tapi_snmp_gen_csap_create(const char* ta, int sid, const char* snmp_agent, tapi_snmp_security_t* security, tapi_snmp_version_t snmp_version, uint16_t rem_port, uint16_t loc_port, int timeout, csap_handle_t* csap_id);
int tapi_snmp_set_vbs(const char* ta, int sid, int csap_id, const tapi_snmp_varbind_t* var_binds, size_t num_vars, int* errstat, int* errindex);
int tapi_snmp_set(const char* ta, int sid, int csap_id, int* errstat, int* errindex, ...);
int tapi_snmp_set_row(const char* ta, int sid, int csap_id, int* errstat, int* errindex, const tapi_snmp_oid_t* common_index, ...);
int tapi_snmp_get_row(const char* ta, int sid, int csap_id, int* errstatus, int* errindex, const tapi_snmp_oid_t* common_index, ...);
int tapi_snmp_set_integer(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, int value, int* errstat);
int tapi_snmp_set_unsigned(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, unsigned int value, int* errstat);
int tapi_snmp_set_octetstring(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, const uint8_t* value, size_t size, int* errstat);
int tapi_snmp_set_string(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, const char* value, int* errstat);
int tapi_snmp_get(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, tapi_snmp_get_type_t next, tapi_snmp_varbind_t* varbind, int* errstatus);
int tapi_snmp_getbulk(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* v_oid, int* num, tapi_snmp_varbind_t* varbind, int* errstatus);
int tapi_snmp_walk(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, void* userdata, walk_callback callback);
int tapi_snmp_get_ipaddr(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, void* addr, int* errstat);
int tapi_snmp_get_date_and_time(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, time_t* val, int* offset_from_utc, int* errstat);
int tapi_snmp_get_integer(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, int* val, int* errstat);
static unsigned int tapi_snmp_get_unsigned(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, unsigned int* val, int* errstat);
int tapi_snmp_get_string(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, char* buf, size_t buf_size, int* errstat);
int tapi_snmp_get_oct_string(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, void* buf, size_t* buf_size, int* errstat);
int tapi_snmp_get_objid(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, tapi_snmp_oid_t* ret_oid, int* errstat);
int tapi_snmp_get_table(const char* ta, int sid, int csap_id, tapi_snmp_oid_t* table_oid, int* num, void** result);
int tapi_snmp_get_table_rows(const char* ta, int sid, int csap_id, tapi_snmp_oid_t* table_entry, int num, tapi_snmp_oid_t* suffix, void** result);
int tapi_snmp_get_table_dimension(tapi_snmp_oid_t* table_oid, int* dimension);
int tapi_snmp_make_table_index(tapi_snmp_oid_t* tbl, tapi_snmp_oid_t* index, ...);
int tapi_snmp_get_table_columns(tapi_snmp_oid_t* table_oid, tapi_snmp_var_access** columns);
int tapi_snmp_load_mib_with_path(const char* dir_path, const char* mib_file);
int tapi_snmp_load_cfg_mibs(const char* dir_path);
static void tapi_snmp_zero_oid(tapi_snmp_oid_t* oid);
void tapi_snmp_append_oid(tapi_snmp_oid_t* oid, int n, ...);
int tapi_snmp_make_oid(const char* oid_str, tapi_snmp_oid_t* oid);
int tapi_snmp_find_vb(const tapi_snmp_varbind_t* var_binds, size_t num, const tapi_snmp_oid_t* oid, const tapi_snmp_varbind_t** vb, size_t* pos);
static int tapi_snmp_find_vb_str(const tapi_snmp_varbind_t* var_binds, size_t num, const char* oid, const tapi_snmp_varbind_t** vb, size_t* pos);
int tapi_snmp_get_syntax(tapi_snmp_oid_t* oid, tapi_snmp_vartypes_t* syntax);
void tapi_snmp_trap_handler(const char* fn, void* user_param);
int tapi_snmp_make_instance(const char* oid_str, tapi_snmp_oid_t* oid, ...);
int tapi_snmp_make_vb(tapi_snmp_varbind_t* vb, const char* oid_str, const char* type, const char* value, ...);
int tapi_snmp_cmp_vb(const tapi_snmp_varbind_t* vb1, const tapi_snmp_varbind_t* vb2, tapi_snmp_vb_cmp_type cmp_type);
int tapi_snmp_cmp_oid(const tapi_snmp_oid_t* oid1, const tapi_snmp_oid_t* oid2);
const char* print_oid(const tapi_snmp_oid_t* oid);
const char* tapi_snmp_print_oct_str(const void* data, size_t len);
const char* snmp_error_h2str(int error_val);
const char* snmp_obj_type_h2str(enum snmp_obj_type obj_type);
const char* tapi_snmp_obj_status_h2str(enum tapi_snmp_mib_status obj_status);
const char* tapi_snmp_truth_value_h2str(enum tapi_snmp_truth_value val);
const char* tapi_snmp_val_type_h2str(enum tapi_snmp_vartypes_t type);
const char* tapi_snmp_gen_trap_h2str(enum tapi_snmp_gen_trap_t type);
tapi_snmp_gen_trap_t tapi_snmp_gen_trap_by_name(const char* trap_name);

// macros

#define MAX_LABLE_LEN
#define MAX_OID_LEN
#define TAPI_SNMP_TRAP_PORT
#define tapi_snmp_load_mib(mib_file_)

Detailed Documentation

Traffic Application Domain Command Handler SNMP protocol implementaion internal declarations.

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Typedefs

typedef enum tapi_snmp_version_t tapi_snmp_version_t

SNMP Protocol version

typedef enum tapi_snmp_sec_model_t tapi_snmp_sec_model_t

SNMP Security model

typedef enum tapi_snmp_sec_level_t tapi_snmp_sec_level_t

SNMPv3 USM Security Level

typedef enum tapi_snmp_auth_proto_t tapi_snmp_auth_proto_t

SNMPv3 USM Authentication protocol

typedef enum tapi_snmp_priv_proto_t tapi_snmp_priv_proto_t

SNMPv3 USM Privacy protocol

typedef enum tapi_snmp_vartypes_t tapi_snmp_vartypes_t

Type codes for SNMP variable binding values. Really SNMP uses some of ASN.1 codes. Not all possible codes are defined, only usually used and supported in TAD SNMP module.

typedef enum tapi_snmp_gen_trap_t tapi_snmp_gen_trap_t

The list of possible values of “GEN TRAP” field of SNMP V1 Trap.

typedef enum tapi_snmp_mib_access tapi_snmp_mib_access

Store mib access type

typedef enum tapi_snmp_mib_status tapi_snmp_mib_status

Store mib status

typedef struct tapi_snmp_var_access tapi_snmp_var_access

Structure to contain snmp variable mib access

typedef enum tapi_snmp_truth_value tapi_snmp_truth_value

Definitions of values for SNMP TruthValue type

typedef struct tapi_snmp_common_table_row_s tapi_snmp_common_table_row_t

Structure that contains generic part of all SNMP table rows - INDEX part of row. It could be useful when casting unknown type of table to get at least the value of the row index.

typedef struct tapi_snmp_security_s tapi_snmp_security_t

SNMP security parameters

typedef int (*walk_callback)(
    const tapi_snmp_varbind_t *varbind,
    void *userdata
    )

Callback function for the tapi_snmp_walk() routine, it is called for each variable in a walk subtree.

Parameters:

varbind	Variable binding, for which the callback function is called
userdata	Parameter, provided by the caller of tapi_snmp_walk()

typedef void (*tapi_snmp_trap_callback)(
    const tapi_snmp_message_t *trap,
    void *user_data
    )

Callback function for the catching of SNMP traps.

Parameters:

trap	SNMP message with trap.
user_data	Parameter, provided by the caller of tapi_snmp_walk().

typedef struct tapi_snmp_pkt_handler_data tapi_snmp_pkt_handler_data

FIXME

Global Functions

int tapi_snmp_cat_oid(tapi_snmp_oid_t* base, const tapi_snmp_oid_t* suffix)

Concatenate two object identifiers and put result into first one. Mainly intended for table indexes.

Parameters:

base	base OID, will contain result (IN/OUT).
suffix	second OID, to be added to the base.

Returns:

zero on success, otherwise error code.

int tapi_snmp_is_sub_oid(const tapi_snmp_oid_t* tree, const tapi_snmp_oid_t* node)

Boolean check is the first OID contained in second one.

Parameters:

tree	OID of MIB sub-tree.
node	OID of node to be checked on presence in sub-tree.
1	node is in tree
0	otherwise

void tapi_snmp_free_varbind(tapi_snmp_varbind_t* varbind)

Free memory allocated in snmp varbind structure

Parameters:

varbind

Varbind to be freed

Returns:

N/A

void tapi_snmp_free_message(tapi_snmp_message_t* snmp_message)

Free memory allocated in snmp message structure got from tapi_snmp_packet_to_plain function

Parameters:

snmp_message

converted structure

Returns:

N/A

tapi_snmp_oct_string_t* tapi_snmp_mk_oct_string(uint8_t* data, size_t data_len)

Allocate octet string data structure based on user specified data buffer.

Parameters:

data	buffer with data
data_len	size of data buffer

Returns:

Allocated octet sting data structure

void tapi_snmp_free_oct_string(tapi_snmp_oct_string_t* oct_string)

Free octet string allocated with tapi_snmp_mk_oct_string()

Parameters:

oct_string

octet string to free

Returns:

N/A

int tapi_snmp_packet_to_plain(asn_value* pkt, tapi_snmp_message_t* snmp_message)

Convert SNMP-Message ASN.1 value to plain C structure.

Parameters:

pkt	ASN.1 value of type SNMP-Message or Generic-PDU with choice “snmp”
snmp_message	Converted structure (OUT)

Returns:

Zero on success or error code.

te_errno tapi_snmp_csap_create(const char* ta, int sid, const char* snmp_agent, const char* community, tapi_snmp_version_t snmp_version, csap_handle_t* csap_id)

Creates usual SNMP (community-based security model) CSAP on specified Test Agent and got its handle.

Parameters:

ta	Test Agent name
sid	RCF Session ID
snmp_agent	Address of SNMP agent
community	SNMP community
snmp_version	SNMP version
csap_id	identifier of an SNMP CSAP (OUT)

Returns:

zero on success or error code.

te_errno tapi_snmp_gen_csap_create(const char* ta, int sid, const char* snmp_agent, tapi_snmp_security_t* security, tapi_snmp_version_t snmp_version, uint16_t rem_port, uint16_t loc_port, int timeout, csap_handle_t* csap_id)

Creates generic SNMP CSAP on specified Test Agent and got its handle.

Parameters:

ta	Test Agent name.
sid	RCF Session ID.
snmp_agent	Address of SNMP agent.
security	SNMP security parameters.
snmp_version	SNMP version.
rem_port	Remote UDP port.
loc_port	Local UDP port.
timeout	Default timeout, measured in milliseconds.
csap_id	identifier of an SNMP CSAP. (OUT)

Returns:

zero on success or error code.

int tapi_snmp_set_vbs(const char* ta, int sid, int csap_id, const tapi_snmp_varbind_t* var_binds, size_t num_vars, int* errstat, int* errindex)

The function send SNMP-SET request for specified objects to the SNMP agent, associated with a particular SNMP CSAP.

The function waits for SNMP agent response.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	identifier of an SNMP CSAP.
var_binds	Array with var-binds to be sent in request.
num_vars	Number of var-binds in array below.
errstat	Rhe value of error-status field in response message (OUT), may be zero if not need.
errindex	Rhe value of error-index field in response message (OUT), may be zero if not need.

Returns:

zero on success or error code.

int tapi_snmp_set(const char* ta, int sid, int csap_id, int* errstat, int* errindex, ...)

The same as tapi_snmp_set_vbs, but gets sequence of “varbind groups” from free arguments sequence after ‘errindex’.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	identifier of an SNMP CSAP.
errstat	The value of error-status field in response message (OUT), may be zero if not need.
errindex	The value of error-index field in response message (OUT), may be zero if not need.
…	Sequence of “varbind groups”: Symbolic label of MIB leaf (usually literal contant) and value, which may be either integer (for INTEGER syntax leafs), or tapi_snmp_oct_string_t* for OCTET_STRING types, or tapi_snmp_oid_t*; ended by NULL. Passed pointers are considered as ‘const’, i.e. OID and data are not changed.

Returns:

zero on success or error code.

int tapi_snmp_set_row(const char* ta, int sid, int csap_id, int* errstat, int* errindex, const tapi_snmp_oid_t* common_index, ...)

The function send SNMP-SET request for specified objects to the SNMP agent, associated with a particular SNMP CSAP.

The function waits for SNMP agent response.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	identifier of an SNMP CSAP.
errstat	The value of error-status field in response message (OUT), may be zero if not need.
errindex	The value of error-index field in response message (OUT), may be zero if not need.
common_index	Common index part of OID, which should be concatened to all varbind’s OIDs below; may be NULL.
…	Sequence of “varbind groups”: label of MIB leaf and value, which may be either integer, or tapi_snmp_oct_string_t*, for OCTET_STRING types, or tapi_snmp_oid_t*; ended by NULL. Passed pointers are considered as ‘const’, i.e. OID and data are not changed.

Returns:

zero on success or error code.

int tapi_snmp_get_row(const char* ta, int sid, int csap_id, int* errstatus, int* errindex, const tapi_snmp_oid_t* common_index, ...)

The function send SNMP-GET request for specified objects to the SNMP agent, associated with a particular SNMP CSAP. Note, that the function waits for SNMP agent response.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	identifier of an SNMP CSAP.
errstatus	The value of error-status field in response message (OUT), may be zero if not need.
errindex	The value of error-index field in response message (OUT), may be zero if not need.
common_index	Common index part of OID, which should be concatened to all varbind’s OIDs below; may be NULL.
…	Sequence of “varbind groups”: label of MIB leaf and value, which may be either integer, or tapi_snmp_oct_string_t*, for OCTET_STRING types, or tapi_snmp_oid_t*; ended by NULL. Passed pointers are desired as ‘const’, i.e. OID and data are not changed.

Returns:

zero on success or error code.

int tapi_snmp_set_integer(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, int value, int* errstat)

The function makes an attempt to set an integer value for an SNMP object by means of SNMP Set request, which is sent to the SNMP agent, associated with a particular SNMP CSAP. Note, that the function waits for SNMP agent response.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	identifier of an SNMP CSAP.
oid	ID of an SNMP object the value is to be set.
value	integer value.
errstat	the value of error-status field in response message (OUT), may be zero if not need.

Returns:

zero on success or error code.

int tapi_snmp_set_unsigned(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, unsigned int value, int* errstat)

The function makes an attempt to set an unsigned integer value for an SNMP object by means of SNMP Set request, which is sent to the SNMP agent, associated with a particular SNMP CSAP. Note, that the function waits for SNMP agent response.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	identifier of an SNMP CSAP.
oid	ID of an SNMP object the value is to be set.
value	unsigned integer value.
errstat	the value of error-status field in response message (OUT), may be zero if not need.

Returns:

zero on success or error code.

int tapi_snmp_set_octetstring(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, const uint8_t* value, size_t size, int* errstat)

The function makes an attempt to set an octet string value for an SNMP object by means of SNMP Set request, which is sent to the SNMP agent, associated with an SNMP CSAP. Note, that the function waits for SNMP agent response.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	identifier of an SNMP CSAP.
oid	ID of an SNMP object the value is to be set.
value	octet string value.
size	octet string size.
errstat	the value of error-status field in response message (OUT), may be zero if not need.

Returns:

zero on success or error code.

int tapi_snmp_set_string(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, const char* value, int* errstat)

The function makes an attempt to set a string value for an SNMP object by means of SNMP Set request, which is sent to the SNMP agent, associated with an SNMP CSAP. Note, that the argument string should contain only printable characters. For a general octet string use tapi_snmp_set_octetstring() function. Note, that the function waits for SNMP agent response.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	identifier of an SNMP CSAP.
oid	ID of an SNMP object the value is to be set.
value	zero-terminated string.
errstat	the value of error-status field in response message (OUT), may be zero if not need.

Returns:

zero on success or error code.

int tapi_snmp_get(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, tapi_snmp_get_type_t next, tapi_snmp_varbind_t* varbind, int* errstatus)

The function can be used to send either SNMP Get request or SNMP GetNext request to the SNMP agent, associated with an SNMP CSAP, and obtain a variable binding agent have responded.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	Identifier of an SNMP CSAP.
oid	ID of an SNMP object.
next	The parameter defines which of the SNMP request should be send (GetRequest or GetNextRequest).
varbind	Location for variable binding, got SNMP agent for the given OID. Pointers in structure (for complex long data) are allocated by this method and should be freed by user. (OUT)
errstatus	The value of error-status field in response message (OUT), may be zero if not need.

Returns:

zero on success or error code.

int tapi_snmp_getbulk(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* v_oid, int* num, tapi_snmp_varbind_t* varbind, int* errstatus)

The function can be used to send either SNMP Get-Bulk request to the SNMP agent, associated with an SNMP CSAP, and obtain a variable binding agent have responded.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	Identifier of an SNMP CSAP
v_oid	ID of an SNMP object
num	Number of elements in ‘varbinds’ (IN/OUT)
varbind	Location for variable bindings, got SNMP agent for the given OID. Pointers in structures (for complex long data) are allocated by this method and should be freed by user. (OUT)
errstatus	The value of error-status field in response message (OUT), may be zero if not need

Returns:

Zero on success or error code.

int tapi_snmp_walk(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, void* userdata, walk_callback callback)

The function uses SNMP GetNext requests to query an agent for a tree of information. An object identifier specifies which portion of the object identifier space will be searched using GetNext requests. All variables in the subtree below the given OID are queried, and for every such variable a callback function is called.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	Identifier of an SNMP CSAP
oid	OID which defines a subtree to work with
userdata	Opaque data to be passed into the callback function
callback	Callback function, which is executed for each leaf

Returns:

Zero on success or error code.

int tapi_snmp_get_ipaddr(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, void* addr, int* errstat)

The following functions are useful wrappers Sends SNMP Get request on MIB object with type InetAddr to the SNMP agent, associated with an SNMP CSAP and obtains a value the agent have responded.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	SNMP CSAP handle
oid	ID of an SNMP object
addr	Location for returned IPv4 address (OUT) Buffer must be sizeof(struct in_addr) bytes long
errstat	The value of error-status field in response message (OUT), may be zero if not need

Returns:

zero on success or error code

int tapi_snmp_get_date_and_time(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, time_t* val, int* offset_from_utc, int* errstat)

Sends SNMP Get request on MIB object with type DateAndTime to the SNMP agent, associated with an SNMP CSAP and obtains a value the agent have responded.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	SNMP CSAP handle
oid	ID of an SNMP object
val	Location for returned time (OUT)
offset_from_utc	Location for signed offset from UTC octet in minutes (OUT)
errstat	The value of error-status field in response message (OUT), may be zero if not need

Returns:

zero on success or error code

int tapi_snmp_get_integer(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, int* val, int* errstat)

Sends SNMP Get request on MIB object with type Integer to the SNMP agent, associated with an SNMP CSAP and obtains a value the agent have responded.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	SNMP CSAP handle
oid	ID of an SNMP object
val	Location for returned value (OUT)
errstat	The value of error-status field in response message (OUT), may be zero if not need

Returns:

Zero on success or error code

static unsigned int tapi_snmp_get_unsigned(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, unsigned int* val, int* errstat)

Sends SNMP Get request on MIB object with type Unsigned (or Gauge) to the SNMP agent, associated with an SNMP CSAP and obtains a value the agent have responded.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	SNMP CSAP handle
oid	ID of an SNMP object
val	Location for returned value (OUT)
errstat	The value of error-status field in response message (OUT), may be zero if not need

Returns:

Zero on success or error code

int tapi_snmp_get_string(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, char* buf, size_t buf_size, int* errstat)

Sends SNMP Get request on MIB object with type DisplayString to the SNMP agent, associated with an SNMP CSAP and obtains a value the agent have responded.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	SNMP CSAP handle
oid	ID of an SNMP object
buf	Location for returned string (OUT)
buf_size	Number of bytes in ‘buf’
errstat	The value of error-status field in response message (OUT), may be zero if not need

Returns:

Zero on success or error code

int tapi_snmp_get_oct_string(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, void* buf, size_t* buf_size, int* errstat)

Sends SNMP Get request on MIB object with type OctetString to the SNMP agent, associated with an SNMP CSAP and obtains a value the agent have responded.

Parameters:

ta	Test Agent name
sid	RCF Session id.
csap_id	SNMP CSAP handle
oid	ID of an SNMP object
buf	Location for returned value (OUT)
buf_size	Number of bytes in ‘buf’ on input and the number of bytes actually written on output (IN/OUT)
errstat	The value of error-status field in response message (OUT), may be zero if not need

Returns:

Zero on success or error code

int tapi_snmp_get_objid(const char* ta, int sid, int csap_id, const tapi_snmp_oid_t* oid, tapi_snmp_oid_t* ret_oid, int* errstat)

Sends SNMP Get request on MIB object with type ObjectIdentifier to the SNMP agent, associated with an SNMP CSAP and obtains a value the agent have responded.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	SNMP CSAP handle
oid	ID of an SNMP object
ret_oid	Location for returned value (OUT)
errstat	The value of error-status field in response message (OUT), may be zero if not need

Returns:

Zero on success or error code

int tapi_snmp_get_table(const char* ta, int sid, int csap_id, tapi_snmp_oid_t* table_oid, int* num, void** result)

Get SNMP table or one column from it, depends on passed OID.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	SNMP CSAP handle
table_oid	OID of SNMP table Entry object, or one leaf in this entry
num	Number of raws in table = height of matrix below (OUT)
result	Pointer to the allocated matrix with results, if only one column should be get, matrix width is 1, otherwise matrix width is greatest subid of Table entry + 1. (OUT)

Returns:

Zero on success or error code

int tapi_snmp_get_table_rows(const char* ta, int sid, int csap_id, tapi_snmp_oid_t* table_entry, int num, tapi_snmp_oid_t* suffix, void** result)

Get SNMP table row, list of leafs will be got from parsed MIB tree. Operation is performed as single SNMP-GET with multiple OIDs for all table entries, and result is returned as SNMP message with varbind array.

Parameters:

ta	Test Agent name
sid	RCF session ID
csap_id	SNMP CSAP handle
table_entry	OID of SNMP table Entry MIB node
num	number of suffixes
suffix	Array with index suffixes of desired table rows
result	Pointer to the allocated matrix with results, matrix width is greatest subid of Table entry (OUT)

Returns:

Zero on success or error code

int tapi_snmp_get_table_dimension(tapi_snmp_oid_t* table_oid, int* dimension)

Get SNMP table dimension.

Parameters:

table_oid	OID of SNMP table Entry object, or one leaf in this entry
dimension	Table dimension (OUT)

Returns:

zero on success or error code

int tapi_snmp_make_table_index(tapi_snmp_oid_t* tbl, tapi_snmp_oid_t* index, ...)

Make table index.

Parameters:

tbl	Table OID
index	Table index pointer
…	Values to be inserted in index.id

Returns:

Zero on success or error code

int tapi_snmp_get_table_columns(tapi_snmp_oid_t* table_oid, tapi_snmp_var_access** columns)

Get SNMP table columns.

Parameters:

table_oid	OID of SNMP table Entry object, or one leaf in this entry
columns	Pointer to the allocated array of columns (OUT)

Returns:

Zero on success or error code

int tapi_snmp_load_mib_with_path(const char* dir_path, const char* mib_file)

Loads all text OIDs from MIB file

Parameters:

dir_path	Path to directory with MIB files
mib_file	File name of the MIB file

Returns:

Status of the operation

int tapi_snmp_load_cfg_mibs(const char* dir_path)

Load all mibs specified in cs.conf file in “/snmp/mibs/load” list.

Parameters:

dir_path

Path to directory where to search MIB files

Returns:

Status of the operation

static void tapi_snmp_zero_oid(tapi_snmp_oid_t* oid)

Initialize OID to zero length OID

Parameters:

oid	OID to initialize

void tapi_snmp_append_oid(tapi_snmp_oid_t* oid, int n, ...)

Append a set of SUB IDs to the OID

Parameters:

oid	OID to be appended
n	Number of SUB IDs to append
…	SUB IDs type of “int”

int tapi_snmp_make_oid(const char* oid_str, tapi_snmp_oid_t* oid)

Parses text representation of OID to TAPI SNMP OID data structure

Parameters:

oid_str	OID string representation
oid	Location for parsed OID (OUT)

Returns:

Status of the operation

int tapi_snmp_find_vb(const tapi_snmp_varbind_t* var_binds, size_t num, const tapi_snmp_oid_t* oid, const tapi_snmp_varbind_t** vb, size_t* pos)

Finds VarBind by name (OID) among the array of VarBinds.

Parameters:

var_binds	Pointer to the array of VarBinds
num	The number of entries in var_binds array
oid	VarBind name we are interested in
vb	Found VarBind
pos	Position of found VarBind in the list, can be NULL if does not matter
0	VarBind is found
TE_ENOENT	There is no required VarBind in the list

Returns:

Status of the operation

static int tapi_snmp_find_vb_str(const tapi_snmp_varbind_t* var_binds, size_t num, const char* oid, const tapi_snmp_varbind_t** vb, size_t* pos)

Finds VarBind by name (OID) among the array of VarBinds. Function is the same as tapi_snmp_find_vb, but only gets OID in string format rather than in tapi_snmp_oid_t.

int tapi_snmp_get_syntax(tapi_snmp_oid_t* oid, tapi_snmp_vartypes_t* syntax)

Get SNMP object syntax from MIB.

Parameters:

oid	OID of SNMP object
syntax	syntax of SNMP object (OUT)

Returns:

Status of the operation

void tapi_snmp_trap_handler(const char* fn, void* user_param)

FIXME

int tapi_snmp_make_instance(const char* oid_str, tapi_snmp_oid_t* oid, ...)

Parses text representation of OID to TAPI SNMP OID data structure then adds instance indexes to the TAPI SNMP OID data structure.

Parameters:

oid_str	OID string representation
oid	Location for parsed OID (OUT)
…	Indexes of table field instance

Returns:

Status of the operation

int tapi_snmp_make_vb(tapi_snmp_varbind_t* vb, const char* oid_str, const char* type, const char* value, ...)

Create VarBind for specified OID with the particular value.

Parameters:

vb	Pointer to VarBind data structure to be filled in by the function (OUT)
oid_str	OID string representation
type	Type of the value, can be one of the following: i INTEGER u UNSIGNED s STRING x HEX STRING d DECIMAL STRING n NULLOBJ o OBJID t TIMETICKS a IPADDRESS b BITS
value	VarBind value
…	For tabular objects, index of the entry - type tapi_snmp_oid_t

Returns:

Status of the operation

int tapi_snmp_cmp_vb(const tapi_snmp_varbind_t* vb1, const tapi_snmp_varbind_t* vb2, tapi_snmp_vb_cmp_type cmp_type)

Compare two VarBinds

Parameters:

vb1	First VarBind
vb2	Second VarBind
cmp_type	Type of comparision
0	The values are the same
-1	The values are different

Returns:

Result of comparision

int tapi_snmp_cmp_oid(const tapi_snmp_oid_t* oid1, const tapi_snmp_oid_t* oid2)

Compare two OIDs

Parameters:

oid1	First OID
oid2	Second OID

Returns:

Function return an integer less than, equal to, or greater than zero if oid1 is found, respectively, to be less than, to match, or be greater than oid2.

const char* print_oid(const tapi_snmp_oid_t* oid)

Print SNMP OID struct to string and return pointer to this string. Note, that buffer with string is static and behaviour of this function in multithread usage may be unpredictable.

Parameters:

oid	pointer to structure with OID to be printed.

Returns:

Pointer to buffer with printed OID.

const char* tapi_snmp_print_oct_str(const void* data, size_t len)

Print array of bytes to string and return pointer to this string. Note, that buffer with string is static and behaviour of this function in multithread usage may be unpredictable.

Parameters:

data	Pointer to the data to be printed
len	Number of bytes in data array

Returns:

Pointer to buffer with printed data.

const char* snmp_error_h2str(int error_val)

Convert SNMP ERROR constants to string format

const char* snmp_obj_type_h2str(enum snmp_obj_type obj_type)

Convert SNMP Object type constants to string format

const char* tapi_snmp_obj_status_h2str(enum tapi_snmp_mib_status obj_status)

Convert SNMP MIB Object status constants to string format

const char* tapi_snmp_truth_value_h2str(enum tapi_snmp_truth_value val)

Convert SNMP TruthValue constants to string format

const char* tapi_snmp_val_type_h2str(enum tapi_snmp_vartypes_t type)

Convert SNMP value types constants to string format

const char* tapi_snmp_gen_trap_h2str(enum tapi_snmp_gen_trap_t type)

Convert SNMP Trap type constants to string format

tapi_snmp_gen_trap_t tapi_snmp_gen_trap_by_name(const char* trap_name)

Get SNMPv1 generic trap id by its name

Parameters:

trap_name

Name of trap

Returns:

Trap ID for generic traps or TAPI_SNMP_TRAP_ENTERPRISESPECIFIC otherwise

Macros

#define MAX_LABLE_LEN

Maximum length of label

#define MAX_OID_LEN

Strongly restricted maximal length of Object Identifier - this value is not succeded for all MIBs which are under testing. Really, it seems that this length can be exceeded only for “string” table indixes. Maximum length of object identifier

#define TAPI_SNMP_TRAP_PORT

Default port for SNMP trap receiver application

#define tapi_snmp_load_mib(mib_file_)

The macro simplify usage of tapi_snmp_load_mib function with using only one argument instead of two. In the caller context SUITE_SRCDIR macro MUST be defined.