Skip to content

Commit

Permalink
Document Param trait (#2938)
Browse files Browse the repository at this point in the history
  • Loading branch information
kennykerr authored Mar 18, 2024
1 parent 66f0108 commit 69ffb41
Show file tree
Hide file tree
Showing 578 changed files with 84,677 additions and 84,950 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,8 @@ impl core::ops::Not for BOOL {
}
}
}
impl windows_core::IntoParam<BOOL> for bool {
unsafe fn into_param(self) -> windows_core::Param<BOOL> {
windows_core::Param::Owned(self.into())
impl windows_core::Param<BOOL> for bool {
unsafe fn param(self) -> windows_core::ParamValue<BOOL> {
windows_core::ParamValue::Owned(self.into())
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,8 @@ impl core::ops::Not for BOOLEAN {
}
}
}
impl windows_core::IntoParam<BOOLEAN> for bool {
unsafe fn into_param(self) -> windows_core::Param<BOOLEAN> {
windows_core::Param::Owned(self.into())
impl windows_core::Param<BOOLEAN> for bool {
unsafe fn param(self) -> windows_core::ParamValue<BOOLEAN> {
windows_core::ParamValue::Owned(self.into())
}
}
2 changes: 1 addition & 1 deletion crates/libs/bindgen/src/rust/structs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ fn gen_windows_traits(writer: &Writer, def: metadata::TypeDef, name: &TokenStrea
let type_kind = if is_copy {
quote! { CopyType }
} else {
quote! { ValueType }
quote! { CloneType }
};

let mut tokens = quote! {
Expand Down
2 changes: 1 addition & 1 deletion crates/libs/bindgen/src/rust/winrt_methods.rs
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ fn gen_winrt_abi_args(writer: &Writer, params: &[metadata::SignatureParam]) -> T
quote! { #name.len().try_into().unwrap(), core::mem::transmute(#name.as_ptr()), }
}
} else if metadata::type_is_borrowed(&param.ty) {
quote! { #name.into_param().abi(), }
quote! { #name.param().abi(), }
} else if metadata::type_is_blittable(&param.ty) {
if param.ty.is_const_ref() {
quote! { &#name, }
Expand Down
4 changes: 2 additions & 2 deletions crates/libs/bindgen/src/rust/writer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -373,7 +373,7 @@ impl Writer {
if param.kind == metadata::SignatureParamKind::IntoParam {
let name: TokenStream = gen_name(position);
let into = self.type_name(&param.ty);
tokens.combine(&quote! { #name: windows_core::IntoParam<#into>, });
tokens.combine(&quote! { #name: windows_core::Param<#into>, });
}
}
tokens
Expand Down Expand Up @@ -982,7 +982,7 @@ impl Writer {
}
}
metadata::SignatureParamKind::IntoParam => {
quote! { #name.into_param().abi(), }
quote! { #name.param().abi(), }
}
metadata::SignatureParamKind::OptionalPointer => {
if flags.contains(metadata::ParamAttributes::Out) {
Expand Down
8 changes: 4 additions & 4 deletions crates/libs/core/src/imp/com_bindings.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ pub unsafe fn CoCreateGuid() -> windows_core::Result<windows_core::GUID> {
#[inline]
pub unsafe fn RoGetAgileReference<P0>(options: AgileReferenceOptions, riid: *const windows_core::GUID, punk: P0) -> windows_core::Result<IAgileReference>
where
P0: windows_core::IntoParam<windows_core::IUnknown>,
P0: windows_core::Param<windows_core::IUnknown>,
{
windows_targets::link!("ole32.dll" "system" fn RoGetAgileReference(options : AgileReferenceOptions, riid : *const windows_core::GUID, punk : * mut core::ffi::c_void, ppagilereference : *mut * mut core::ffi::c_void) -> windows_core::HRESULT);
let mut result__ = std::mem::zeroed();
RoGetAgileReference(options, riid, punk.into_param().abi(), &mut result__).and_then(|| windows_core::Type::from_abi(result__))
RoGetAgileReference(options, riid, punk.param().abi(), &mut result__).and_then(|| windows_core::Type::from_abi(result__))
}
pub const AGILEREFERENCE_DEFAULT: AgileReferenceOptions = AgileReferenceOptions(0i32);
#[repr(transparent)]
Expand Down Expand Up @@ -870,11 +870,11 @@ impl PropertyValue {
}
pub fn CreateInspectable<P0>(value: P0) -> windows_core::Result<windows_core::IInspectable>
where
P0: windows_core::IntoParam<windows_core::IInspectable>,
P0: windows_core::Param<windows_core::IInspectable>,
{
Self::IPropertyValueStatics(|this| unsafe {
let mut result__ = std::mem::zeroed();
(windows_core::Interface::vtable(this).CreateInspectable)(windows_core::Interface::as_raw(this), value.into_param().abi(), &mut result__).and_then(|| windows_core::Type::from_abi(result__))
(windows_core::Interface::vtable(this).CreateInspectable)(windows_core::Interface::as_raw(this), value.param().abi(), &mut result__).and_then(|| windows_core::Type::from_abi(result__))
})
}
pub fn CreateGuid(value: windows_core::GUID) -> windows_core::Result<windows_core::IInspectable> {
Expand Down
111 changes: 57 additions & 54 deletions crates/libs/core/src/param.rs
Original file line number Diff line number Diff line change
@@ -1,105 +1,108 @@
use super::*;

#[doc(hidden)]
pub enum Param<T: Type<T>> {
Owned(T),
Borrowed(T::Abi),
}

impl<T: Type<T>> Param<T> {
pub fn abi(&self) -> T::Abi {
unsafe {
match self {
Self::Owned(item) => std::mem::transmute_copy(item),
Self::Borrowed(borrowed) => std::mem::transmute_copy(borrowed),
}
}
}
}

#[doc(hidden)]
pub trait CanInto<T>: Sized {
const QUERY: bool = false;
}

impl<T> CanInto<T> for T where T: Clone {}

#[doc(hidden)]
pub trait IntoParam<T: TypeKind, C = <T as TypeKind>::TypeKind>: Sized
/// Provides automatic parameter conversion in cases where the Windows API expects implicit conversion support.
///
/// There is no need to implement this trait. Blanket implementations are provided for all applicable Windows types.
pub trait Param<T: TypeKind, C = <T as TypeKind>::TypeKind>: Sized
where
T: Type<T>,
{
unsafe fn into_param(self) -> Param<T>;
#[doc(hidden)]
unsafe fn param(self) -> ParamValue<T>;
}

impl<T> IntoParam<T> for Option<&T>
impl<T> Param<T> for Option<&T>
where
T: Type<T>,
{
unsafe fn into_param(self) -> Param<T> {
Param::Borrowed(match self {
unsafe fn param(self) -> ParamValue<T> {
ParamValue::Borrowed(match self {
Some(item) => std::mem::transmute_copy(item),
None => std::mem::zeroed(),
})
}
}

impl<T, U> IntoParam<T, ReferenceType> for &U
impl<T, U> Param<T, InterfaceType> for &U
where
T: TypeKind<TypeKind = ReferenceType> + Clone,
T: TypeKind<TypeKind = InterfaceType> + Clone,
T: Interface,
U: Interface,
U: CanInto<T>,
{
unsafe fn into_param(self) -> Param<T> {
unsafe fn param(self) -> ParamValue<T> {
if U::QUERY {
self.cast().map_or(Param::Borrowed(std::mem::zeroed()), |ok| Param::Owned(ok))
self.cast().map_or(ParamValue::Borrowed(std::mem::zeroed()), |ok| ParamValue::Owned(ok))
} else {
Param::Borrowed(std::mem::transmute_copy(self))
ParamValue::Borrowed(std::mem::transmute_copy(self))
}
}
}

impl<T> IntoParam<T, ValueType> for &T
impl<T> Param<T, CloneType> for &T
where
T: TypeKind<TypeKind = ValueType> + Clone,
T: TypeKind<TypeKind = CloneType> + Clone,
{
unsafe fn into_param(self) -> Param<T> {
Param::Borrowed(std::mem::transmute_copy(self))
unsafe fn param(self) -> ParamValue<T> {
ParamValue::Borrowed(std::mem::transmute_copy(self))
}
}

impl<T, U> IntoParam<T, CopyType> for U
impl<T, U> Param<T, CopyType> for U
where
T: TypeKind<TypeKind = CopyType> + Clone,
U: TypeKind<TypeKind = CopyType> + Clone,
U: CanInto<T>,
{
unsafe fn into_param(self) -> Param<T> {
Param::Owned(std::mem::transmute_copy(&self))
unsafe fn param(self) -> ParamValue<T> {
ParamValue::Owned(std::mem::transmute_copy(&self))
}
}

impl IntoParam<PCWSTR> for &BSTR {
unsafe fn into_param(self) -> Param<PCWSTR> {
Param::Owned(PCWSTR(self.as_ptr()))
impl Param<PCWSTR> for &BSTR {
unsafe fn param(self) -> ParamValue<PCWSTR> {
ParamValue::Owned(PCWSTR(self.as_ptr()))
}
}

impl IntoParam<PCWSTR> for &HSTRING {
unsafe fn into_param(self) -> Param<PCWSTR> {
Param::Owned(PCWSTR(self.as_ptr()))
impl Param<PCWSTR> for &HSTRING {
unsafe fn param(self) -> ParamValue<PCWSTR> {
ParamValue::Owned(PCWSTR(self.as_ptr()))
}
}

impl IntoParam<PCWSTR> for PWSTR {
unsafe fn into_param(self) -> Param<PCWSTR> {
Param::Owned(PCWSTR(self.0))
impl Param<PCWSTR> for PWSTR {
unsafe fn param(self) -> ParamValue<PCWSTR> {
ParamValue::Owned(PCWSTR(self.0))
}
}

impl IntoParam<PCSTR> for PSTR {
unsafe fn into_param(self) -> Param<PCSTR> {
Param::Owned(PCSTR(self.0))
impl Param<PCSTR> for PSTR {
unsafe fn param(self) -> ParamValue<PCSTR> {
ParamValue::Owned(PCSTR(self.0))
}
}

#[doc(hidden)]
pub enum ParamValue<T: Type<T>> {
Owned(T),
Borrowed(T::Abi),
}

impl<T: Type<T>> ParamValue<T> {
pub fn abi(&self) -> T::Abi {
unsafe {
match self {
Self::Owned(item) => std::mem::transmute_copy(item),
Self::Borrowed(borrowed) => std::mem::transmute_copy(borrowed),
}
}
}
}

#[doc(hidden)]
pub trait CanInto<T>: Sized {
const QUERY: bool = false;
}

impl<T> CanInto<T> for T where T: Clone {}
18 changes: 9 additions & 9 deletions crates/libs/core/src/type.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,10 @@ pub trait TypeKind {
}

#[doc(hidden)]
pub struct ReferenceType;
pub struct InterfaceType;

#[doc(hidden)]
pub struct ValueType;
pub struct CloneType;

#[doc(hidden)]
pub struct CopyType;
Expand All @@ -24,9 +24,9 @@ pub trait Type<T: TypeKind, C = <T as TypeKind>::TypeKind>: TypeKind + Sized + C
fn from_default(default: &Self::Default) -> Result<Self>;
}

impl<T> Type<T, ReferenceType> for T
impl<T> Type<T, InterfaceType> for T
where
T: TypeKind<TypeKind = ReferenceType> + Clone,
T: TypeKind<TypeKind = InterfaceType> + Clone,
{
type Abi = *mut std::ffi::c_void;
type Default = Option<Self>;
Expand All @@ -44,9 +44,9 @@ where
}
}

impl<T> Type<T, ValueType> for T
impl<T> Type<T, CloneType> for T
where
T: TypeKind<TypeKind = ValueType> + Clone,
T: TypeKind<TypeKind = CloneType> + Clone,
{
type Abi = std::mem::MaybeUninit<Self>;
type Default = Self;
Expand Down Expand Up @@ -77,7 +77,7 @@ where
}

impl<T: Interface> TypeKind for T {
type TypeKind = ReferenceType;
type TypeKind = InterfaceType;
}

impl<T> TypeKind for *mut T {
Expand Down Expand Up @@ -116,9 +116,9 @@ impl TypeKind for PCSTR {
}

impl TypeKind for HSTRING {
type TypeKind = ValueType;
type TypeKind = CloneType;
}

impl TypeKind for BSTR {
type TypeKind = ValueType;
type TypeKind = CloneType;
}
4 changes: 2 additions & 2 deletions crates/libs/core/src/variant.rs
Original file line number Diff line number Diff line change
Expand Up @@ -53,11 +53,11 @@ impl Drop for PROPVARIANT {
}

impl TypeKind for VARIANT {
type TypeKind = ValueType;
type TypeKind = CloneType;
}

impl TypeKind for PROPVARIANT {
type TypeKind = ValueType;
type TypeKind = CloneType;
}

impl std::fmt::Debug for VARIANT {
Expand Down
Loading

0 comments on commit 69ffb41

Please sign in to comment.