fxdeviceinterfaceapi.cpp

Go to the documentation of this file.

/*++

Copyright (c) Microsoft Corporation

Module Name:

    FxDeviceInterfaceAPI.cpp

Abstract:

    This module implements the device interface object external APIs

Author:




Environment:

    kernel and user mode

Revision History:

--*/

#include "fxsupportpch.hpp"

extern "C" {
// #include "FxDeviceInterfaceAPI.tmh"
}

//
// extern "C" the entire file
//
extern "C" {

_Must_inspect_result_
__drv_maxIRQL(PASSIVE_LEVEL)
NTSTATUS
STDCALL
WDFEXPORT(WdfDeviceCreateDeviceInterface)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Device,
    __in
    CONST GUID *InterfaceClassGUID,
    __in_opt
    PCUNICODE_STRING ReferenceString
    )
/*++

Routine Description:
    Creates a device interface associated with the passed in device object

Arguments:
    Device - Handle which represents the device exposing the interface

    InterfaceGUID - GUID describing the interface being exposed

    ReferenceString - OPTIONAL string which allows the driver writer to
        distinguish between different exposed interfaces

Return Value:
    STATUS_SUCCESS or appropriate NTSTATUS code

  --*/
{
    DDI_ENTRY();

    SINGLE_LIST_ENTRY **ppPrev, *pCur;
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxDeviceInterface *pDeviceInterface;
    FxDevice *pDevice;
    FxPkgPnp* pPkgPnp;
    NTSTATUS status;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Device,
                                   FX_TYPE_DEVICE,
                                   (PVOID*) &pDevice,
                                   &pFxDriverGlobals);

    FxPointerNotNull(pFxDriverGlobals, InterfaceClassGUID);

    status = FxVerifierCheckIrqlLevel(pFxDriverGlobals, PASSIVE_LEVEL);
    if (!NT_SUCCESS(status)) {
        return status;
    }

    if (ReferenceString != NULL) {
        status = FxValidateUnicodeString(pFxDriverGlobals, ReferenceString);
        if (!NT_SUCCESS(status)) {
            return status;
        }
    }

    if (pDevice->IsLegacy()) {
        status = STATUS_INVALID_DEVICE_REQUEST;

        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGERROR,
            "WDFDEVICE %p is not a PNP device, device interface creation not "
            "allowed %!STATUS!", Device, status);

        return status;
    }

    pDeviceInterface = new(pFxDriverGlobals, PagedPool) FxDeviceInterface();

    if (pDeviceInterface == NULL) {
        status = STATUS_INSUFFICIENT_RESOURCES;

        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGERROR,
            "WDFDEVICE %p DeviceInterface object creation failed, %!STATUS!",
            Device, status);

        return status;
    }

    status = pDeviceInterface->Initialize(pFxDriverGlobals,
                                          InterfaceClassGUID,
                                          ReferenceString);

    if (!NT_SUCCESS(status)) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGERROR,
            "WDFDEVICE %p, DeviceInterface object initialization failed, %!STATUS!",
            Device, status );

        goto Done;
    }

    pPkgPnp = pDevice->m_PkgPnp;

    pPkgPnp->m_DeviceInterfaceLock.AcquireLock(pFxDriverGlobals);

    status = pDeviceInterface->Register(pDevice);

    if (NT_SUCCESS(status)) {
        //
        // Insert into the end of the list
        //
        ppPrev = &pPkgPnp->m_DeviceInterfaceHead.Next;
        pCur = pPkgPnp->m_DeviceInterfaceHead.Next;
        while (pCur != NULL) {
            ppPrev = &pCur->Next;
            pCur = pCur->Next;
        }

        *ppPrev = &pDeviceInterface->m_Entry;
    }

    pPkgPnp->m_DeviceInterfaceLock.ReleaseLock(pFxDriverGlobals);

Done:
    if (!NT_SUCCESS(status)) {
        delete pDeviceInterface;
        pDeviceInterface = NULL;
    }

    return status;
}

