search

MicrosoftDocs / winrt-api

WinRT reference content for developing Microsoft Universal Windows Platform (UWP) apps
Creative Commons Attribution 4.0 International
231 stars 500 forks source link

pnp namespace is deprecated. And we could explain better the pnp object model. #2391

Closed smadasam closed 1 year ago

smadasam commented 1 year ago

[Enter feedback here] We need to describe the Pnp namespace as obsolete or depreciated. It was [debatable whether it should ever have] existed. [That] was corrected in TH1 (10.0.10240.0). Device information kind was introduced at the base Windows.Devices.Enumeration namespace, which eliminates the need for the pnp namespace to exist.

Here is a diagram of the PnP object model as expressed by DevQuery or the Windows.Devices.Enumeration API

https://microsoft.sharepoint.com/:u:/r/teams/osg_core_sigma/dplat/Shared%20Documents/Teams/DnD/Planning/Nickel/Device%20Object%20Model.vsdx?d=wffd4600cc92d413690a523240f77b3b5&csf=1&web=1&e=csG4Yb

Device Object Model

Windows.Devices.Enumeration defaults to returning device interfaces if no kind is specified. Most selectors and the enums, query device interfaces. This makes sense since most device stacks consume interfaces instances and their currency. The deeper PnP object model is available by passing the device information kind.

Association Endpoints (AEPs) generally "hit the wire" to discover devices, so it can be expensive in terms of power and time, and impact QoS depending on how your PC implemented their radios. Association objects should always be discovered with a watcher as many protocols don't have a concept of "enumeration complete," so the protocol stack emulates that with a long query timeout.

If you need to use a protocol-style device, they are normally discovered as AEPs first. Typically, these devices are discovered, and then paired. After they are paired, typically the protocol stack creates PnP state with devnodes, interfaces, etc., so the default interface watcher won't enumerate them until they are paired. Some devices can't be paired and are simply accessed as AEPs in their device stacks, eg. some BTLE devices and profiles.

What the objects are for: DeviceInterface: describes what the device can do, eg. camera, mic, accelerometer. Device stacks generally operate on device interfaces, or even more generically, devices are accessed by the interface with CreateFile, and IOCTL. Device, represents a device node as discovered by a bus, etc. PCI, USB, in the PnP tree. PnP loads drivers onto device nodes. DeviceContainer, is intended to describe what the user might precieve as a "device," eg. printer, mouse, laptop, and is a collection of device nodes that reside in that chassis. DevicePanel, DeviceInterfaceClass, defines well known devices classes and the programming contact for that interface, eg. a webcam interface class has a well known programming contract, so device interfaces of that class are used via that contract AssociationEndpoint: represents a device that is discoverable by the PC, but not typically by PnP busses like USB, but by device protocols like Bluetooth, or a network printer over various protocols like IPP. AssociationEndpointContainer, is intended to describe what the user might precieve as a "device," eg. printer, XBOX, that might make itself discoverable as one or more endpoint over one or more protocols AssociationEndpointService, describes what the device endpoint can do, eg. print, media server, headset, etc. an endpoint typically has to be paired to access the services, but not always

    [version(NTDDI_WINTHRESHOLD)]
    [version(NTDDI_WINTHRESHOLD, Platform.WindowsPhone)]
    [v1_enum]
    [contract(Windows.Foundation.UniversalApiContract, 1)]
    typedef enum DeviceInformationKind
    {
        Unknown = 0,
        DeviceInterface,
        DeviceContainer,
        Device,
        DeviceInterfaceClass,
        AssociationEndpoint,
        AssociationEndpointContainer,
        AssociationEndpointService,
        [contract(Windows.Foundation.UniversalApiContract, 7)]
        DevicePanel
    } DeviceInformationKind;

    [version(NTDDI_WINTHRESHOLD)]
    [version(NTDDI_WINTHRESHOLD, Platform.WindowsPhone)]
    [uuid(493b4f34-a84f-45fd-9167-15d1cb1bd1f9)]
    [exclusiveto(DeviceInformation)]
    [contract(Windows.Foundation.UniversalApiContract, 1)]
    interface IDeviceInformationStatics2: IInspectable
    {
        HRESULT GetAqsFilterFromDeviceClass(
            [in] DeviceClass deviceClass,
            [out, retval] HSTRING *aqsFilter);

        [overload("CreateFromIdAsync")]
        // Disable async-async due to caller-mutable [in] parameter
        [remote_sync]
        HRESULT CreateFromIdAsyncWithKindAndAdditionalProperties(
            [in] HSTRING deviceId,
            [in] IIterable<HSTRING> *additionalProperties,
            [in] DeviceInformationKind kind,
            [out, retval] Windows.Foundation.IAsyncOperation<DeviceInformation*> **asyncOp);

        [overload("FindAllAsync")]
        // Disable async-async due to caller-mutable [in] parameter
        [remote_sync]
        HRESULT FindAllAsyncWithKindAqsFilterAndAdditionalProperties(
            [in, unique] HSTRING aqsFilter,
            [in] IIterable<HSTRING> *additionalProperties,
            [in] DeviceInformationKind kind,
            [out, retval] Windows.Foundation.IAsyncOperation<DeviceInformationCollection*> **asyncOp);

        [overload("CreateWatcher")]
        HRESULT CreateWatcherWithKindAqsFilterAndAdditionalProperties(
            [in, unique] HSTRING aqsFilter,
            [in] IIterable<HSTRING> *additionalProperties,
            [in] DeviceInformationKind kind,
            [out, retval] DeviceWatcher **watcher);
    }

Document Details

⚠ Do not edit this section. It is required for learn.microsoft.com ➟ GitHub issue linking.

stevewhims commented 1 year ago

Thanks, @smadasam! I'll get on with this asap. Meanwhile, let's take it to internal email for convenience of comms, and I'll go ahead and close this. I'll return here and update this thread when I'm done.

Thanks! -Steve

stevewhims commented 1 year ago

UPDATE: The request changes are now live in the docs.

Thanks! -Steve