fxhandle.h

Go to the documentation of this file.

/*++
 
Copyright (c) Microsoft Corporation
 
Module Name:
 
    fxhandle.h
 
Abstract:
 
    Private interfaces for Driver Frameworks handle functions.
 
Author:
 
 
 
 
Environment:
 
    Both kernel and user mode
 
Revision History:
 
 
--*/
 
#ifndef _WDFPHANDLE_H_
#define _WDFPHANDLE_H_
 
struct FxContextHeader;
 
struct FxContextHeader {
    //
    // Backpointer to the object that this is a context for
    //
    FxObject* Object;
 
    //
    // Next context in the chain
    //
    FxContextHeader* NextHeader;
 
    //
    // Function to call when object is deleted
    //
    PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback;
 
    //
    // Function to call when the object's memory is destroyed
    // when the last reference count goes to zero
    //
    PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback;
 
    //
    // Type associated with this context
    //
    PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo;
 
    //
    // Start of client's context
    //
    DECLSPEC_ALIGN(MEMORY_ALLOCATION_ALIGNMENT) ULONG_PTR Context[1];
};
 
//
// We want all the way up to the aligned field, but not the field itself
//
#define FX_CONTEXT_HEADER_SIZE FIELD_OFFSET(FxContextHeader, Context)
 
#define COMPUTE_RAW_OBJECT_SIZE(_rawObjectSize) \
    ((USHORT) WDF_ALIGN_SIZE_UP(_rawObjectSize, MEMORY_ALLOCATION_ALIGNMENT))
 
//
// Computes the size required for a fixed size object plus any extra buffer space
// it requires.  The extra buffer space is aligned on a process natural boundary.
//
#define COMPUTE_OBJECT_SIZE(_rawObjectSize, _extraSize) \
   (COMPUTE_RAW_OBJECT_SIZE(_rawObjectSize) + (USHORT) WDF_ALIGN_SIZE_UP(_extraSize, MEMORY_ALLOCATION_ALIGNMENT))
 
//
// Gets size of the context associated with the specified attributes structure.
//
size_t
FxGetContextSize(
    __in_opt    PWDF_OBJECT_ATTRIBUTES Attributes
    );
 
//
// Computes the total size of an object taking into account its fixed size,
// any additional size after the fixed, and an object header, so the memory looks
// like:
//
// Object
// additional optional memory
// WDF_HANDLE_HEADER
//
_Must_inspect_result_
NTSTATUS
FxCalculateObjectTotalSize2(
    __in        PFX_DRIVER_GLOBALS FxDriverGlobals,
    __in        USHORT RawObjectSize,
    __in        USHORT ExtraSize,
    __in        size_t ContextSize,
    __out       size_t* Total
    );
 
_Must_inspect_result_
NTSTATUS
FxCalculateObjectTotalSize(
    __in        PFX_DRIVER_GLOBALS FxDriverGlobals,
    __in        USHORT RawObjectSize,
    __in        USHORT ExtraSize,
    __in_opt    PWDF_OBJECT_ATTRIBUTES Attributes,
    __out       size_t* Total
    );
 
PVOID
FxObjectHandleAlloc(
    __in        PFX_DRIVER_GLOBALS FxDriverGlobals,
    __in        POOL_TYPE PoolType,
    __in        size_t Size,
    __in        ULONG Tag,
    __in_opt    PWDF_OBJECT_ATTRIBUTES Attributes,
    __in        USHORT ExtraSize,
    __in        FxObjectType ObjectType
    );
 
VOID
FxContextHeaderInit(
    __in        FxContextHeader* Header,
    __in        FxObject* Object,
    __in_opt    PWDF_OBJECT_ATTRIBUTES Attributes
    );
 
PVOID
FxObjectAndHandleHeaderInit(
    __in        PFX_DRIVER_GLOBALS FxDriverGlobals,
    __in        PVOID AllocationStart,
    __in        USHORT ObjectSize,
    __in_opt    PWDF_OBJECT_ATTRIBUTES Attributes,
    __in        FxObjectType ObjectType
    );
 
