fxobjectapi.cpp

Go to the documentation of this file.

/*++

Copyright (c) Microsoft Corporation

Module Name:

    FxObjectApi.cpp

Abstract:


Author:


Environment:

    kernel mode only

Revision History:

--*/

#include "fxobjectpch.hpp"

extern "C" {

#if defined(EVENT_TRACING)
#include "FxObjectAPI.tmh"
#endif

}


extern "C" {

__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
VOID
STDCALL
WDFEXPORT(WdfObjectReferenceActual)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFOBJECT Object,
    __in_opt
    PVOID Tag,
    __in
    LONG Line,
    __in
    PSTR File
    )
/*++

Routine Description:
    Adds an explicit reference that was taken on an object.

Arguments:
    Object - the object to reference
    Tag - The tag used to track this reference.  If not matched on dereference,
          a breakpoint is hit.  Tags are only tracked when enabled via the
          registry or WDF verifier.
    Line - the caller's line number making the call
    File - the caller's file name making the call

Return Value:
    None.  We do not return the current reference count.

  --*/
{
    DDI_ENTRY();

    FxPointerNotNull(GetFxDriverGlobals(DriverGlobals), Object);

    FxObject::_ReferenceActual(
        Object,
        Tag,
        Line,
        File
        );
}

__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
VOID
STDCALL
WDFEXPORT(WdfObjectDereferenceActual)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFOBJECT Object,
    __in_opt
    PVOID Tag,
    __in
    LONG Line,
    __in
    PSTR File
    )
/*++

Routine Description:
    Removes an explicit reference that was taken on an object.

Arguments:
    Object - the object to dereference
    Tag - The tag used when referencing the Object, if not matched, a breakpoint
          is hit.  Tags are only tracked when enabled via the registry or
          WDF verifier.
    Line - the caller's line number making the call
    File - the caller's file name making the call

Return Value:
    None.  We do not return the current reference count.

  --*/
{
    DDI_ENTRY();

    FxPointerNotNull(GetFxDriverGlobals(DriverGlobals), Object);

    FxObject::_DereferenceActual(
        Object,
        Tag,
        Line,
        File
        );
}

FxCallbackLock*
FxGetCallbackLock(
    FxObject* Object
    )

/*++

Routine Description:

    This returns the proper FxCallbackLock pointer
    for the object.

    It returns NULL if an FxCallbackLock is not valid
    for the object.

Arguments:

    Object - Pointer to object to retrieve the callback lock pointer for

Returns:

    FxCallbackLock*

--*/

{
    NTSTATUS status;
    IFxHasCallbacks* ihcb;
    FxQueryInterfaceParams params = { (PVOID*) &ihcb, FX_TYPE_IHASCALLBACKS, 0 };

    ihcb = NULL;

    //
    // Query the object for the IFxHasCallbacks interface. Objects that
    // have callback locks must support this interface.
    //
    status = Object->QueryInterface(&params);
    if (!NT_SUCCESS(status)) {
        return NULL;
    }

    return ihcb->GetCallbackLockPtr(NULL);
}

__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
VOID
STDCALL
WDFEXPORT(WdfObjectAcquireLock)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    _Requires_lock_not_held_(_Curr_)
    _Acquires_lock_(_Curr_)
    WDFOBJECT Object
    )
{
    DDI_ENTRY();

    FxObject* pObject;
    FxCallbackLock* pLock;
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    KIRQL irql;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Object,
                                   FX_TYPE_OBJECT,
                                   (PVOID*)&pObject,
                                   &pFxDriverGlobals);

    //
    // If Lock Verifier on, validate whether its correct to
    // make this call
    //
    if (pFxDriverGlobals->FxVerifierLock) {
        //
        // Check IRQL Level, etc.
        //
    }

    //
    // Get the CallbackLock for the object
    //
    pLock = FxGetCallbackLock(pObject);

    if (pLock == NULL) {
        DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                            "Invalid to call on WDFOBJECT 0x%p", Object);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        FxVerifierBugCheck(pFxDriverGlobals,
                           WDF_INVALID_LOCK_OPERATION,
                           (ULONG_PTR)Object,
                           (ULONG_PTR)NULL
                           );
        return;
    }

    pLock->Lock(&irql);
    pLock->m_PreviousIrql = irql;

    return;
}


__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
VOID
STDCALL
WDFEXPORT(WdfObjectReleaseLock)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    _Requires_lock_held_(_Curr_)
    _Releases_lock_(_Curr_)
    WDFOBJECT Object
    )
{
    DDI_ENTRY();

    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxObject* pObject;
    FxCallbackLock* pLock;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Object,
                                   FX_TYPE_OBJECT,
                                   (PVOID*)&pObject,
                                   &pFxDriverGlobals);

    //
    // If Lock Verifier on, validate whether its correct to
    // make this call
    //
    if (pFxDriverGlobals->FxVerifierLock) {
        //
        // Check IRQL Level, etc.
        //
    }

    //
    // Get the CallbackLock for the object
    //
    pLock = FxGetCallbackLock(pObject);
    if (pLock == NULL) {
        DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                            "Invalid to call on WDFOBJECT 0x%p",Object);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
        FxVerifierBugCheck(pFxDriverGlobals,
                           WDF_INVALID_LOCK_OPERATION,
                           (ULONG_PTR)Object,
                           (ULONG_PTR)NULL
                           );
        return;
    }

    pLock->Unlock(pLock->m_PreviousIrql);

    return;
}

__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
VOID
STDCALL
WDFEXPORT(WdfObjectDelete)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFOBJECT Object
    )
{
    DDI_ENTRY();

    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxObject* pObject;

    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Object,
                                   FX_TYPE_OBJECT,
                                   (PVOID*)&pObject,
                                   &pFxDriverGlobals);

    //
    // The object may not allow the Delete DDI
    //
    if (pObject->IsNoDeleteDDI()) {
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "Attempt to Delete an Object Which does not allow WdfDeleteObject "
            "Handle 0x%p, %!STATUS!",
            Object, STATUS_CANNOT_DELETE);
        FxVerifierDbgBreakPoint(pFxDriverGlobals);
    }
    else {
        pObject->DeleteObject();
    }
}

_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
WDFAPI
NTSTATUS
STDCALL
WDFEXPORT(WdfObjectQuery)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFOBJECT Object,
    __in
    CONST GUID* Guid,
    __in
    ULONG QueryBufferLength,
    __out_bcount(QueryBufferLength)
    PVOID QueryBuffer
    )

/*++

Routine Description:

    Query the object handle for specific information

    This allows dynamic extensions to DDI's.

    Currently, it is used to allow test hooks for verification
    which are not available in a production release.

Arguments:

    Object - Handle to object for the query

    Guid - GUID to represent the information/DDI to query for

    QueryBufferLength - Length of QueryBuffer to return data in

    QueryBuffer - Pointer to QueryBuffer

Returns:

    NTSTATUS

--*/

{
    DDI_ENTRY();

    FxObject* p;

    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         Object,
                         FX_TYPE_OBJECT,
                         (PVOID*)&p);

    return FxObject::_ObjectQuery(p,
                                  Guid,
                                  QueryBufferLength,
                                  QueryBuffer);
}

} // extern "C" for all functions