oids.h File Reference

#include <epan/ftypes/ftypes.h>
#include <epan/prefs.h>
#include <epan/wmem_scopes.h>
#include "ws_symbol_export.h"

Go to the source code of this file.

Classes
struct	_oid_bit_t
	Maps a single bit offset within an OID value to a protocol tree field. More...
struct	_oid_bits_info_t
	Describes the full set of named bit fields within a BITS-syntax OID value. More...
struct	_oid_value_type_t
	Describes the value syntax and BER encoding of an OID leaf node. More...
struct	_oid_key_t
	Describes a single index key component used to identify rows in an OID-indexed table. More...
struct	_oid_info_t
	A node in the OID registry tree, representing one arc of an object identifier. More...

Macros
#define	BER_TAG_ANY   -1
#define	subid_t   uint32_t
#define	add_oid_debug_subtree(a, b)   ((void)0)

Typedefs
typedef struct _oid_bits_info_t	oid_bits_info_t
	Describes the full set of named bit fields within a BITS-syntax OID value.
typedef enum _oid_key_type_t	oid_key_type_t
	Encoding type of a key sub-identifier in an OID index.
typedef struct _oid_value_type_t	oid_value_type_t
	Describes the value syntax and BER encoding of an OID leaf node.
typedef enum _oid_kind_t	oid_kind_t
	Semantic role of an OID node within a MIB or SMI object hierarchy.
typedef struct _oid_key_t	oid_key_t
	Describes a single index key component used to identify rows in an OID-indexed table.
typedef struct _oid_info_t	oid_info_t
	A node in the OID registry tree, representing one arc of an object identifier.

Enumerations
enum	_oid_key_type_t {   OID_KEY_TYPE_WRONG , OID_KEY_TYPE_INTEGER , OID_KEY_TYPE_OID , OID_KEY_TYPE_STRING ,   OID_KEY_TYPE_BYTES , OID_KEY_TYPE_NSAP , OID_KEY_TYPE_IPADDR , OID_KEY_TYPE_IMPLIED_OID ,   OID_KEY_TYPE_IMPLIED_STRING , OID_KEY_TYPE_IMPLIED_BYTES , OID_KEY_TYPE_ETHER , OID_KEY_TYPE_DATE_AND_TIME }
	Encoding type of a key sub-identifier in an OID index. More...
enum	_oid_kind_t {   OID_KIND_UNKNOWN = 0 , OID_KIND_NODE , OID_KIND_SCALAR , OID_KIND_TABLE ,   OID_KIND_ROW , OID_KIND_COLUMN , OID_KIND_NOTIFICATION , OID_KIND_GROUP ,   OID_KIND_COMPLIANCE , OID_KIND_CAPABILITIES }
	Semantic role of an OID node within a MIB or SMI object hierarchy. More...

Functions
WS_DLL_PUBLIC void	oids_init (const char *app_env_var_prefix)
	Initialize OID resolution and register related preferences.
void	oid_pref_init (module_t *nameres)
	Initialize OID-related preferences.
WS_DLL_PUBLIC void	oids_cleanup (void)
	Clean up OID-related resources.
WS_DLL_PUBLIC unsigned	oid_subid2encoded (wmem_allocator_t *scope, unsigned len, uint32_t *subids, uint8_t **encoded_p)
	Return length of encoded buffer.
WS_DLL_PUBLIC unsigned	oid_string2encoded (wmem_allocator_t *scope, const char *oid_str, uint8_t **encoded_p)
	Return length of encoded buffer.
WS_DLL_PUBLIC unsigned	oid_encoded2subid (wmem_allocator_t *scope, const uint8_t *oid, int len, uint32_t **subids_p)
	Return the number of sub-identifiers in a decoded OID.
WS_DLL_PUBLIC unsigned	oid_encoded2subid_sub (wmem_allocator_t *scope, const uint8_t *oid_bytes, int oid_len, uint32_t **subids_pi, bool is_first)
	Return the number of sub-identifiers in a decoded OID, with support for partial (sub-) OID decoding.
WS_DLL_PUBLIC unsigned	oid_string2subid (wmem_allocator_t *scope, const char *oid_str, uint32_t **subids_p)
	Return the number of sub-identifiers in a decoded OID string.