VOID
__inline
FxObjectHandleCreate(
    __in  FxObject* Object,
    __out PWDFOBJECT Handle
    )
{
#if FX_SUPER_DBG
    if (Object->GetDriverGlobals()->FxVerifierHandle) {
 
 
 
 
 
 
        ASSERT(Object->GetObjectSize() > 0);
        ASSERT(Object == Object->GetContextHeader()->Object);
    }
#endif
 
    ASSERT((((ULONG_PTR) Object) & FxHandleFlagMask) == 0x0);
    *Handle = Object->GetObjectHandle();
}
 
/*++
 
Routine Description:
 
    Retrieves the object pointer from the handle if valid.
 
    This does not change an objects reference count.
 
Arguments:
 
    handle - The object handle created by WdfObjectCreateHandle
 
    type - Type of the object from FxTypes.h
 
    ppObj - Pointer to location to store the returned object.
 
Returns:
 
    NTSTATUS
 
--*/
 
VOID
FxObjectHandleGetPtrQI(
    __in FxObject* Object,
    __out PVOID* PPObject,
    __in WDFOBJECT Handle,
    __in WDFTYPE Type,
    __in WDFOBJECT_OFFSET Offset
    );
 
_Must_inspect_result_
NTSTATUS
FxObjectAllocateContext(
    __in        FxObject*               Object,
    __in        PWDF_OBJECT_ATTRIBUTES  Attributes,
    __in        BOOLEAN                 AllowCallbacksOnly,
    __deref_opt_out PVOID*              Context
    );
 
__inline
BOOLEAN
FxObjectCheckType(
    __in FxObject* Object,
    __in WDFTYPE  Type
    )
/*++
 
Routine Description:
    Checks if the FxObject is of a the Type.
 
Arguments:
    FxObject - the object being checked
    Type - The type value to be checked
 
Returns:
    TRUE if the Object is of the type 'Type'
    FALSE otherwise
  --*/
{
    NTSTATUS status;
    PVOID tmpObject;
    FxQueryInterfaceParams params = {&tmpObject, Type, 0};
 
    //
    // Do a quick non virtual call for the type and only do the slow QI if
    // the first types do not match
    //
 
    if (Object->GetType() == Type) {
        return TRUE;
    }
 
    status = Object->QueryInterface(&params);
 
    if (!NT_SUCCESS(status)) {
        return FALSE;
    }
 
    return TRUE;
 
}
 
__inline
VOID
FxObjectHandleGetPtr(
    __in PFX_DRIVER_GLOBALS FxDriverGlobals,
    __in WDFOBJECT Handle,
    __in WDFTYPE Type,
    __out PVOID* PPObject
    )
/*++
 
Routine Description:
    Converts an externally facing WDF handle into its internal object.
 
Arguments:
    FxDriverGlobals - caller's globals
    Handle - handle to convert into an object
    Type - required type of the underlying object
    PPObject - pointer to receive the underlying object
 
  --*/
{
    WDFOBJECT_OFFSET offset;
    FxObject* pObject;
 
    if (Handle == NULL) {
 
 
 
 
 
        FxVerifierBugCheck(FxDriverGlobals,
                           WDF_INVALID_HANDLE,
                           (ULONG_PTR) Handle,
                           Type);
 
        /* NOTREACHED */
        return;
    }
 
    offset = 0;
    pObject = FxObject::_GetObjectFromHandle(Handle, &offset);
 
    //
    // The only DDI you can call on an object which has a ref count of zero is
    // WdfObjectGetTypedContextWorker().
    //
    ASSERT(pObject->GetRefCnt() > 0);
 
    //
    // Do a quick non virtual call for the type and only do the slow QI if
    // the first types do not match
    //
    if (pObject->GetType() == Type) {
        *PPObject = pObject;
        ASSERT(offset == 0x0);
        return;
    }
    else {
        FxObjectHandleGetPtrQI(pObject, PPObject, Handle, Type, offset);
    }
}
 
