ifxhascallbacks.hpp

Go to the documentation of this file.

 
/*++
 
Copyright (c) Microsoft. All rights reserved.
 
Module Name:
 
    IFxHasCallbacks.hpp
 
Abstract:
 
    Interface that objects with device driver callbacks and
    constraints implement
 
Author:
 
 
 
Environment:
 
    Both kernel and user mode
 
Revision History:
 
--*/
 
#ifndef __IFX_HASCALLBACKS_HPP
#define __IFX_HASCALLBACKS_HPP
 
//
// Objects that have callbacks into the device driver
// (implemented by deriving a delegate from FxCallback), may
// have constraints specified by the device driver when the object
// or driver was created.
//
// These constraints control synchronization, and execution (IRQL) level
// on callbacks to the device driver.
//
// To provide synchronization an FxCallbackLock may be implemented, at
// either DISPATCH (spinlock) or PASSIVE (mutex lock) level depending
// on whether a passive level constraint is in effect.
//
// This interface allows the constraints, and any associated locks
// to be retrieved in a generic fashion from the object, such as
// for implementing the WdfObjectAcquireLock/WdfObjectReleaseLock APIs.
//
 
class IFxHasCallbacks {
 
public:
 
    //
    // Returns the constraints in effect for the object.
    //
    virtual
    VOID
    GetConstraints(
        __out WDF_EXECUTION_LEVEL*       ExecutionLevel,
        __out WDF_SYNCHRONIZATION_SCOPE* SynchronizationScope
        ) = 0;
 
    //
    // This returns the callback lock in effect for the object that
    // will serialize with its event callbacks to the device driver.
    //
    // If no callback locks are in effect, the return value is NULL.
    //
    // The type of FxCallbackLock returned may be a spinlock, or mutex
    // type depending on whether the object has a passive level callback
    // constraint in effect.
    //
    // In addition, optionally returns the object that contains the lock
    // providing any serialization constraint. This allows reference counting
    // the object who owns the lock, which may not be the target
    // object. An example would be a child object sharing its parent
    // FxDevice's synchronziation lock.
    //
    _Must_inspect_result_
    virtual
    FxCallbackLock*
    GetCallbackLockPtr(
        __out_opt FxObject** LockObject
        ) = 0;
};
 
#endif // __IFX_HASCALLBACKS_HPP