WS_DLL_PUBLIC char *	oid_encoded2string (wmem_allocator_t *scope, const uint8_t *encoded, unsigned len)
	Return the string representation of an encoded OID.
WS_DLL_PUBLIC char *	rel_oid_encoded2string (wmem_allocator_t *scope, const uint8_t *encoded, unsigned len)
	Return the string representation of an encoded relative OID.
WS_DLL_PUBLIC char *	oid_subid2string (wmem_allocator_t *scope, uint32_t *subids, unsigned len)
	Convert a sequence of OID sub-identifiers to a human-readable string.
WS_DLL_PUBLIC char *	rel_oid_subid2string (wmem_allocator_t *scope, uint32_t *subids, unsigned len, bool is_absolute)
	Convert a sequence of OID subidentifiers to a human-readable string.
WS_DLL_PUBLIC char *	oid_resolved (wmem_allocator_t *scope, unsigned len, uint32_t *subids)
	Resolve an OID to its human-readable name.
WS_DLL_PUBLIC char *	oid_resolved_from_encoded (wmem_allocator_t *scope, const uint8_t *oid, int len)
	Resolve an OID from its encoded form.
WS_DLL_PUBLIC char *	rel_oid_resolved_from_encoded (wmem_allocator_t *scope, const uint8_t *oid, int len)
	Resolve an OID from its encoded form.
WS_DLL_PUBLIC char *	oid_resolved_from_string (wmem_allocator_t *scope, const char *oid_str)
	Resolves an OID string to its resolved form.
WS_DLL_PUBLIC void	oid_both (wmem_allocator_t *scope, unsigned oid_len, uint32_t *subids, char **resolved_p, char **numeric_p)
	Resolve and convert an OID to both resolved and numeric representations.
WS_DLL_PUBLIC void	oid_both_from_encoded (wmem_allocator_t *scope, const uint8_t *oid, int oid_len, char **resolved_p, char **numeric_p)
	Resolve and convert an OID from its encoded form to both resolved and numeric representations.
WS_DLL_PUBLIC void	oid_both_from_string (wmem_allocator_t *scope, const char *oid_str, char **resolved_p, char **numeric_p)
	Resolve and convert an OID from its string representation to both resolved and numeric forms.
WS_DLL_PUBLIC oid_info_t *	oid_get (unsigned oid_len, uint32_t *subids, unsigned *matched_p, unsigned *left_p)
	Retrieves an OID information structure from its encoded form.
WS_DLL_PUBLIC oid_info_t *	oid_get_from_encoded (wmem_allocator_t *scope, const uint8_t *oid, int oid_len, uint32_t **subids, unsigned *matched, unsigned *left)
	Retrieves an OID information structure from its encoded form.
WS_DLL_PUBLIC oid_info_t *	oid_get_from_string (wmem_allocator_t *scope, const char *oid_str, uint32_t **subids, unsigned *matched, unsigned *left)
	Retrieves an OID information structure from a string representation.
WS_DLL_PUBLIC void	oid_add (const char *name, unsigned oid_len, uint32_t *subids)
	Add an OID to the OID database.
WS_DLL_PUBLIC void	oid_add_from_encoded (const char *name, const uint8_t *oid, int oid_len)
	Add an OID to the OID database from an encoded buffer.
WS_DLL_PUBLIC void	oid_add_from_string (const char *name, const char *oid_str)
	Add an OID to the OID database from a string.
WS_DLL_PUBLIC char *	oid_get_default_mib_path (const char *app_env_var_prefix)
	Fetch the default MIB/PIB path.

Enumeration Type Documentation

_oid_key_type_t

enum _oid_key_type_t

Encoding type of a key sub-identifier in an OID index.

Enumerator
OID_KEY_TYPE_WRONG	Invalid or unrecognized key type
OID_KEY_TYPE_INTEGER	Key is encoded as a single integer sub-identifier
OID_KEY_TYPE_OID	Key is a fixed-length OID sub-identifier sequence
OID_KEY_TYPE_STRING	Key is a fixed-length octet string
OID_KEY_TYPE_BYTES	Key is a fixed-length byte array
OID_KEY_TYPE_NSAP	Key is an NSAP (Network Service Access Point) address
OID_KEY_TYPE_IPADDR	Key is a 4-byte IPv4 address
OID_KEY_TYPE_IMPLIED_OID	Key is an implied-length OID (no leading length sub-id)
OID_KEY_TYPE_IMPLIED_STRING	Key is an implied-length octet string
OID_KEY_TYPE_IMPLIED_BYTES	Key is an implied-length byte array
OID_KEY_TYPE_ETHER	Key is a 6-byte IEEE 802 MAC address
OID_KEY_TYPE_DATE_AND_TIME	Key is an SNMPv2 DateAndTime octet string

