fxtimerapi.cpp

Go to the documentation of this file.

/*++
 
Copyright (c) Microsoft Corporation
 
Module Name:
 
    FxTimerApi.cpp
 
Abstract:
 
    This implements the WDFTIMER API's
 
Author:
 
 
 
Environment:
 
    Both kernel and user mode
 
Revision History:
 
 
--*/
 
#include "coreprivshared.hpp"
 
#include "fxtimer.hpp"
 
extern "C" {
// #include "FxTimerApi.tmh"
}
 
//
// extern "C" the entire file
//
extern "C" {
 
_Must_inspect_result_
__drv_maxIRQL(DISPATCH_LEVEL)
NTSTATUS
STDCALL
WDFEXPORT(WdfTimerCreate)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    PWDF_TIMER_CONFIG Config,
    __in
    PWDF_OBJECT_ATTRIBUTES Attributes,
    __out
    WDFTIMER * Timer
    )
 
/*++
 
Routine Description:
 
    Create a TIMER object that will call the supplied function
    when it fires. It returns a handle to the WDFTIMER object.
 
Arguments:
 
    Config     - WDF_TIMER_CONFIG structure.
 
    Attributes - WDF_OBJECT_ATTRIBUTES to set the parent object, to request
                 a context memory allocation and a DestroyCallback.
 
    Timer - Pointer to location to return the resulting WDFTIMER handle.
 
Returns:
 
    STATUS_SUCCESS - A WDFTIMER handle has been created.
 
Notes:
 
    The WDFTIMER object is deleted either when the DEVICE or QUEUE it is
    associated with is deleted, or WdfObjectDelete is called.
 
--*/
 
{
    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, Timer);
 
    if (Config->Size != sizeof(WDF_TIMER_CONFIG) &&
        Config->Size != sizeof(WDF_TIMER_CONFIG_V1_7) &&
        Config->Size != sizeof(WDF_TIMER_CONFIG_V1_11)) {
        status = STATUS_INFO_LENGTH_MISMATCH;
 
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "PWDF_TIMER_CONFIG Size %d, expected %d, %!STATUS!",
            Config->Size, sizeof(WDF_TIMER_CONFIG), status);
 
        return status;
    }
 
    if (Config->Period > MAXLONG) {
        status = STATUS_INVALID_PARAMETER;
 
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "Period value %u for a periodic timer cannot be greater than "
            "MAXLONG, %!STATUS!", Config->Period, status);
 
        return status;
    }
 
    //
    // For version 1.13 and higher, the tolerable delay could
    // go upto MAXULONG
    //
    if (Config->Size > sizeof(WDF_TIMER_CONFIG_V1_7) &&
        (pFxDriverGlobals->IsVersionGreaterThanOrEqualTo(1,13) == FALSE)) {
        if (Config->TolerableDelay > MAXLONG) {
 
            status = STATUS_INVALID_PARAMETER;
 
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                "TolerableDelay value %u cannot be greater than MAXLONG, "
                "%!STATUS!", Config->TolerableDelay, status);
 
            return status;
        }
    }
 
    if (Config->Size > sizeof(WDF_TIMER_CONFIG_V1_11)) {
 
#if (FX_CORE_MODE == FX_CORE_USER_MODE)
        if (Config->UseHighResolutionTimer) {
 
            status = STATUS_NOT_IMPLEMENTED;
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                "UseHighResolutionTimer option is not supported for UMDF "
                "%!STATUS!", status);
            return status;
        }
