fxworkitemapi.cpp

Go to the documentation of this file.

/*++

Copyright (c) Microsoft Corporation

Module Name:

    FxWorkItemApi.cpp

Abstract:

    This implements the WDFWORKITEM API's

Author:



Environment:

    Both kernel and user mode

Revision History:


--*/

#include "coreprivshared.hpp"

#include "fxworkitem.hpp"

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


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

_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
NTSTATUS
STDCALL
WDFEXPORT(WdfWorkItemCreate)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    PWDF_WORKITEM_CONFIG Config,
    __in
    PWDF_OBJECT_ATTRIBUTES Attributes,
    __out
    WDFWORKITEM* WorkItem
    )

/*++

Routine Description:

    Create a WorkItem object that will call the supplied function with
    context when it fires. It returns a handle to the WDFWORKITEM object.

Arguments:

    Config - Pointer to WDF_WORKITEM_CONFIG structure

    Attributes - WDF_OBJECT_ATTRIBUTES to set the parent object and to request
                 a context memory allocation,  and a DestroyCallback.

    WorkItem - Pointer to the created WDFWORKITEM handle.

Returns:

    STATUS_SUCCESS - A WDFWORKITEM handle has been created.

    The WDFWORKITEM will be automatically deleted when the object it is
    associated with is deleted.

Notes:

    The WDFWORKITEM object is deleted either when the DEVICE or QUEUE it is
    associated with is deleted, or WdfObjectDelete is called.

    If the WDFWORKITEM is used to access WDM objects, a Cleanup callback should
    be registered to allow references to be released.

--*/

{
    DDI_ENTRY();

    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxObject* pParent;
    NTSTATUS status;

    pFxDriverGlobals = GetFxDriverGlobals(DriverGlobals);
    status = FxValidateObjectAttributesForParentHandle(pFxDriverGlobals,
                                                       Attributes,
                                                       FX_VALIDATE_OPTION_PARENT_REQUIRED);
    if (!NT_SUCCESS(status)) {
        return status;
    }

    FxObjectHandleGetPtrAndGlobals(pFxDriverGlobals,
                                   Attributes->ParentObject,
                                   FX_TYPE_OBJECT,
                                   (PVOID*)&pParent,
                                   &pFxDriverGlobals);

    FxPointerNotNull(pFxDriverGlobals, Config);
    FxPointerNotNull(pFxDriverGlobals, WorkItem);

    if (Config->Size != sizeof(WDF_WORKITEM_CONFIG)) {
        status = STATUS_INFO_LENGTH_MISMATCH;

        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "WDF_WORKITEM_CONFIG Size got %d, expected %d, %!STATUS!",
            Config->Size, sizeof(WDF_WORKITEM_CONFIG), status);

        return status;
    }

    if (Config->EvtWorkItemFunc == NULL) {
        status = STATUS_INVALID_PARAMETER;

        DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                            "Supplied EvtWorkItemFunc == NULL, %!STATUS!",
                            status);

        return status;
    }

    //
    // The parent for FxWorkItem is explicitly part of the API, and ties
    // synchronization and lifetime.
    //
    status = FxValidateObjectAttributes(pFxDriverGlobals, Attributes);
    if (!NT_SUCCESS(status)) {
        return status;
    }

    return FxWorkItem::_Create(
        pFxDriverGlobals, Config, Attributes, pParent, WorkItem);
}

__drv_maxIRQL(DISPATCH_LEVEL)
VOID
STDCALL
WDFEXPORT(WdfWorkItemEnqueue)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFWORKITEM WorkItem
    )
/*++

Routine Description:

    Enqueue a WorkItem to execute.

Arguments:

    WorkItem - Handle to WDFWORKITEM

Returns:

    None

--*/
{
    DDI_ENTRY();

    FxWorkItem* pFxWorkItem;

    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         WorkItem,
                         FX_TYPE_WORKITEM,
                         (PVOID*)&pFxWorkItem);

    pFxWorkItem->Enqueue();
}

__drv_maxIRQL(DISPATCH_LEVEL)
WDFOBJECT
STDCALL
WDFEXPORT(WdfWorkItemGetParentObject)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFWORKITEM WorkItem
    )

/*++

Routine Description:

    Return the Object handle supplied to WdfWorkItemCreate

Arguments:

    WDFWORKITEM - Handle to WDFWORKITEM object created with WdfWorkItemCreate.

Returns:

    Handle to the framework object that is the specified work-item object's
    parent object.

--*/

{
    DDI_ENTRY();

    FxWorkItem* pFxWorkItem;

    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         WorkItem,
                         FX_TYPE_WORKITEM,
                         (PVOID*)&pFxWorkItem);

    return pFxWorkItem->GetAssociatedObject();
}

__drv_maxIRQL(PASSIVE_LEVEL)
VOID
STDCALL
WDFEXPORT(WdfWorkItemFlush)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFWORKITEM WorkItem
    )
/*++

Routine Description:

    Wait until any outstanding workitems have completed

Arguments:

    WorkItem - Handle to WDFWORKITEM

Returns:

    None

--*/
{
    DDI_ENTRY();

    FxWorkItem* pFxWorkItem;

    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         WorkItem,
                         FX_TYPE_WORKITEM,
                         (PVOID*)&pFxWorkItem);

    //
    // Use the object's globals, not the caller's
    //
    if (!NT_SUCCESS(FxVerifierCheckIrqlLevel(pFxWorkItem->GetDriverGlobals(),
                                            PASSIVE_LEVEL))) {
        return;
    }

    pFxWorkItem->FlushAndWait();
}

} // extern "C"