_oid_kind_t

enum _oid_kind_t

Semantic role of an OID node within a MIB or SMI object hierarchy.

Enumerator
OID_KIND_UNKNOWN	Kind has not been determined or is unrecognized
OID_KIND_NODE	Interior node with no directly associated object
OID_KIND_SCALAR	Scalar MIB object (single instance)
OID_KIND_TABLE	SEQUENCE OF table object
OID_KIND_ROW	Table row (SEQUENCE) object
OID_KIND_COLUMN	Table column object
OID_KIND_NOTIFICATION	NOTIFICATION-TYPE object
OID_KIND_GROUP	OBJECT-GROUP or NOTIFICATION-GROUP
OID_KIND_COMPLIANCE	MODULE-COMPLIANCE object
OID_KIND_CAPABILITIES	AGENT-CAPABILITIES object

Function Documentation

oid_add()

WS_DLL_PUBLIC void oid_add	(	const char *	name,
		unsigned	oid_len,
		uint32_t *	subids
	)

Add an OID to the OID database.

Parameters

name	The name to associate with the OID.
oid_len	The number of sub-identifiers in subids.
subids	The array of sub-identifiers.

oid_add_from_encoded()

WS_DLL_PUBLIC void oid_add_from_encoded	(	const char *	name,
		const uint8_t *	oid,
		int	oid_len
	)

Add an OID to the OID database from an encoded buffer.

Parameters

name	The name to associate with the OID.
oid	The encoded OID buffer.
oid_len	The length of the encoded buffer.

oid_add_from_string()

WS_DLL_PUBLIC void oid_add_from_string	(	const char *	name,
		const char *	oid_str
	)

Add an OID to the OID database from a string.

Parameters

name	The name to associate with the OID.
oid_str	The OID string.

oid_both()

WS_DLL_PUBLIC void oid_both	(	wmem_allocator_t *	scope,
		unsigned	oid_len,
		uint32_t *	subids,
		char **	resolved_p,
		char **	numeric_p
	)

Resolve and convert an OID to both resolved and numeric representations.

Parameters

scope	Memory allocator for allocating memory.
oid_len	Length of the OID subids array.
subids	Array of OID subidentifiers.
resolved_p	Pointer to store the resolved OID string.
numeric_p	Pointer to store the numeric OID representation.

oid_both_from_encoded()

WS_DLL_PUBLIC void oid_both_from_encoded	(	wmem_allocator_t *	scope,
		const uint8_t *	oid,
		int	oid_len,
		char **	resolved_p,
		char **	numeric_p
	)

Resolve and convert an OID from its encoded form to both resolved and numeric representations.

Parameters

scope	Memory allocator for allocating memory.
oid	Encoded OID data.
oid_len	Length of the encoded OID data.
resolved_p	Pointer to store the resolved OID string.
numeric_p	Pointer to store the numeric OID representation.

oid_both_from_string()

WS_DLL_PUBLIC void oid_both_from_string	(	wmem_allocator_t *	scope,
		const char *	oid_str,
		char **	resolved_p,
		char **	numeric_p
	)

Resolve and convert an OID from its string representation to both resolved and numeric forms.

Parameters

scope	Memory allocator for allocating memory.
oid_str	The OID string to resolve and convert.
resolved_p	Pointer to store the resolved OID string.
numeric_p	Pointer to store the numeric OID representation.

oid_encoded2string()

WS_DLL_PUBLIC char * oid_encoded2string	(	wmem_allocator_t *	scope,
		const uint8_t *	encoded,
		unsigned	len
	)

Return the string representation of an encoded OID.

Parameters

scope	The memory allocator scope.
encoded	The encoded OID buffer.
len	The length of the encoded buffer.

Returns

The string representation of the OID.

oid_encoded2subid()

