Crate grob

Welcome to the grob (growable buffer) crate!

Many Windows API functions require the caller to provide a buffer for the returned data. The pattern goes something like this…

• Call the function with an initial buffer and size
• If that works then process the returned data
• If that does not work because the buffer is too small then create a larger buffer and try again
• If that does not work for any other reason then deal with the error

There are copious examples of a growable buffer including a version in the Rust Standard Library. There is a lack of consistency amoungst all the examples. Some versions continue trying indefinately. Some versions make an arbitrary number of attempts like three then give up. Some versions double the size of the new buffer. Some versions increase the size by a fixed amount like 128 bytes. Even Microsoft’s API examples are inconsistent.

The goal with this crate is to provide a single high quality growable buffer that any Rust developer can easily use.

Getting Start

The generic functions listed below are a great place to start. They wrap all the details necessary for making Windows API calls.

When the API Call Returns	And the Data Is	For Example	Use
an error code; a u32	large + binary	GetTcpTable2	winapi_large_binary + RvIsError
an error code; a u32	large + binary	GetAdaptersAddresses	winapi_large_binary + RvIsError
a BOOL	small + binary	GetLogicalProcessorInformationEx	winapi_small_binary + RvIsError
a BOOL	text	GetUserNameW	winapi_string + RvIsError
elements / WCHARs stored	path	GetModuleFileNameW	winapi_path_buf + RvIsSize
elements / WCHARs stored	path	GetSystemWindowsDirectoryW	winapi_path_buf + RvIsSize
bytes stored	large + binary	GetFileVersionInfoSizeW	winapi_large_binary + see example

WindowsString and WindowsPathString are available for easily and efficiently passing string parameters into Windows API functions like DeleteFileW, ReplaceFileW, and SetComputerNameW.

Structs

Argument

Wrapper for Windows API arguments. Typically a pointer to the buffer and a pointer to the buffer size or a &mut [T].

FrozenBuffer

Read-only buffer filled with data from an operating system call.

GrowByDoubleWithNull

GrowStrategy appropriate for Windows API calls that return the number of characters stored (the needed buffer space is not available).

GrowToNearestNibble

GrowStrategy appropriate for small binary data that is unlikely to change where the call returns the buffer size needed.

GrowToNearestNibbleWithNull

GrowStrategy appropriate for Windows API calls that return the number of characters that need to be stored for success (the needed buffer size is returned).

GrowToNearestQuarterKibi

GrowStrategy appropriate for large binary data that may change between calls where the call returns the buffer size needed.

GrowableBuffer

Writable buffer capable of providing an Argument for a Windows API function then a FrozenBuffer when that call succeeds.

RvIsError

Wrapper for the return value from a Windows API call that returns an error code.

RvIsSize

Wrapper for the return value from a Windows API call that returns the number of elements stored

StackBuffer

Initial buffer placed on the stack to improve performance.

WindowsPathString

Windows (UTF-16) string placed on the stack when possible to improve performance sized for paths.

WindowsString

Windows (UTF-16) string placed on the stack when possible to improve performance.

Enums

FillBufferAction

What action to take after an operating system call: Commit, Grow, or NoData

Constants

ALIGNMENT

Buffer alignment that works for all Windows API calls; alignment used for all grob buffers

CAPACITY_FOR_NAMES

A good starting buffer capacity, in bytes, for Windows API calls that return the name of something.

CAPACITY_FOR_PATHS

A good starting buffer capacity, in bytes, for Windows API calls that return a file system path.

SIZE_OF_WCHAR

Size of WCHAR / u16 (two bytes) cast as a u32.

Traits

AsPCWSTR

GrowStrategy

How should the buffer grow? Small bump? Double in capacity?

NeededSize

Used internally help determine the FillBufferAction.

RawToInternal

Conversion between capacity (bytes in the buffer) and size (API units of measure like WCHARs). Conversion to the API pointer type.

ReadBuffer

Return a read-only pointer to a buffer and the actual number of bytes stored in the buffer.

ToResult

Convert an API return value and the needed buffer size into a FillBufferResult which is then converted to a FillBufferAction.

WriteBuffer

Management for a writable buffer.

Functions

winapi_binary

Generic growable buffer loop for binary data (the result datatype is implied).

winapi_generic

Generic growable buffer loop.

winapi_large_binary

Generic wrapper function for a Windows API call that returns binary data and needs a relatively large buffer.

winapi_path_buf

Generic wrapper for a Windows API call that returns a file system path.

winapi_small_binary

Generic wrapper function for a Windows API call that returns binary data and needs a relatively small buffer

winapi_string

Generic wrapper for a Windows API call that returns a text string like the computer or user name.

Type Aliases

FillBufferResult

The result of an operating system call.

GrowForSmallBinary

Alias for the GrowToNearestNibble GrowStrategy.

GrowForStaticText

Alias for the GrowToNearestNibbleWithNull GrowStrategy.

GrowForStoredIsReturned

Alias for the GrowByDoubleWithNull GrowStrategy.