ReactOS 0.4.15-dev-5666-gc548b97
fxhandle.h
Go to the documentation of this file.
1/*++
2
3Copyright (c) Microsoft Corporation
4
5Module Name:
6
7 fxhandle.h
8
9Abstract:
10
11 Private interfaces for Driver Frameworks handle functions.
12
13Author:
14
15
16
17
18Environment:
19
20 Both kernel and user mode
21
22Revision History:
23
24
25--*/
26
27#ifndef _WDFPHANDLE_H_
28#define _WDFPHANDLE_H_
29
60struct FxContextHeader;
61
63 //
64 // Backpointer to the object that this is a context for
65 //
67
68 //
69 // Next context in the chain
70 //
72
73 //
74 // Function to call when object is deleted
75 //
77
78 //
79 // Function to call when the object's memory is destroyed
80 // when the last reference count goes to zero
81 //
83
84 //
85 // Type associated with this context
86 //
88
89 //
90 // Start of client's context
91 //
93};
94
95//
96// We want all the way up to the aligned field, but not the field itself
97//
98#define FX_CONTEXT_HEADER_SIZE FIELD_OFFSET(FxContextHeader, Context)
99
100#define COMPUTE_RAW_OBJECT_SIZE(_rawObjectSize) \
101 ((USHORT) WDF_ALIGN_SIZE_UP(_rawObjectSize, MEMORY_ALLOCATION_ALIGNMENT))
102
103//
104// Computes the size required for a fixed size object plus any extra buffer space
105// it requires. The extra buffer space is aligned on a process natural boundary.
106//
107#define COMPUTE_OBJECT_SIZE(_rawObjectSize, _extraSize) \
108 (COMPUTE_RAW_OBJECT_SIZE(_rawObjectSize) + (USHORT) WDF_ALIGN_SIZE_UP(_extraSize, MEMORY_ALLOCATION_ALIGNMENT))
109
110//
111// Gets size of the context associated with the specified attributes structure.
112//
113size_t
116 );
117
118//
119// Computes the total size of an object taking into account its fixed size,
120// any additional size after the fixed, and an object header, so the memory looks
121// like:
122//
123// Object
124// additional optional memory
125// WDF_HANDLE_HEADER
126//
130 __in PFX_DRIVER_GLOBALS FxDriverGlobals,
131 __in USHORT RawObjectSize,
132 __in USHORT ExtraSize,
133 __in size_t ContextSize,
134 __out size_t* Total
135 );
136
140 __in PFX_DRIVER_GLOBALS FxDriverGlobals,
141 __in USHORT RawObjectSize,
142 __in USHORT ExtraSize,
144 __out size_t* Total
145 );
146
147PVOID
149 __in PFX_DRIVER_GLOBALS FxDriverGlobals,
151 __in size_t Size,
152 __in ULONG Tag,
154 __in USHORT ExtraSize,
156 );
157
158VOID
163 );
164
165PVOID
167 __in PFX_DRIVER_GLOBALS FxDriverGlobals,
168 __in PVOID AllocationStart,
169 __in USHORT ObjectSize,
172 );
173
174VOID
175__inline
179 )
180{
181#if FX_SUPER_DBG
182 if (Object->GetDriverGlobals()->FxVerifierHandle) {
183
184
185
186
187
188
189 ASSERT(Object->GetObjectSize() > 0);
190 ASSERT(Object == Object->GetContextHeader()->Object);
191 }
192#endif
193
194 ASSERT((((ULONG_PTR) Object) & FxHandleFlagMask) == 0x0);
195 *Handle = Object->GetObjectHandle();
196}
197
198/*++
199
200Routine Description:
201
202 Retrieves the object pointer from the handle if valid.
203
204 This does not change an objects reference count.
205
206Arguments:
207
208 handle - The object handle created by WdfObjectCreateHandle
209
210 type - Type of the object from FxTypes.h
211
212 ppObj - Pointer to location to store the returned object.
213
214Returns:
215
216 NTSTATUS
217
218--*/
219
220VOID
223 __out PVOID* PPObject,
227 );
228
234 __in BOOLEAN AllowCallbacksOnly,
236 );
237
238__inline
243 )
244/*++
245
246Routine Description:
247 Checks if the FxObject is of a the Type.
248
249Arguments:
250 FxObject - the object being checked
251 Type - The type value to be checked
252
253Returns:
254 TRUE if the Object is of the type 'Type'
255 FALSE otherwise
256 --*/
257{
259 PVOID tmpObject;
260 FxQueryInterfaceParams params = {&tmpObject, Type, 0};
261
262 //
263 // Do a quick non virtual call for the type and only do the slow QI if
264 // the first types do not match
265 //
266
267 if (Object->GetType() == Type) {
268 return TRUE;
269 }
270
271 status = Object->QueryInterface(&params);
272
273 if (!NT_SUCCESS(status)) {
274 return FALSE;
275 }
276
277 return TRUE;
278
279}
280
281__inline
282VOID
284 __in PFX_DRIVER_GLOBALS FxDriverGlobals,
287 __out PVOID* PPObject
288 )
289/*++
290
291Routine Description:
292 Converts an externally facing WDF handle into its internal object.
293
294Arguments:
295 FxDriverGlobals - caller's globals
296 Handle - handle to convert into an object
297 Type - required type of the underlying object
298 PPObject - pointer to receive the underlying object
299
300 --*/
301{
304
305 if (Handle == NULL) {
306
307
308
309
310
311 FxVerifierBugCheck(FxDriverGlobals,
314 Type);
315
316 /* NOTREACHED */
317 return;
318 }
319
320 offset = 0;
322
323 //
324 // The only DDI you can call on an object which has a ref count of zero is
325 // WdfObjectGetTypedContextWorker().
326 //
327 ASSERT(pObject->GetRefCnt() > 0);
328
329 //
330 // Do a quick non virtual call for the type and only do the slow QI if
331 // the first types do not match
332 //
333 if (pObject->GetType() == Type) {
334 *PPObject = pObject;
335 ASSERT(offset == 0x0);
336 return;
337 }
338 else {
340 }
341}
342
343__inline
344VOID
346 __in PFX_DRIVER_GLOBALS FxDriverGlobals,
349 __out PVOID* PPObject,
351 )
352/*++
353
354Routine Description:
355 This function probably should be removed and the optional Offset paramter
356 moved into the signature for FxObjectHandleGetPtr(). The distinction
357 between these 2 functions was important when both of them were *not*
358 FORCEINLINE functions (since there was an additional parameter to push onto
359 the stack). Now that they are both __inlined, there is no longer a
360 parameter to push, eliminating this optimization.
361
362Arguments:
363 FxDriverGlobals - caller's globals
364 Handle - handle to convert into an object
365 Type - required type of the underlying object
366 PPObject - pointer to receive the underlying object
367 Offset - offset into the object which the handle resided. Nearly all objects
368 will have a zero offset
369
370 --*/
371{
373
374 if (Handle == NULL) {
375
376
377
378
379
380 FxVerifierBugCheck(FxDriverGlobals,
383 Type);
384
385 /* NOTREACHED */
386 return;
387 }
388
389 *Offset = 0;
391
392 //
393 // The only DDI you can call on an object which has a ref count of zero is
394 // WdfObjectGetTypedContextWorker().
395 //
396 ASSERT(pObject->GetRefCnt() > 0);
397
398 //
399 // Do a quick non virtual call for the type and only do the slow QI if
400 // the first types do not match
401 //
402 if (pObject->GetType() == Type) {
403 *PPObject = pObject;
404 ASSERT(*Offset == 0x0);
405 return;
406 }
407 else {
409 }
410}
411
412VOID
413__inline
415 __in PFX_DRIVER_GLOBALS CallersGlobals,
418 __out PVOID* PPObject,
419 __out PFX_DRIVER_GLOBALS* ObjectGlobals
420 )
421/*++
422
423Routine Description:
424 Converts an externally facing WDF handle into its internal object.
425
426Arguments:
427 FxDriverGlobals - caller's globals
428 Handle - handle to convert into an object
429 Type - required type of the underlying object
430 PPObject - pointer to receive the underlying object
431 ObjectGlobals - pointer to receive the underlying object's globals.
432
433 --*/
434{
435 //
436 // All FX_TYPEs except for IFX_TYPE_MEMORY derive from FxObject, so our cast
437 // below will work with all types but IFX_TYPE_MEMORY (in which case the caller
438 // should call FxObjectHandleGetPtr and then get the globals on their own
439 // from the IFxMemory interface).
440 //
442
443 FxObjectHandleGetPtr(CallersGlobals,
444 Handle,
445 Type,
446 PPObject);
447
448 *ObjectGlobals = ((FxObject*) (*PPObject))->GetDriverGlobals();
449}
450
451VOID
452__inline
454 __in PFX_DRIVER_GLOBALS CallersGlobals,
456 __out PFX_DRIVER_GLOBALS* ObjectGlobals
457 )
458/*++
459
460Routine Description:
461 Converts an externally facing WDF handle into its internal object and
462 returns its globals.
463
464Arguments:
465 FxDriverGlobals - caller's globals
466 Handle - handle to convert into an object
467 ObjectGlobals - pointer to receive the underlying object's globals.
468
469 --*/
470{
472
473 FxObjectHandleGetPtrAndGlobals(CallersGlobals,
474 Handle,
476 &pObject,
477 ObjectGlobals);
478
480}
481
482#endif // _WDFPHANDLE_H_
unsigned char BOOLEAN
Type
Definition: Type.h:7
LONG NTSTATUS
Definition: precomp.h:26
static FxObject * _GetObjectFromHandle(__in WDFOBJECT Handle, __inout PWDFOBJECT_OFFSET ObjectOffset)
Definition: fxobject.hpp:613
WDFTYPE GetType(VOID)
Definition: fxobject.hpp:742
LONG GetRefCnt(VOID)
Definition: fxobject.hpp:758
Definition: Header.h:9
#define __in
Definition: dbghelp.h:35
#define __in_opt
Definition: dbghelp.h:38
#define __out
Definition: dbghelp.h:62
#define __deref_opt_out
Definition: dbghelp.h:32
#define NULL
Definition: types.h:112
#define TRUE
Definition: types.h:120
#define FALSE
Definition: types.h:117
#define NT_SUCCESS(StatCode)
Definition: apphelp.c:32
_Must_inspect_result_ _In_ FLT_CONTEXT_TYPE _In_ SIZE_T ContextSize
Definition: fltkernel.h:1444
PVOID FxObjectAndHandleHeaderInit(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PVOID AllocationStart, __in USHORT ObjectSize, __in_opt PWDF_OBJECT_ATTRIBUTES Attributes, __in FxObjectType ObjectType)
Definition: handleapi.cpp:292
__inline VOID FxObjectHandleGetPtr(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in WDFOBJECT Handle, __in WDFTYPE Type, __out PVOID *PPObject)
Definition: fxhandle.h:283
size_t FxGetContextSize(__in_opt PWDF_OBJECT_ATTRIBUTES Attributes)
Definition: handleapi.cpp:38
__inline BOOLEAN FxObjectCheckType(__in FxObject *Object, __in WDFTYPE Type)
Definition: fxhandle.h:240
__inline VOID FxObjectHandleGetPtrOffset(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in WDFOBJECT Handle, __in WDFTYPE Type, __out PVOID *PPObject, __out PWDFOBJECT_OFFSET Offset)
Definition: fxhandle.h:345
_Must_inspect_result_ NTSTATUS FxObjectAllocateContext(__in FxObject *Object, __in PWDF_OBJECT_ATTRIBUTES Attributes, __in BOOLEAN AllowCallbacksOnly, __deref_opt_out PVOID *Context)
Definition: handleapi.cpp:397
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)
Definition: handleapi.cpp:163
_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)
Definition: handleapi.cpp:147
_Must_inspect_result_ NTSTATUS FxCalculateObjectTotalSize2(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in USHORT RawObjectSize, __in USHORT ExtraSize, __in size_t ContextSize, __out size_t *Total)
Definition: handleapi.cpp:73
VOID FxObjectHandleGetPtrQI(__in FxObject *Object, __out PVOID *PPObject, __in WDFOBJECT Handle, __in WDFTYPE Type, __in WDFOBJECT_OFFSET Offset)
Definition: handleapi.cpp:347
VOID __inline FxObjectHandleCreate(__in FxObject *Object, __out PWDFOBJECT Handle)
Definition: fxhandle.h:176
VOID __inline FxObjectHandleGetPtrAndGlobals(__in PFX_DRIVER_GLOBALS CallersGlobals, __in WDFOBJECT Handle, __in WDFTYPE Type, __out PVOID *PPObject, __out PFX_DRIVER_GLOBALS *ObjectGlobals)
Definition: fxhandle.h:414
VOID FxContextHeaderInit(__in FxContextHeader *Header, __in FxObject *Object, __in_opt PWDF_OBJECT_ATTRIBUTES Attributes)
Definition: handleapi.cpp:248
VOID __inline FxObjectHandleGetGlobals(__in PFX_DRIVER_GLOBALS CallersGlobals, __in WDFOBJECT Handle, __out PFX_DRIVER_GLOBALS *ObjectGlobals)
Definition: fxhandle.h:453
@ FxHandleFlagMask
Definition: fxobject.hpp:62
USHORT * PWDFOBJECT_OFFSET
Definition: fxobject.hpp:80
FxObjectType
Definition: fxobject.hpp:117
USHORT WDFOBJECT_OFFSET
Definition: fxobject.hpp:80
FxObject * pObject
USHORT WDFTYPE
Definition: fxtypes.h:29
@ FX_TYPE_OBJECT
Definition: fxtypes.h:45
@ IFX_TYPE_MEMORY
Definition: fxtypes.h:55
#define FxVerifierBugCheck(FxDriverGlobals, Error,...)
Definition: fxverifier.h:58
ULONG Handle
Definition: gdb_input.c:15
GLenum const GLfloat * params
Definition: glext.h:5645
GLintptr offset
Definition: glext.h:5920
unsigned int ULONG
Definition: retypes.h:1
#define ASSERT(a)
Definition: mode.c:44
ObjectType
Definition: metafile.c:81
#define _Must_inspect_result_
Definition: ms_sal.h:558
#define MEMORY_ALLOCATION_ALIGNMENT
Definition: ntbasedef.h:90
#define UNREFERENCED_PARAMETER(P)
Definition: ntbasedef.h:317
_In_ ULONG _In_ ULONG Offset
Definition: ntddpcm.h:101
unsigned short USHORT
Definition: pedump.c:61
FxContextHeader * NextHeader
Definition: fxhandle.h:71
PFN_WDF_OBJECT_CONTEXT_DESTROY EvtDestroyCallback
Definition: fxhandle.h:82
DECLSPEC_ALIGN(MEMORY_ALLOCATION_ALIGNMENT) ULONG_PTR Context[1]
PFN_WDF_OBJECT_CONTEXT_CLEANUP EvtCleanupCallback
Definition: fxhandle.h:76
FxObject * Object
Definition: fxhandle.h:66
PCWDF_OBJECT_CONTEXT_TYPE_INFO ContextTypeInfo
Definition: fxhandle.h:87
Definition: ps.c:97
INT POOL_TYPE
Definition: typedefs.h:78
uint32_t ULONG_PTR
Definition: typedefs.h:65
@ WDF_INVALID_HANDLE
Definition: wdfbugcodes.h:62
_Must_inspect_result_ _In_ WDFCOLLECTION _In_ WDFOBJECT Object
_Must_inspect_result_ _In_ WDFDMAENABLER _In_ _In_opt_ PWDF_OBJECT_ATTRIBUTES Attributes
_Must_inspect_result_ _In_ WDFDEVICE _In_ BOOLEAN _In_opt_ PVOID Tag
Definition: wdfdevice.h:4065
_Must_inspect_result_ _In_ WDFDEVICE _In_ DEVICE_REGISTRY_PROPERTY _In_ _Strict_type_match_ POOL_TYPE PoolType
Definition: wdfdevice.h:3815
_Must_inspect_result_ _In_ WDFDEVICE _In_ PWDF_DEVICE_PROPERTY_DATA _In_ DEVPROPTYPE _In_ ULONG Size
Definition: wdfdevice.h:4533
EVT_WDF_OBJECT_CONTEXT_DESTROY * PFN_WDF_OBJECT_CONTEXT_DESTROY
Definition: wdfobject.h:95
EVT_WDF_OBJECT_CONTEXT_CLEANUP * PFN_WDF_OBJECT_CONTEXT_CLEANUP
Definition: wdfobject.h:82