WS_DLL_PUBLIC unsigned oid_encoded2subid	(	wmem_allocator_t *	scope,
		const uint8_t *	oid,
		int	len,
		uint32_t **	subids_p
	)

Return the number of sub-identifiers in a decoded OID.

Parameters

scope	The memory allocator scope.
oid	The encoded OID buffer.
len	The length of the encoded buffer.
subids_p	Output pointer to the array of sub-identifiers.

Returns

The number of sub-identifiers in the decoded OID.

oid_encoded2subid_sub()

WS_DLL_PUBLIC unsigned oid_encoded2subid_sub	(	wmem_allocator_t *	scope,
		const uint8_t *	oid_bytes,
		int	oid_len,
		uint32_t **	subids_pi,
		bool	is_first
	)

Return the number of sub-identifiers in a decoded OID, with support for partial (sub-) OID decoding.

Parameters

scope	The memory allocator scope.
oid_bytes	The encoded OID buffer.
oid_len	The length of the encoded buffer.
subids_pi	Output pointer to the array of sub-identifiers.
is_first	Whether this is the first component of the OID.

Returns

The number of sub-identifiers in the decoded OID.

oid_get()

WS_DLL_PUBLIC oid_info_t * oid_get	(	unsigned	oid_len,
		uint32_t *	subids,
		unsigned *	matched_p,
		unsigned *	left_p
	)

Retrieves an OID information structure from its encoded form.

Parameters

oid_len	Length of the encoded OID data.
subids	Pointer to store the decoded sub-identifiers.
matched_p	Pointer to store the number of nodes used by the returned OID.
left_p	Pointer to store the number of remaining unresolved sub-identifiers.

Returns

oid_info_t* Pointer to the retrieved OID information structure or the root OID if no match is found.

oid_get_default_mib_path()

WS_DLL_PUBLIC char * oid_get_default_mib_path

(

const char *

app_env_var_prefix

)

Fetch the default MIB/PIB path.

Parameters

app_env_var_prefix

The prefix for environment variables related to OID resolution.

Returns

A string containing the default MIB/PIB path. It must be g_free()d by the caller.

oid_get_from_encoded()

WS_DLL_PUBLIC oid_info_t * oid_get_from_encoded	(	wmem_allocator_t *	scope,
		const uint8_t *	oid,
		int	oid_len,
		uint32_t **	subids,
		unsigned *	matched,
		unsigned *	left
	)

Retrieves an OID information structure from its encoded form.

Parameters

scope	Memory allocator scope for allocating the returned object.
oid	Encoded OID data.
oid_len	Length of the encoded OID data.
subids	Pointer to store the decoded sub-identifiers.
matched	Pointer to store the number of matched sub-identifiers.
left	Pointer to store the number of remaining sub-identifiers.

Returns

Pointer to the retrieved OID information structure, or NULL if not found.

oid_get_from_string()

WS_DLL_PUBLIC oid_info_t * oid_get_from_string	(	wmem_allocator_t *	scope,
		const char *	oid_str,
		uint32_t **	subids,
		unsigned *	matched,
		unsigned *	left
	)

Retrieves an OID information structure from a string representation.

Parameters

scope	Memory allocator scope for the returned oid_info_t structure.
oid_str	String representation of the OID to retrieve.
subids	Pointer to store the resulting sub-identifier array.
matched	Pointer to store the number of matched sub-identifiers.
left	Pointer to store the number of remaining sub-identifiers.

Returns

Pointer to the retrieved oid_info_t structure, or NULL if not found.

oid_pref_init()

void oid_pref_init ( module_t *  nameres )

extern

Initialize OID-related preferences.

Parameters

nameres

The module structure for name resolution.

oid_resolved()

WS_DLL_PUBLIC char * oid_resolved	(	wmem_allocator_t *	scope,
		unsigned	len,
		uint32_t *	subids
	)

Resolve an OID to its human-readable name.

Parameters

scope	Memory allocator for the returned string.
len	Length of the OID sub-identifier array.
subids	Array of OID sub-identifiers.

Returns

Human-readable name of the OID, or NULL if not found.

oid_resolved_from_encoded()

WS_DLL_PUBLIC char * oid_resolved_from_encoded	(	wmem_allocator_t *	scope,
		const uint8_t *	oid,
		int	len
	)

