Struct Oid

Source

pub struct Oid { /* private fields */ }

Expand description

Object Identifier.

Stored as a sequence of arc values (u32). Uses SmallVec to avoid heap allocation for OIDs with 16 or fewer arcs.

Implementations§

Source §

impl Oid

Source

pub fn empty() -> Self

Create an empty OID.

Source

pub fn new(arcs: impl IntoIterator<Item = u32>) -> Self

Create an OID from arc values.

Accepts any iterator of u32 values.

§Examples

use async_snmp::oid::Oid;

// From a Vec
let oid = Oid::new(vec![1, 3, 6, 1, 2, 1]);
assert_eq!(oid.arcs(), &[1, 3, 6, 1, 2, 1]);

// From an array
let oid = Oid::new([1, 3, 6, 1]);
assert_eq!(oid.len(), 4);

// From a range
let oid = Oid::new(0..5);
assert_eq!(oid.arcs(), &[0, 1, 2, 3, 4]);

Source

pub fn from_slice(arcs: &[u32]) -> Self

Create an OID from a slice of arcs.

§Examples

use async_snmp::oid::Oid;

let arcs = [1, 3, 6, 1, 2, 1, 1, 1, 0];
let oid = Oid::from_slice(&arcs);
assert_eq!(oid.to_string(), "1.3.6.1.2.1.1.1.0");

// Empty slice creates an empty OID
let empty = Oid::from_slice(&[]);
assert!(empty.is_empty());

Source

pub fn parse(s: &str) -> Result<Self>

Parse an OID from dotted string notation (e.g., “1.3.6.1.2.1.1.1.0”).

§Validation

This method parses the string format but does not validate arc constraints per X.690 Section 8.19.4. Invalid OIDs like "3.0" (arc1 must be 0, 1, or 2) or "0.40" (arc2 must be ≤39 when arc1 < 2) will parse successfully.

To validate arc constraints, call validate() after parsing, or use to_ber_checked() which validates before encoding.

§Examples

use async_snmp::oid::Oid;

// Valid OID
let oid = Oid::parse("1.3.6.1.2.1.1.1.0").unwrap();
assert!(oid.validate().is_ok());

// Invalid arc1 parses but fails validation
let invalid = Oid::parse("3.0").unwrap();
assert!(invalid.validate().is_err());

Source

pub fn arcs(&self) -> &[u32]

Get the arc values.

Source

pub fn len(&self) -> usize

Get the number of arcs.

Source

pub fn is_empty(&self) -> bool

Check if the OID is empty.

Source

pub fn starts_with(&self, other: &Oid) -> bool

Check if this OID starts with another OID.

Returns true if self begins with the same arcs as other. An OID always starts with itself, and any OID starts with an empty OID.

§Examples

use async_snmp::oid::Oid;

let sys_descr = Oid::parse("1.3.6.1.2.1.1.1.0").unwrap();
let system = Oid::parse("1.3.6.1.2.1.1").unwrap();
let interfaces = Oid::parse("1.3.6.1.2.1.2").unwrap();

// sysDescr is under the system subtree
assert!(sys_descr.starts_with(&system));

// sysDescr is not under the interfaces subtree
assert!(!sys_descr.starts_with(&interfaces));

// Every OID starts with itself
assert!(sys_descr.starts_with(&sys_descr));

// Every OID starts with the empty OID
assert!(sys_descr.starts_with(&Oid::empty()));

Source

pub fn parent(&self) -> Option<Oid>

Get the parent OID (all arcs except the last).

Returns None if the OID is empty.

§Examples

use async_snmp::oid::Oid;

let sys_descr = Oid::parse("1.3.6.1.2.1.1.1.0").unwrap();
let parent = sys_descr.parent().unwrap();
assert_eq!(parent.to_string(), "1.3.6.1.2.1.1.1");

// Can chain parent() calls
let grandparent = parent.parent().unwrap();
assert_eq!(grandparent.to_string(), "1.3.6.1.2.1.1");

// Empty OID has no parent
assert!(Oid::empty().parent().is_none());

Source

pub fn child(&self, arc: u32) -> Oid

Create a child OID by appending an arc.

§Examples

use async_snmp::oid::Oid;

let system = Oid::parse("1.3.6.1.2.1.1").unwrap();

// sysDescr is system.1
let sys_descr = system.child(1);
assert_eq!(sys_descr.to_string(), "1.3.6.1.2.1.1.1");

// sysDescr.0 is the scalar instance
let sys_descr_instance = sys_descr.child(0);
assert_eq!(sys_descr_instance.to_string(), "1.3.6.1.2.1.1.1.0");

Source

pub fn strip_prefix(&self, prefix: &Oid) -> Option<Oid>