#endif
 
        if ((Config->TolerableDelay > 0) &&
            (Config->UseHighResolutionTimer)) {
 
            status = STATUS_INVALID_PARAMETER;
 
            DoTraceLevelMessage(
                pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
                "UseHighResolutionTimer option sepcified with non zero tolerable delay %u "
                "%!STATUS!", Config->TolerableDelay, status);
 
            return status;
        }
    }
 
    status = FxValidateObjectAttributes(pFxDriverGlobals,
                                Attributes,
                                FX_VALIDATE_OPTION_EXECUTION_LEVEL_ALLOWED);
    if (!NT_SUCCESS(status)) {
        return status;
    }
 
    if (Config->Period  > 0 &&
        Attributes->ExecutionLevel == WdfExecutionLevelPassive) {
        status = STATUS_NOT_SUPPORTED;
 
        DoTraceLevelMessage(
            pFxDriverGlobals, TRACE_LEVEL_ERROR, TRACINGDEVICE,
            "Passive level periodic timer is not supported. "
            "Use one shot timer and queue the next timer from the callback "
            "or use a dedicated thread, %!STATUS!",
            status);
 
        return status;
    }
 
    return FxTimer::_Create(pFxDriverGlobals, Config, Attributes, pParent, Timer);
}
 
__drv_maxIRQL(DISPATCH_LEVEL)
BOOLEAN
STDCALL
WDFEXPORT(WdfTimerStart)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFTIMER Timer,
    __in
    LONGLONG DueTime
    )
 
/*++
 
Routine Description:
 
    Enqueue the TIMER to run at the specified time.
 
Arguments:
 
    WDFTIMER - Handle to WDFTIMER object created with WdfTimerCreate.
 
    DueTime - Time to execute
 
Returns:
 
    TRUE if the timer object was in the system's timer queue
 
--*/
 
{
    DDI_ENTRY();
 
    FxTimer* pFxTimer;
    LARGE_INTEGER li;
 
    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         Timer,
                         FX_TYPE_TIMER,
                         (PVOID*)&pFxTimer);
 
    li.QuadPart = DueTime;
 
    return pFxTimer->Start(li);
}
 
__drv_when(Wait == __true, __drv_maxIRQL(PASSIVE_LEVEL))
__drv_when(Wait == __false, __drv_maxIRQL(DISPATCH_LEVEL))
BOOLEAN
STDCALL
WDFEXPORT(WdfTimerStop)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFTIMER Timer,
    __in
    BOOLEAN  Wait
    )
 
/*++
 
Routine Description:
 
    Stop the TIMER
 
Arguments:
 
    WDFTIMER - Handle to WDFTIMER object created with WdfTimerCreate.
 
Returns:
 
    TRUE if the timer object was in the system's timer queue
 
--*/
 
{
    DDI_ENTRY();
 
    PFX_DRIVER_GLOBALS pFxDriverGlobals;
    FxTimer* pFxTimer;
    NTSTATUS status;
 
    FxObjectHandleGetPtrAndGlobals(GetFxDriverGlobals(DriverGlobals),
                                   Timer,
                                   FX_TYPE_TIMER,
                                   (PVOID*)&pFxTimer,
                                   &pFxDriverGlobals);
 
    if (Wait) {
        status = FxVerifierCheckIrqlLevel(pFxDriverGlobals, PASSIVE_LEVEL);
        if (!NT_SUCCESS(status)) {
            return FALSE;
        }
    }
 
    return pFxTimer->Stop(Wait);
}
 
__drv_maxIRQL(DISPATCH_LEVEL)
WDFOBJECT
STDCALL
WDFEXPORT(WdfTimerGetParentObject)(
    __in
    PWDF_DRIVER_GLOBALS DriverGlobals,
    __in
    WDFTIMER Timer
    )
 
/*++
 
Routine Description:
 
    Return the Parent Object handle supplied to WdfTimerCreate
 
Arguments:
 
    WDFTIMER - Handle to WDFTIMER object created with WdfTimerCreate.
 
Returns:
 
    Handle to the framework object that is the specified timer object's
    parent object
 
--*/
 
{
    DDI_ENTRY();
 
    FxTimer* pFxTimer;
 
    FxObjectHandleGetPtr(GetFxDriverGlobals(DriverGlobals),
                         Timer,
                         FX_TYPE_TIMER,
                         (PVOID*)&pFxTimer);
 
    return pFxTimer->GetObject();
}
 
} // extern "C"