Resolve an OID from its encoded form.

Parameters

scope	Memory allocator for allocated memory.
oid	Encoded OID data.
len	Length of the encoded OID data.

Returns

Resolved OID as a string, or NULL if resolution fails.

oid_resolved_from_string()

WS_DLL_PUBLIC char * oid_resolved_from_string	(	wmem_allocator_t *	scope,
		const char *	oid_str
	)

Resolves an OID string to its resolved form.

Parameters

scope	Memory allocator scope for allocating memory.
oid_str	The OID string to resolve.

Returns

The resolved OID as a string, or NULL if resolution fails.

oid_string2encoded()

WS_DLL_PUBLIC unsigned oid_string2encoded	(	wmem_allocator_t *	scope,
		const char *	oid_str,
		uint8_t **	encoded_p
	)

Return length of encoded buffer.

Parameters

scope	The memory allocator scope.
oid_str	The OID string to encode.
encoded_p	Output pointer to the encoded buffer.

Returns

Length of the encoded buffer.

oid_string2subid()

WS_DLL_PUBLIC unsigned oid_string2subid	(	wmem_allocator_t *	scope,
		const char *	oid_str,
		uint32_t **	subids_p
	)

Return the number of sub-identifiers in a decoded OID string.

Parameters

scope	The memory allocator scope.
oid_str	The OID string to decode.
subids_p	Output pointer to the array of sub-identifiers.

Returns

The number of sub-identifiers in the decoded OID.

oid_subid2encoded()

WS_DLL_PUBLIC unsigned oid_subid2encoded	(	wmem_allocator_t *	scope,
		unsigned	len,
		uint32_t *	subids,
		uint8_t **	encoded_p
	)

Return length of encoded buffer.

Parameters

scope	The memory allocator scope.
len	The number of sub-identifiers in subids.
subids	The array of sub-identifiers to encode.
encoded_p	Output pointer to the encoded buffer.

Returns

Length of the encoded buffer.

oid_subid2string()

WS_DLL_PUBLIC char * oid_subid2string	(	wmem_allocator_t *	scope,
		uint32_t *	subids,
		unsigned	len
	)

Convert a sequence of OID sub-identifiers to a human-readable string.

Parameters

scope	Memory allocator for the returned string.
subids	Array of OID sub-identifiers.
len	Number of sub-identifiers in the array.

Returns

A formatted string representing the OID, or NULL on failure.

oids_cleanup()

WS_DLL_PUBLIC void oids_cleanup

(

void

)

Clean up OID-related resources.

init function called from epan.h

oids_init()

WS_DLL_PUBLIC void oids_init

(

const char *

app_env_var_prefix

)

Initialize OID resolution and register related preferences.

init function called from prefs.c

Parameters

app_env_var_prefix

The prefix for environment variables related to OID resolution.

rel_oid_encoded2string()

WS_DLL_PUBLIC char * rel_oid_encoded2string	(	wmem_allocator_t *	scope,
		const uint8_t *	encoded,
		unsigned	len
	)

Return the string representation of an encoded relative OID.

Parameters

scope	The memory allocator scope.
encoded	The encoded relative OID buffer.
len	The length of the encoded buffer.

Returns

The string representation of the relative OID.

rel_oid_resolved_from_encoded()

WS_DLL_PUBLIC char * rel_oid_resolved_from_encoded	(	wmem_allocator_t *	scope,
		const uint8_t *	oid,
		int	len
	)

Resolve an OID from its encoded form.

Parameters

scope	Memory allocator for allocated memory.
oid	Encoded OID data.
len	Length of the encoded OID data.

Returns

Resolved OID as a string, or NULL if resolution fails.

rel_oid_subid2string()

WS_DLL_PUBLIC char * rel_oid_subid2string	(	wmem_allocator_t *	scope,
		uint32_t *	subids,
		unsigned	len,
		bool	is_absolute
	)

Convert a sequence of OID subidentifiers to a human-readable string.

Parameters

scope	Memory allocator for the returned string.
subids	Array of OID subidentifiers.
len	Number of subidentifiers in the array.
is_absolute	Flag indicating if the OID is absolute (starts with a dot).

Returns

A formatted string representing the OID, or "*** Empty OID ***" if input is invalid.