Struct OwnedUnicodeString 

pub struct OwnedUnicodeString { /* private fields */ }

A safe wrapper around Windows UNICODE_STRING that owns its UTF-16 buffer.

The OwnedUnicodeString structure provides a safe abstraction over the Windows UNICODE_STRING type, which is used for handling Unicode strings in Windows environments. This structure owns a UTF-16 buffer and ensures its validity throughout the lifetime of the OwnedUnicodeString instance, preventing memory safety issues such as dangling pointers and buffer overflows.

The safety of OwnedUnicodeString is primarily derived from its ownership model. It manages the UTF-16 buffer internally using a Vec<u16>, which allows for dynamic resizing and ensures proper memory deallocation when the OwnedUnicodeString instance is dropped. By owning the buffer, the structure ensures that the memory is only released when it is no longer in use, thereby preventing use-after-free errors.

However, it’s important to note that the UNICODE_STRING structure used internally contains a mutable pointer (*mut u16) to the UTF-16 buffer (PWSTR), which directly points to the underlying Vec<u16>. This mutable pointer is necessary because the Microsoft bindings for Windows APIs use this type to interact with strings. As a result, if the user decides to manually modify the vector (Vec<u16>) without properly adjusting the associated length fields (Length and MaximumLength), it can lead to undefined behavior or potential memory safety issues. Therefore, while the buffer is accessible and mutable, any manual modifications should be performed with caution.

The mutable pointer and direct access to the buffer are unavoidable due to the design of the Windows API bindings provided by Microsoft, which require the use of *mut u16 (PWSTR). This design choice respects the type requirements of these bindings but also places the responsibility on the user to handle any low-level modifications with care to maintain the integrity of the Unicode string.

Fields

• unicode_string: A UNICODE_STRING structure that points to the UTF-16 buffer. This structure is updated to reflect the current state of the buffer, including its length and maximum length. The Buffer field is a mutable pointer (*mut u16) to the UTF-16 data.
• buffer: A Vec<u16> that owns and manages the UTF-16 buffer, ensuring that its lifetime is tied to the OwnedUnicodeString structure. The buffer’s memory is automatically managed, reducing the risk of memory leaks or unsafe memory access.

Safety

OwnedUnicodeString ensures that the UTF-16 buffer remains valid and properly managed as long as the OwnedUnicodeString instance exists. This design guarantees that memory is safely allocated and deallocated and that the buffer is correctly formatted for use with Windows APIs. However, due to the mutable pointer in the underlying UNICODE_STRING, caution must be exercised if manually modifying the buffer to prevent mismatches in length or buffer overflows.

Trait Implementations

impl Add<&str> for OwnedUnicodeString

fn add(self, rhs: &str) -> Self::Output

Concatenates an OwnedUnicodeString with a Rust string slice (&str).

This implementation allows for concatenating a Rust &str directly onto an OwnedUnicodeString, returning a new OwnedUnicodeString with the combined content. The string slice is encoded as UTF-16 before concatenation.

type Output = OwnedUnicodeString

The resulting type after applying the + operator.

impl Add for OwnedUnicodeString

fn add(self, rhs: Self) -> Self::Output

Concatenates two OwnedUnicodeString instances.

This implementation of the Add trait allows for the concatenation of two OwnedUnicodeString instances, resulting in a new OwnedUnicodeString that contains the combined UTF-16 buffers of the operands. It ensures that the resulting buffer is properly null-terminated and that the lengths are updated accordingly.

Safety

The internal buffer is resized to accommodate the concatenated strings, and lengths are recalculated to prevent overflows or invalid reads.

type Output = OwnedUnicodeString

The resulting type after applying the + operator.

impl AsRef<UNICODE_STRING> for OwnedUnicodeString

fn as_ref(&self) -> &UNICODE_STRING

Provides a reference to the internal UNICODE_STRING.

This implementation allows for safe access to the underlying UNICODE_STRING structure, which can be useful for interoperability with Windows APIs that expect a UNICODE_STRING pointer. The returned reference reflects the current state of the buffer and its lengths.

impl Display for OwnedUnicodeString

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

Formats the OwnedUnicodeString as a Rust string for display purposes.

This implementation provides a Display formatter that allows the OwnedUnicodeString to be printed directly using Rust’s println! and other formatting macros. It decodes the UTF-16 buffer to a Rust string slice, converting any invalid UTF-16 sequences to the Unicode replacement character (�).

Examples

use krnlstring::OwnedUnicodeString;

let my_string = OwnedUnicodeString::from("Hello, world!");
println!("{}", my_string);

impl From<&str> for OwnedUnicodeString

fn from(value: &str) -> Self

Converts a Rust string slice (&str) to an OwnedUnicodeString.

This implementation encodes the Rust string as UTF-16 and stores the result in a Vec<u16>, which is then used to initialize the OwnedUnicodeString. This allows for seamless integration with Rust’s native string types while leveraging the safety and efficiency of UTF-16 buffers.

Examples

use krnlstring::OwnedUnicodeString;

let my_string = OwnedUnicodeString::from("Hello, world!");

impl From<Vec<u16>> for OwnedUnicodeString

fn from(value: Vec<u16>) -> Self

Converts a Vec<u16> to an OwnedUnicodeString.

This implementation takes ownership of the provided Vec<u16>, allowing for direct manipulation of the UTF-16 buffer. It initializes an UNICODE_STRING with the provided vector, calculates the length and maximum length of the buffer, and ensures that it remains valid and properly managed throughout the instance’s lifetime.

Safety

The caller must ensure that the input Vec<u16> represents a valid UTF-16 encoded string. This function will calculate the lengths based on the vector’s contents and adjust the UNICODE_STRING fields accordingly.

impl Into<*const u16> for &mut OwnedUnicodeString

fn into(self) -> PCWSTR

Converts a mutable reference to an OwnedUnicodeString into a PCWSTR.

This conversion ensures that the UTF-16 buffer is null-terminated, as required for use with many Windows API functions that expect a PCWSTR (a pointer to a constant, null-terminated UTF-16 string). The conversion does not make a copy of the buffer, maintaining a zero-copy approach.

Safety

The buffer must remain valid for the lifetime of the PCWSTR returned. The caller should ensure that the OwnedUnicodeString is not mutated in a way that invalidates the pointer.

impl Into<*mut u16> for &mut OwnedUnicodeString

fn into(self) -> PWSTR

Converts a mutable reference to an OwnedUnicodeString into a PWSTR.

Similar to Into<PCWSTR>, this conversion ensures that the UTF-16 buffer is properly null-terminated and returns a mutable pointer (PWSTR). This is useful for APIs that require a mutable UTF-16 string buffer.

Safety

The buffer must remain valid and should not be modified in a way that would invalidate the pointer while it is being used as a PWSTR.

impl PartialEq for OwnedUnicodeString

fn eq(&self, other: &Self) -> bool

Compares two OwnedUnicodeString instances for equality.

This implementation of the PartialEq trait allows for the comparison of two OwnedUnicodeString instances based on the contents of their UTF-16 buffers. It checks if the lengths and contents of both buffers match, providing a simple and efficient way to compare Unicode strings.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.