# Module std::os::windows::ffi 1.0.0 [−] [src]

This is supported on Windows only.

Windows-specific extensions to the primitives in the `std::ffi` module.

# Overview

For historical reasons, the Windows API uses a form of potentially ill-formed UTF-16 encoding for strings. Specifically, the 16-bit code units in Windows strings may contain isolated surrogate code points which are not paired together. The Unicode standard requires that surrogate code points (those in the range U+D800 to U+DFFF) always be paired, because in the UTF-16 encoding a surrogate code unit pair is used to encode a single character. For compatibility with code that does not enforce these pairings, Windows does not enforce them, either.

While it is not always possible to convert such a string losslessly into a valid UTF-16 string (or even UTF-8), it is often desirable to be able to round-trip such a string from and to Windows APIs losslessly. For example, some Rust code may be "bridging" some Windows APIs together, just passing `WCHAR` strings among those APIs without ever really looking into the strings.

If Rust code does need to look into those strings, it can convert them to valid UTF-8, possibly lossily, by substituting invalid sequences with U+FFFD REPLACEMENT CHARACTER, as is conventionally done in other Rust APIs that deal with string encodings.

# `OsStringExt` and `OsStrExt`

`OsString` is the Rust wrapper for owned strings in the preferred representation of the operating system. On Windows, this struct gets augmented with an implementation of the `OsStringExt` trait, which has a `from_wide` method. This lets you create an `OsString` from a `&[u16]` slice; presumably you get such a slice out of a `WCHAR` Windows API.

Similarly, `OsStr` is the Rust wrapper for borrowed strings from preferred representation of the operating system. On Windows, the `OsStrExt` trait provides the `encode_wide` method, which outputs an `EncodeWide` iterator. You can `collect` this iterator, for example, to obtain a `Vec<u16>`; you can later get a pointer to this vector's contents and feed it to Windows APIs.

These traits, along with `OsString` and `OsStr`, work in conjunction so that it is possible to round-trip strings from Windows and back, with no loss of data, even if the strings are ill-formed UTF-16.

## Structs

EncodeWide | [ Windows ] Generates a wide character sequence for potentially ill-formed UTF-16.

## Traits

OsStrExt | [ Windows ] Windows-specific extensions to `OsStr`.
OsStringExt | [ Windows ] Windows-specific extensions to `OsString`.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
↑
  Move up in search results
↓
  Move down in search results
↹
  Switch tab
⏎
  Go to active search result
+ / -
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)