Struct Buffer

pub struct Buffer<P: ReadPrecision = ()> {
    buf: Box<[u8]>,
    filled: usize,
    precision: P,
}

Available on crate features proxy-handshake or client-handshake only.

An input buffer containing maybe some socks data

Buffer has a capacity set at creation time, and records how much data it contains.

Data is consumed by step(), and received data is appended using a RecvStep returned from step.

The P type parameter indicates whether we’re allowing read-ahead, or doing only precise reads. See ReadPrecision for details.

Fields

buf: Box<[u8]>

The actual buffer

filled: usize

[0..filled] has data that’s been read but not yet drained

precision: P

Marker for the precision

Implementations

impl Buffer<()>

pub fn new() -> Self

Creates a new default Buffer

impl Buffer<PreciseReads>

pub fn new_precise() -> Self

Creates a new Buffer for reeading precisely

use tor_socksproto::{Handshake as _, SocksProxyHandshake, SocksRequest};

let mut hs = SocksProxyHandshake::new();
let mut buf = tor_socksproto::Buffer::new_precise();

impl<P: ReadPrecision> Buffer<P>

pub fn with_size(size: usize) -> Self

Creates a new Buffer with a specified size

Specify the P type parameter according to whether you wanted a Buffer like from Buffer::new(), which will read eagerly, or one like from Buffer::new_precise(), which will read eagerly, See ReadPrecision.

let mut buf = tor_socksproto::Buffer::<tor_socksproto::PreciseReads>::with_size(2048);

pub fn from_parts(buf: Box<[u8]>, filled: usize) -> Self

Creates a new Buffer from a partially-filed buffer

• buf[..filled] should contain data already read from the peer
• buf[filled..] should be zero (or other innocuous data), and will not be used (except if there are bugs)

Using this and into_parts to obtain a Buffer with a differetn the read precision (different P type parameter) can result in malfunctions.

pub fn into_parts(self) -> (Box<[u8]>, usize)

Disassembles a Buffer, returning the pieces

pub fn unfilled_slice(&mut self) -> &mut [u8]

The portion of the buffer that is available for writing new data.

The caller may fill this (from the beginning) with more data, and then call Buffer::note_received. Normally, the caller will do this after receiving a NextStep::Recv instruction.

Where possible, prefer RecvStep::buf and RecvStep::note_received.

pub fn filled_slice(&mut self) -> &[u8]

The portion of the buffer that contains already-read, but unprocessed, data.

Callers will not normally want this.

pub fn note_received(&mut self, len: NonZeroUsize)

Notes that len bytes have been received.

The actual data must already have been written to the slice from .unfilled_slice(). Where possible, prefer RecvStep::buf and RecvStep::note_received.

(It doesn’t make sense to call this with len == 0. If the 0 came from a read call, this indicates EOF - but that might not be an error if the protocol implemnetation doesn’t need more data. RecvStep::note_received handles this properly.)

Panics

len must be no more than .unfilled_slice().len().

Trait Implementations

impl<P: ReadPrecision> Debug for Buffer<P>

fn fmt(&self, formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<P: ReadPrecision> Default for Buffer<P>

fn default() -> Self

Returns the “default value” for a type.