Struct ClientBuilder 

pub struct ClientBuilder { /* private fields */ }

Builder for constructing SNMP clients.

This is the single entry point for client construction. It supports all SNMP versions (v1, v2c, v3) through the Auth enum.

Example

use async_snmp::{Auth, ClientBuilder};
use std::time::Duration;

// Simple v2c client
let client = ClientBuilder::new("192.168.1.1:161", Auth::v2c("public"))
    .connect().await?;

// v3 client with authentication
let client = ClientBuilder::new("192.168.1.1:161",
    Auth::usm("admin").auth(async_snmp::AuthProtocol::Sha256, "password"))
    .timeout(Duration::from_secs(10))
    .retries(5)
    .connect().await?;

Implementations

impl ClientBuilder

pub fn new(target: impl Into<String>, auth: impl Into<Auth>) -> Self

Create a new client builder.

Arguments

• target - The target address (e.g., “192.168.1.1:161”)
• auth - Authentication configuration (community or USM)

Example

use async_snmp::{Auth, ClientBuilder};

// Using Auth::default() for v2c with "public" community
let builder = ClientBuilder::new("192.168.1.1:161", Auth::default());

// Using Auth::v1() for SNMPv1
let builder = ClientBuilder::new("192.168.1.1:161", Auth::v1("private"));

// Using Auth::usm() for SNMPv3
let builder = ClientBuilder::new("192.168.1.1:161",
    Auth::usm("admin").auth(async_snmp::AuthProtocol::Sha256, "password"));

pub fn timeout(self, timeout: Duration) -> Self

Set the request timeout (default: 5 seconds).

pub fn retries(self, retries: u32) -> Self

Set the number of retries (default: 3).

pub fn max_oids_per_request(self, max: usize) -> Self

Set the maximum OIDs per request (default: 10).

Requests with more OIDs than this limit are automatically split into multiple batches.

pub fn max_repetitions(self, max: u32) -> Self

Set max-repetitions for GETBULK operations (default: 25).

Controls how many rows are requested per GETBULK PDU during walk operations. Higher values reduce round-trips but increase response size.

pub fn walk_mode(self, mode: WalkMode) -> Self

Override walk behavior for devices with buggy GETBULK (default: Auto).

• WalkMode::Auto: Use GETNEXT for v1, GETBULK for v2c/v3
• WalkMode::GetNext: Always use GETNEXT (slower but more compatible)
• WalkMode::GetBulk: Always use GETBULK (faster, errors on v1)

pub fn oid_ordering(self, ordering: OidOrdering) -> Self

Set OID ordering behavior for walk operations (default: Strict).

• OidOrdering::Strict: Require strictly increasing OIDs. Most efficient.
• OidOrdering::AllowNonIncreasing: Allow non-increasing OIDs with cycle detection. Uses O(n) memory to track seen OIDs.

Use AllowNonIncreasing for buggy agents that return OIDs out of order.

pub fn max_walk_results(self, limit: usize) -> Self

Set maximum results from a single walk operation (default: unlimited).

Safety limit to prevent runaway walks. Walk terminates normally when limit is reached.

pub fn engine_cache(self, cache: Arc<EngineCache>) -> Self

Set shared engine cache (V3 only, for high-throughput polling).

Allows multiple clients to share discovered engine state, reducing the number of discovery requests.

pub fn context_engine_id(self, engine_id: impl Into<Vec<u8>>) -> Self

Override the context engine ID (V3 only).

By default, the context engine ID is the same as the authoritative engine ID discovered during engine discovery. Use this to override for:

• Proxy scenarios where requests route through an intermediate agent
• Devices that require a specific context engine ID
• Pre-configured engine IDs from device documentation

The engine ID should be provided as raw bytes (not hex-encoded).

pub async fn connect(self) -> Result<Client<UdpTransport>, Error>

Connect via UDP (default).

Errors

Returns an error if the configuration is invalid or the connection fails.

pub async fn connect_tcp(self) -> Result<Client<TcpTransport>, Error>

Connect via TCP.

Errors

Returns an error if the configuration is invalid or the connection fails.

pub fn build<T: Transport>(self, transport: T) -> Result<Client<T>, Error>

Build with custom transport.

Errors

Returns an error if the configuration is invalid.