Strip a prefix OID, returning the remaining arcs as a new Oid.

Returns None if self doesn’t start with the given prefix. Follows str::strip_prefix semantics - stripping an equal OID returns an empty OID.

This is useful for extracting table indexes from walked OIDs.

§Examples

use async_snmp::{oid, Oid};

let if_descr_5 = oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2, 5);
let if_descr = oid!(1, 3, 6, 1, 2, 1, 2, 2, 1, 2);

// Extract the index
let index = if_descr_5.strip_prefix(&if_descr).unwrap();
assert_eq!(index.arcs(), &[5]);

// Non-matching prefix returns None
let sys_descr = oid!(1, 3, 6, 1, 2, 1, 1, 1);
assert!(if_descr_5.strip_prefix(&sys_descr).is_none());

// Equal OIDs return empty
let same = oid!(1, 3, 6);
assert!(same.strip_prefix(&same).unwrap().is_empty());

// Empty prefix returns self
let any = oid!(1, 2, 3);
assert_eq!(any.strip_prefix(&Oid::empty()).unwrap(), any);

Source

pub fn suffix(&self, n: usize) -> Option<&[u32]>

Get the last N arcs as a slice (for multi-level table indexes).

Returns None if n exceeds the OID length.

This is useful for grouping SNMP table walk results by composite indexes.

§Examples

use async_snmp::oid;

// ipNetToMediaPhysAddress has index (ifIndex, IpAddress) = 5 arcs
let oid = oid!(1, 3, 6, 1, 2, 1, 4, 22, 1, 2, 1, 192, 168, 1, 100);

// Get the 5-arc index (ifIndex=1, IP=192.168.1.100)
let index = oid.suffix(5).unwrap();
assert_eq!(index, &[1, 192, 168, 1, 100]);

// Get just the last arc
assert_eq!(oid.suffix(1), Some(&[100][..]));

// suffix(0) returns empty slice
assert_eq!(oid.suffix(0), Some(&[][..]));

// Too large returns None
assert!(oid.suffix(100).is_none());

Source

pub fn validate(&self) -> Result<()>

Validate OID arcs per X.690 Section 8.19.4.

arc1 must be 0, 1, or 2
arc2 must be <= 39 when arc1 is 0 or 1
arc2 must not cause overflow when computing first subidentifier (arc1*40 + arc2)

§Examples

use async_snmp::oid::Oid;

// Standard SNMP OIDs are valid
let oid = Oid::parse("1.3.6.1.2.1.1.1.0").unwrap();
assert!(oid.validate().is_ok());

// arc1 must be 0, 1, or 2
let invalid = Oid::from_slice(&[3, 0]);
assert!(invalid.validate().is_err());

// arc2 must be <= 39 when arc1 is 0 or 1
let invalid = Oid::from_slice(&[0, 40]);
assert!(invalid.validate().is_err());

// arc2 can be large when arc1 is 2, but must not overflow
let valid = Oid::from_slice(&[2, 999]);
assert!(valid.validate().is_ok());

Source

pub fn validate_length(&self) -> Result<()>

Validate that the OID doesn’t exceed the maximum arc count.

SNMP implementations commonly limit OIDs to 128 subidentifiers. This check provides protection against DoS attacks from maliciously long OIDs.

§Examples

use async_snmp::oid::{Oid, MAX_OID_LEN};

let oid = Oid::parse("1.3.6.1.2.1.1.1.0").unwrap();
assert!(oid.validate_length().is_ok());

// Create an OID with too many arcs
let too_long: Vec<u32> = (0..150).collect();
let long_oid = Oid::new(too_long);
assert!(long_oid.validate_length().is_err());

Source

pub fn validate_all(&self) -> Result<()>

Validate both arc constraints and length.

Combines validate() and validate_length().

Source

pub fn to_ber_smallvec(&self) -> SmallVec<[u8; 64]>

Encode to BER format, returning bytes in a stack-allocated buffer.

Uses SmallVec to avoid heap allocation for OIDs with up to ~20 arcs. This is the optimized version used internally by encoding routines.

OID encoding (X.690 Section 8.19):

First two arcs encoded as (arc1 * 40) + arc2 using base-128
Remaining arcs encoded as base-128 variable length

Source

pub fn to_ber(&self) -> Vec<u8> ⓘ

Encode to BER format.

OID encoding (X.690 Section 8.19):

First two arcs encoded as (arc1 * 40) + arc2 using base-128
Remaining arcs encoded as base-128 variable length

§Empty OID Encoding

Empty OIDs are encoded as zero bytes (empty content). Note that net-snmp encodes empty OIDs as [0x00] (single zero byte). This difference is unlikely to matter in practice since empty OIDs are rarely used in SNMP.