__drv_maxIRQL(PASSIVE_LEVEL)
VOID
STDCALL
WDFEXPORT(WdfDeviceSetDeviceInterfaceState)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Device,
    __in
    CONST GUID *InterfaceClassGUID,
    __in_opt
    PCUNICODE_STRING RefString,
    __in
    BOOLEAN State
    )
{
    DDI_ENTRY();

    PSINGLE_LIST_ENTRY ple;
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    NTSTATUS status;
    FxDevice* pDevice;
    FxPkgPnp* pPkgPnp;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Device,
                                   FX_TYPE_DEVICE,
                                   (PVOID*) &pDevice,
                                   &pFxDriverGlobals);

    FxPointerNotNull(pFxDriverGlobals, InterfaceClassGUID);

    status = FxVerifierCheckIrqlLevel(pFxDriverGlobals, PASSIVE_LEVEL);
    if (!NT_SUCCESS(status)) {
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        return;
    }

    if (RefString != NULL) {
        status = FxValidateUnicodeString(pFxDriverGlobals, RefString);
        if (!NT_SUCCESS(status)) {
            FxVerifierDbgBreakPoint(pFxDriverGlobals);
            return;
        }
    }

    if (pDevice->IsLegacy()) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGERROR,
            "WDFDEVICE %p is not a PNP device, device interfaces not allowed",
            Device);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        return;
    }

    pPkgPnp = pDevice->m_PkgPnp;

    pPkgPnp->m_DeviceInterfaceLock.AcquireLock(pFxDriverGlobals);

    //
    // Iterate over the interfaces and see if we have a match
    //
    for (ple = pPkgPnp->m_DeviceInterfaceHead.Next; ple != NULL; ple = ple->Next) {
        FxDeviceInterface *pDI;

        pDI = FxDeviceInterface::_FromEntry(ple);

        if (FxIsEqualGuid(&pDI->m_InterfaceClassGUID, InterfaceClassGUID)) {
            if (RefString != NULL) {
                if ((RefString->Length == pDI->m_ReferenceString.Length)
                    &&
                    (RtlCompareMemory(RefString->Buffer,
                                      pDI->m_ReferenceString.Buffer,
                                      RefString->Length) == RefString->Length)) {
                    //
                    // They match, carry on
                    //
                    DO_NOTHING();
                }
                else {
                    //
                    // The ref strings do not match, continue on in the search
                    // of the collection.
                    //
                    continue;
                }
            }
            else if (pDI->m_ReferenceString.Length > 0) {
                //
                // Caller didn't specify a ref string but this interface has
                // one, continue on in the search through the collection.
                //
                continue;
            }

            //
            // Set the state and break out of the loop because we found our
            // interface.
            //
            pDI->SetState(State);
            break;
        }
    }

    pPkgPnp->m_DeviceInterfaceLock.ReleaseLock(pFxDriverGlobals);
}

_Must_inspect_result_
__drv_maxIRQL(PASSIVE_LEVEL)
NTSTATUS
STDCALL
WDFEXPORT(WdfDeviceRetrieveDeviceInterfaceString)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFDEVICE Device,
    __in
    CONST GUID* InterfaceClassGUID,
    __in_opt
    PCUNICODE_STRING RefString,
    __in
    WDFSTRING String
    )
/*++

Routine Description:
    Returns the symbolic link value of the registered device interface.

Arguments:


Return Value:


  --*/

{
    DDI_ENTRY();

    PSINGLE_LIST_ENTRY ple;
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxDevice* pDevice;
    FxPkgPnp* pPkgPnp;
    FxString* pString;
    NTSTATUS status;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Device,
                                   FX_TYPE_DEVICE,
                                   (PVOID*) &pDevice,
                                   &pFxDriverGlobals );

    FxPointerNotNull(pFxDriverGlobals, InterfaceClassGUID);

    status = FxVerifierCheckIrqlLevel(pFxDriverGlobals, PASSIVE_LEVEL);
    if (!NT_SUCCESS(status)) {
        return status;
    }

    if (RefString != NULL) {
        status = FxValidateUnicodeString(pFxDriverGlobals, RefString);
        if (!NT_SUCCESS(status)) {
            return status;
        }
    }

    if (pDevice->IsLegacy()) {
        status = STATUS_INVALID_DEVICE_REQUEST;

        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGERROR,
            "WDFDEVICE %p is not a PNP device, device interface creation not "
            "allowed %!STATUS!", Device, status);

        return status;
    }

    FxObjectHandleGetPtr(pFxDriverGlobals,
                         String,
                         FX_TYPE_STRING,
                         (PVOID*) &pString);

    pPkgPnp = pDevice->m_PkgPnp;

    status = STATUS_OBJECT_NAME_NOT_FOUND;

    pPkgPnp->m_DeviceInterfaceLock.AcquireLock(pFxDriverGlobals);

    //
    // Iterate over the interfaces and see if we have a match
    //
    for (ple = pPkgPnp->m_DeviceInterfaceHead.Next;
         ple != NULL;
         ple = ple->Next) {
        FxDeviceInterface *pDI;

        pDI = FxDeviceInterface::_FromEntry(ple);

        if (FxIsEqualGuid(&pDI->m_InterfaceClassGUID, InterfaceClassGUID)) {
            if (RefString != NULL) {
                if ((RefString->Length == pDI->m_ReferenceString.Length)
                    &&
                    (RtlCompareMemory(RefString->Buffer,
                                      pDI->m_ReferenceString.Buffer,
                                      RefString->Length) == RefString->Length)) {
                    //
                    // They match, carry on
                    //
                    DO_NOTHING();
                }
                else {
                    //
                    // The ref strings do not match, continue on in the search
                    // of the collection.
                    //
                    continue;
                }
            }
            else if (pDI->m_ReferenceString.Length > 0) {
                //
                // Caller didn't specify a ref string but this interface has
                // one, continue on in the search through the collection.
                //
                continue;
            }

            status = pDI->GetSymbolicLinkName(pString);

            break;
        }
    }

    pPkgPnp->m_DeviceInterfaceLock.ReleaseLock(pFxDriverGlobals);

    return status;
}

} // extern "C"