pub struct InParam<T: Abi> { /* private fields */ }Expand description
An “IN” param to a Windows API.
In the Windows API, “IN” params are optional params that are borrowed for the lifetime of the function call.
Therefore, InParam<'a, T> is essentially, an optional &'a T (where 'a is the lifetime of the function call)
that has the right in-memory layout to passed to a Windows API.
Usage
Many functions in the windows crate have signatures similar to the following:
fn SomeFunction<'a, P: Into<InParam<'a, IUnknown>>>(iunknown: P);This signature allows the parameter iunknown to passed any value that implements Into<InParam<'a, IUnknown>>.
In other words, anything that can be turned into an InParam<'a, IUnknown> can be used as an argument to this function.
So, what can be turned into an InParam?
Generally, if this is safe to do, the windows crate provides an implementation allowing you to pass the item. This means,
you should be able to pass anything that is logically equivalent to an IUnknown into SomeFunction.
Here are the typical things that can be converted into an InParam<'a, T>:
- References to a value of type
T(i.e.,&'a T). - Anything that can be turned into a
&'a T.- For example, many COM interfaces have such conversions to parent interfaces. For example, if a function requires an
InParam<'a, IUnknown>, you can pass a&'a IInspectablesinceIInspectableinherits fromIUnknown.
- For example, many COM interfaces have such conversions to parent interfaces. For example, if a function requires an
None- becauseInParamss are always optional- Children classes in a WinRT hierarchy.
- For example,
CompositionProjectedShadowCasterhas a method calledSetBrush. This method takes any type that implementsInto<InParam<'a, CompositionBrush>>. This allows you to pass a&CompositionBrushbut also children classes likeCompositionColorBrush.
- For example,
What is the reason for InParam existing?
InParamss can be thought of much kind of like an Cow<'a, Option<T>> - i.e., an optional value that might be owned or might be borrowed.
The reason InParam must be used instead of Cow<'a, Option<T>> is because for FFI calls to work, we need to be very careful about the in-memory
layout of the parameter. InParam takes care of turning the value into the proper in-memory layout that the FFI call expects.
InParams are composed of either an owned type or a Borrowed<'a, T>. If you want to know more about how the types line up at the abi layer,
read the docs for Borrowed and for Abi.
Implementations§
§impl<T: Abi> InParam<T>
impl<T: Abi> InParam<T>
pub fn owned(item: T) -> Self
pub fn owned(item: T) -> Self
Create an owned InParam
Normally, it is not necessary to use this function. Generally, there is a From implementation
that allows you to call .into to safely create an InParam value.
pub fn borrowed(item: ManuallyDrop<T>) -> Self
pub fn borrowed(item: ManuallyDrop<T>) -> Self
Create a borrowed InParam
Normally, it is not necessary to use this function. Generally, there is a From implementation
that allows you to call .into to safely create an InParam value.
pub fn abi(&self) -> T::Abi
pub fn abi(&self) -> T::Abi
Convert this InParam into its abi representation