ReactOS  0.4.15-dev-2700-g4b4ffa9
fxcxdeviceinitapi.cpp
Go to the documentation of this file.
1 /*++
2 
3 Copyright (c) Microsoft Corporation
4 
5 Module Name:
6 
7  FxCxDeviceInitApi.cpp
8 
9 Abstract:
10 
11  This module exposes the "C" interface to the FxDevice object
12  for the class extensions.
13 
14 Author:
15 
16 
17 
18 Environment:
19 
20  Both kernel and user mode
21 
22 Revision History:
23 
24 
25 
26 --*/
27 
28 #include "coreprivshared.hpp"
29 
30 extern "C" {
31 // #include "FxCxDeviceInitApi.tmh"
32 }
33 
34 //
35 // Extern "C" the entire file
36 //
37 extern "C" {
38 
39 __inline
40 static
43  __in PFX_DRIVER_GLOBALS FxDriverGlobals,
45  )
46 {
48 
49  if (FxIsClassExtension(FxDriverGlobals, CxDriverGlobals) == FALSE) {
52  "This function can only be called by a WDF "
53  "extension driver, Driver 0x%p, %!STATUS!",
54  CxDriverGlobals->Public.Driver, status);
55  FxVerifierDbgBreakPoint(FxDriverGlobals);
56  }
57 
58  return status;
59 }
60 
63 WDFAPI
65 WDFEXPORT(WdfCxDeviceInitAssignWdmIrpPreprocessCallback)(
66  __in
68  __in
70  __in
72  __in
77  __in
79  )
80 {
81  DDI_ENTRY();
82 
86 
90 
91  //
92  // Caller must be a class extension driver.
93  //
95  if (!NT_SUCCESS(status)) {
96  goto Done;
97  }
98 
100 
101  if (NumMinorFunctions > 0) {
103  }
104 
105  //
106  // ARRAY_SIZE(CxDeviceInit->PreprocessInfo->Dispatch) just returns a
107  // constant size, it does not actually deref PreprocessInfo (which could
108  // be NULL)
109  //
113  "MajorFunction %x is invalid, %!STATUS!",
115 
116  goto Done;
117  }
118 
119  //
120  // CX must call this API multiple times if it wants to register preprocess callbacks for
121  // multiple IRP major codes.
122  //
125  if (CxDeviceInit->PreprocessInfo == NULL) {
128  "Couldn't create object PreprocessInfo, "
129  "%!STATUS!", status);
130 
131  goto Done;
132  }
134  }
135 
137 
138  if (NumMinorFunctions > 0) {
142  "Already assigned Minorfunctions, %!STATUS!",
143  status);
144  goto Done;
145  }
146 
148  (PUCHAR) FxPoolAllocate(fxDriverGlobals,
149  NonPagedPool,
150  sizeof(UCHAR) * NumMinorFunctions);
151 
155  "Couldn't create object MinorFunctions, "
156  "%!STATUS!", status);
157  goto Done;
158  }
159 
162  &MinorFunctions[0],
164  );
165 
168  }
169 
172 
174 
175 Done:
176  return status;
177 }
178 
180 VOID
181 WDFEXPORT(WdfCxDeviceInitSetIoInCallerContextCallback)(
182  __in
184  __in
186  __in
188  )
189 
190 /*++
191 
192 Routine Description:
193 
194  Registers an I/O pre-processing callback for the class extension device.
195 
196  If registered, any I/O for the device is first presented to this
197  callback function before being placed in any I/O Queue's.
198 
199  The callback is invoked in the thread and/or DPC context of the
200  original WDM caller as presented to the I/O package. No framework
201  threading, locking, synchronization, or queuing occurs, and
202  responsibility for synchronization is up to the device driver.
203 
204  This API is intended to support METHOD_NEITHER IRP_MJ_DEVICE_CONTROL's
205  which must access the user buffer in the original callers context. The
206  driver would probe and lock the buffer pages from within this event
207  handler using the functions supplied on the WDFREQUEST object, storing
208  any required mapped buffers and/or pointers on the WDFREQUEST context
209  whose size is set by the RequestContextSize of the WDF_DRIVER_CONFIG structure.
210 
211  It is the responsibility of this routine to either complete the request, or
212  pass it on to the I/O package through WdfDeviceEnqueueRequest(Device, Request).
213 
214 Arguments:
215 
216  CxDeviceInit - Class Extension Device initialization structure
217 
218  EvtIoInCallerContext - Pointer to driver supplied callback function
219 
220 Return Value:
221 
222  None
223 
224 --*/
225 {
226  DDI_ENTRY();
227 
231 
235 
236  //
237  // Caller must be a class extension driver.
238  //
240  if (!NT_SUCCESS(status)) {
241  goto Done;
242  }
243 
245 
247 
248 Done:
249  return;
250 }
251 
253 VOID
254 WDFEXPORT(WdfCxDeviceInitSetRequestAttributes)(
255  __in
257  __in
259  __in
261  )
262 {
263  DDI_ENTRY();
264 
268 
272 
273  //
274  // Caller must be a class extension driver.
275  //
277  if (!NT_SUCCESS(status)) {
278  goto Done;
279  }
280 
282 
283  //
284  // Parent of all requests created from WDFDEVICE are parented by the WDFDEVICE.
285  //
289 
290  if (!NT_SUCCESS(status)) {
292  return;
293  }
294 
297  sizeof(WDF_OBJECT_ATTRIBUTES));
298 
299 Done:
300  return;
301 }
302 
304 VOID
305 WDFEXPORT(WdfCxDeviceInitSetFileObjectConfig)(
306  __in
308  __in
310  __in
312  __in_opt
314  )
315 
316 /*++
317 
318 Routine Description:
319 
320  Registers file object callbacks for class extensions.
321 
322  Defaults to WdfFileObjectNotRequired if no file obj config set.
323 
324 Arguments:
325 
326 Returns:
327 
328 --*/
329 
330 {
331  DDI_ENTRY();
332 
337 
341 
342  //
343  // Caller must be a class extension driver.
344  //
346  if (!NT_SUCCESS(status)) {
347  goto Done;
348  }
349 
351 
355  "Invalid CxFileObjectConfig Size %d, expected %d",
357 
359  goto Done;
360  }
361 
368  );
369 
370  if (!NT_SUCCESS(status)) {
372  goto Done;
373  }
374 
375  //
376  // Validate AutoForwardCleanupClose.
377  //
378  switch (CxFileObjectConfig->AutoForwardCleanupClose) {
379  case WdfTrue:
380  case WdfFalse:
381  case WdfUseDefault:
382  break;
383 
384  default:
387  "Invalid CxFileObjectConfig->AutoForwardCleanupClose value 0x%x, "
388  "expected WDF_TRI_STATE value",
389  CxFileObjectConfig->AutoForwardCleanupClose);
390 
392  goto Done;
393  }
394 
396 
398  CxFileObjectConfig->AutoForwardCleanupClose;
399 
400  //
401  // Remove bit flags and validate file object class value.
402  //
404  CxFileObjectConfig->FileObjectClass);
405 
410  "Out of range CxFileObjectConfig->FileObjectClass %d",
411  CxFileObjectConfig->FileObjectClass);
413  goto Done;
414  }
415 
416  //
417  // The optional flag can only be combined with a subset of values.
418  //
420  switch(normalizedFileClass) {
424  break;
425 
426  default:
429  "Invalid CxFileObjectConfig->FileObjectClass %d",
430  CxFileObjectConfig->FileObjectClass);
432  goto Done;
433  break; // just in case static verification tools complain.
434  }
435  }
436 
438 
442 
447  }
448 
449 Done:
450  return;
451 }
452 
456 WDFEXPORT(WdfCxDeviceInitAllocate)(
457  __in
459  __in
461  )
462 {
463  DDI_ENTRY();
464 
469 
472  fxDriverGlobals = DeviceInit->DriverGlobals;
473  cxDeviceInit = NULL;
474 
475  //
476  // Caller must be a class extension driver.
477  //
479  if (!NT_SUCCESS(status)) {
480  goto Done;
481  }
482 
484  if (!NT_SUCCESS(status)) {
485  goto Done;
486  }
487 
489  if (NULL == cxDeviceInit) {
490  goto Done;
491  }
492 
495 
496 Done:
497  return cxDeviceInit;
498 }
499 
500 } // extern "C"
501 
#define DDI_ENTRY()
Definition: fxglobalskm.h:56
#define __in_bcount(x)
Definition: dbghelp.h:41
_Must_inspect_result_ __in PWDFCXDEVICE_INIT __in PFN_WDFCXDEVICE_WDM_IRP_PREPROCESS __in UCHAR __in_opt PUCHAR __in ULONG NumMinorFunctions
static __inline NTSTATUS FxValiateCx(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PFX_DRIVER_GLOBALS CxDriverGlobals)
#define _Must_inspect_result_
Definition: no_sal2.h:62
#define STATUS_INSUFFICIENT_RESOURCES
Definition: udferr_usr.h:158
#define __in_opt
Definition: dbghelp.h:38
#define TRUE
Definition: types.h:120
#define STATUS_INVALID_PARAMETER
Definition: udferr_usr.h:135
PFN_WDF_IO_IN_CALLER_CONTEXT IoInCallerContextCallback
NTSTATUS status
unsigned char * PUCHAR
Definition: retypes.h:3
_Must_inspect_result_ _In_ PWDFDEVICE_INIT _In_ PFN_WDFDEVICE_WDM_IRP_PREPROCESS _In_ UCHAR _In_opt_ PUCHAR MinorFunctions
Definition: wdfdevice.h:3465
LONG NTSTATUS
Definition: precomp.h:26
__in PWDFCXDEVICE_INIT __in PWDFCX_FILEOBJECT_CONFIG CxFileObjectConfig
__in PWDFCXDEVICE_INIT __in PFN_WDF_IO_IN_CALLER_CONTEXT EvtIoInCallerContext
WDFCX_FILEOBJECT_CONFIG Callbacks
#define STATUS_INVALID_DEVICE_REQUEST
Definition: udferr_usr.h:138
_Must_inspect_result_ __drv_maxIRQL(DISPATCH_LEVEL) WDFAPI NTSTATUS WDFEXPORT(WdfCxDeviceInitAssignWdmIrpPreprocessCallback)(__in PWDF_DRIVER_GLOBALS DriverGlobals
DriverGlobals
CxFileObjectInit FileObject
_In_ PWDFDEVICE_INIT _In_ PWDF_FILEOBJECT_CONFIG _In_opt_ PWDF_OBJECT_ATTRIBUTES FileObjectAttributes
Definition: wdfdevice.h:3395
__in PWDFCXDEVICE_INIT __in PWDF_OBJECT_ATTRIBUTES RequestAttributes
ASSERT(CxDeviceInit->PreprocessInfo->ClassExtension)
NTSTATUS(STDCALL * PFN_WDFCXDEVICE_WDM_IRP_PREPROCESS)(_In_ WDFDEVICE Device, _Inout_ PIRP Irp, _In_ PVOID DispatchContext)
Definition: wdfcx.h:63
#define FALSE
Definition: types.h:117
#define WDFEXPORT(a)
Definition: fxmacros.hpp:157
#define WDFAPI
Definition: wdftypes.h:53
_In_ PWDFDEVICE_INIT _In_ PWDF_OBJECT_ATTRIBUTES RequestAttributes
Definition: wdfdevice.h:3428
enum _WDF_FILEOBJECT_CLASS WDF_FILEOBJECT_CLASS
PFX_DRIVER_GLOBALS cxDriverGlobals
FxIrpPreprocessInfo * PreprocessInfo
__inline NTSTATUS FxVerifierCheckIrqlLevel(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in KIRQL Irql)
Definition: fxverifier.h:158
#define TRACINGDEVICE
Definition: dbgtrace.h:58
BOOLEAN __inline FxIsFileObjectOptional(__in WDF_FILEOBJECT_CLASS FileObjectClass)
Definition: fxdevice.hpp:112
static _Must_inspect_result_ PWDFCXDEVICE_INIT _AllocateCxDeviceInit(__in PWDFDEVICE_INIT DeviceInit)
#define NT_SUCCESS(StatCode)
Definition: apphelp.c:32
PFX_DRIVER_GLOBALS CxDriverGlobals
WDF_FILEOBJECT_CLASS __inline FxFileObjectClassNormalize(__in WDF_FILEOBJECT_CLASS FileObjectClass)
Definition: fxdevice.hpp:103
cxDeviceInit CxDriverGlobals
WDF_FILEOBJECT_CLASS normalizedFileClass
_Must_inspect_result_ __inline BOOLEAN FxIsClassExtension(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PFX_DRIVER_GLOBALS ExtDriverGlobals)
Definition: fxglobals.h:965
PFN_WDFCXDEVICE_WDM_IRP_PREPROCESS EvtCxDevicePreprocess
unsigned char UCHAR
Definition: xmlstorage.h:181
_Must_inspect_result_ NTSTATUS FxValidateObjectAttributes(__in PFX_DRIVER_GLOBALS FxDriverGlobals, __in PWDF_OBJECT_ATTRIBUTES Attributes, __in ULONG Flags=FX_VALIDATE_OPTION_NONE_SPECIFIED)
PFX_DRIVER_GLOBALS ClientDriverGlobals
#define PASSIVE_LEVEL
Definition: env_spec_w32.h:693
#define TRACE_LEVEL_ERROR
Definition: storswtr.h:27
WDF_TRI_STATE AutoForwardCleanupClose
#define DISPATCH_LEVEL
Definition: env_spec_w32.h:696
WDF_OBJECT_ATTRIBUTES RequestAttributes
_Must_inspect_result_ _In_ PWDFDEVICE_INIT _In_ PFN_WDFDEVICE_WDM_IRP_PREPROCESS _In_ UCHAR _In_opt_ PUCHAR _In_ ULONG NumMinorFunctions
Definition: wdfdevice.h:3465
#define ARRAY_SIZE(a)
Definition: main.h:24
_In_ UCHAR MajorFunction
Definition: wdfdevice.h:1697
PFX_DRIVER_GLOBALS fxDriverGlobals
DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_VERBOSE, TRACINGPNP, "Enter, WDFDEVICE %p", Device)
_Must_inspect_result_ __in PWDFCXDEVICE_INIT __in PFN_WDFCXDEVICE_WDM_IRP_PREPROCESS EvtCxDeviceWdmIrpPreprocess
#define NULL
Definition: types.h:112
_Must_inspect_result_ __in PWDFDEVICE_INIT DeviceInit
_In_ PWDFDEVICE_INIT _In_ PFN_WDF_IO_IN_CALLER_CONTEXT EvtIoInCallerContext
Definition: wdfdevice.h:3502
FxPointerNotNull(cxDriverGlobals, CxDeviceInit)
_Must_inspect_result_ __in PWDFCXDEVICE_INIT __in PFN_WDFCXDEVICE_WDM_IRP_PREPROCESS __in UCHAR __drv_when(NumMinorFunctions > 0, __in_bcount(NumMinorFunctions)) __drv_when(NumMinorFunctions
unsigned int ULONG
Definition: retypes.h:1
Info Dispatch[IRP_MJ_MAXIMUM_FUNCTION+1]
#define RtlCopyMemory(Destination, Source, Length)
Definition: typedefs.h:263
_In_ PWDFDEVICE_INIT DeviceInit
Definition: wdfcontrol.h:113
#define STATUS_SUCCESS
Definition: shellext.h:65
__inline PFX_DRIVER_GLOBALS GetFxDriverGlobals(__in PWDF_DRIVER_GLOBALS DriverGlobals)
Definition: fxglobals.h:597
WDF_FILEOBJECT_CLASS Class
#define __in
Definition: dbghelp.h:35
PWDFCXDEVICE_INIT cxDeviceInit
_Must_inspect_result_ __in PWDFCXDEVICE_INIT CxDeviceInit
EVT_WDF_IO_IN_CALLER_CONTEXT * PFN_WDF_IO_IN_CALLER_CONTEXT
Definition: wdfdevice.h:1728
__in PWDFCXDEVICE_INIT __in PWDFCX_FILEOBJECT_CONFIG __in_opt PWDF_OBJECT_ATTRIBUTES FileObjectAttributes
FxVerifierDbgBreakPoint(pFxDriverGlobals)
_Must_inspect_result_ __in PWDFCXDEVICE_INIT __in PFN_WDFCXDEVICE_WDM_IRP_PREPROCESS __in UCHAR MajorFunction
WDF_OBJECT_ATTRIBUTES Attributes
Definition: ps.c:97