__inline
VOID
FxObjectHandleGetPtrOffset(
    __in PFX_DRIVER_GLOBALS FxDriverGlobals,
    __in WDFOBJECT Handle,
    __in WDFTYPE Type,
    __out PVOID* PPObject,
    __out PWDFOBJECT_OFFSET Offset
    )
/*++
 
Routine Description:
    This function  probably should be removed and the optional Offset paramter
    moved into the signature for  FxObjectHandleGetPtr(). The distinction
    between these 2 functions was important when both of them were *not*
    FORCEINLINE functions (since there was an additional parameter to push onto
    the stack).  Now that they are both __inlined, there is no longer a
    parameter to push, eliminating this optimization.
 
Arguments:
    FxDriverGlobals - caller's globals
    Handle - handle to convert into an object
    Type - required type of the underlying object
    PPObject - pointer to receive the underlying object
    Offset - offset into the object which the handle resided.  Nearly all objects
        will have a zero offset
 
  --*/
{
    FxObject* pObject;
 
    if (Handle == NULL) {
 
 
 
 
 
        FxVerifierBugCheck(FxDriverGlobals,
                           WDF_INVALID_HANDLE,
                           (ULONG_PTR) Handle,
                           Type);
 
        /* NOTREACHED */
        return;
    }
 
    *Offset = 0;
    pObject = FxObject::_GetObjectFromHandle(Handle, Offset);
 
    //
    // The only DDI you can call on an object which has a ref count of zero is
    // WdfObjectGetTypedContextWorker().
    //
    ASSERT(pObject->GetRefCnt() > 0);
 
    //
    // Do a quick non virtual call for the type and only do the slow QI if
    // the first types do not match
    //
    if (pObject->GetType() == Type) {
        *PPObject = pObject;
        ASSERT(*Offset == 0x0);
        return;
    }
    else {
        FxObjectHandleGetPtrQI(pObject, PPObject, Handle, Type, *Offset);
    }
}
 
VOID
__inline
FxObjectHandleGetPtrAndGlobals(
    __in  PFX_DRIVER_GLOBALS CallersGlobals,
    __in  WDFOBJECT Handle,
    __in  WDFTYPE   Type,
    __out PVOID*    PPObject,
    __out PFX_DRIVER_GLOBALS* ObjectGlobals
    )
/*++
 
Routine Description:
    Converts an externally facing WDF handle into its internal object.
 
Arguments:
    FxDriverGlobals - caller's globals
    Handle - handle to convert into an object
    Type - required type of the underlying object
    PPObject - pointer to receive the underlying object
    ObjectGlobals - pointer to receive the underlying object's globals.
 
  --*/
{
    //
    // All FX_TYPEs except for IFX_TYPE_MEMORY derive from FxObject, so our cast
    // below will work with all types but IFX_TYPE_MEMORY (in which case the caller
    // should call FxObjectHandleGetPtr and then get the globals on their own
    // from the IFxMemory interface).
    //
    ASSERT(Type != IFX_TYPE_MEMORY);
 
    FxObjectHandleGetPtr(CallersGlobals,
                         Handle,
                         Type,
                         PPObject);
 
    *ObjectGlobals = ((FxObject*) (*PPObject))->GetDriverGlobals();
}
 
VOID
__inline
FxObjectHandleGetGlobals(
    __in  PFX_DRIVER_GLOBALS CallersGlobals,
    __in  WDFOBJECT Handle,
    __out PFX_DRIVER_GLOBALS* ObjectGlobals
    )
/*++
 
Routine Description:
    Converts an externally facing WDF handle into its internal object and
    returns its globals.
 
Arguments:
    FxDriverGlobals - caller's globals
    Handle - handle to convert into an object
    ObjectGlobals - pointer to receive the underlying object's globals.
 
  --*/
{
    PVOID pObject;
 
    FxObjectHandleGetPtrAndGlobals(CallersGlobals,
                                   Handle,
                                   FX_TYPE_OBJECT,
                                   &pObject,
                                   ObjectGlobals);
 
    UNREFERENCED_PARAMETER(pObject);
}
 
#endif // _WDFPHANDLE_H_