1 /*++
2 
3 Copyright (c) Microsoft Corporation
4 
5 Module Name:
6 
7     FxUserObjectApi.cpp
8 
9 Abstract:
10 
11     This modules implements the C API's for the FxUserObject.
12 
13 Author:
14 
15 
16 
17 Environment:
18 
19     Both kernel and user mode
20 
21 Revision History:
22 
23 --*/
24 
25 #include "fxobjectpch.hpp"
26 
27 #include "fxuserobject.hpp"
28 
29 // Tracing support
30 extern "C" {
31 #if defined(EVENT_TRACING)
32 #include "FxUserObjectApi.tmh"
33 #endif
34 }
35 
36 
37 extern "C" {
38 
39 _Must_inspect_result_
40 __drv_maxIRQL(DISPATCH_LEVEL)
41 NTSTATUS
42 STDCALL
43 WDFEXPORT(WdfObjectCreate)(
44    __in
45    PWDF_DRIVER_GLOBALS DriverGlobals,
46    __in_opt
47    PWDF_OBJECT_ATTRIBUTES Attributes,
48    __out
49    WDFOBJECT* Object
50    )
51 
52 /*++
53 
54 Routine Description:
55 
56     This creates a general WDF object for use by the device driver.
57 
58     It participates in general framework object contracts in that it:
59 
60     - Has a handle and a reference count
61     - Has Cleanup and Destroy callbacks
62     - Supports driver context memory and type
63     - Can have child objects
64     - Can optionally have a parent object and automatically delete with it
65 
66     It is intended to allow a WDF device driver to use this object to
67     create its own structures that can participate in frameworks lifetime
68     management.
69 
70     The device driver can use the objects context memory and type to
71     represent its own internal data structures, and can further assign
72     device driver specific resources and release them by registering
73     for EvtObjectCleanup, and EvtObjectDestroy callbacks.
74 
75     The object may be deleted by using the WdfObjectDelete API.
76 
77     Since the object is represented by a frameworks handle, it can be
78     reference counted, and validated.
79 
80     Class drivers may use this object to define framework object handles
81     for their types.
82 
83 Arguments:
84 
85     Attributes - WDF_OBJECT_ATTRIBUTES to define a parent object, context memory,
86                  Cleanup and Destroy handlers.
87 
88 Return Value:
89 
90     NTSTATUS
91 
92 --*/
93 
94 {
95     DDI_ENTRY();
96 
97     NTSTATUS status;
98     WDFOBJECT handle;
99     FxUserObject* pUserObject;
100     PFX_DRIVER_GLOBALS pFxDriverGlobals;
101 
102     pUserObject = NULL;
103     pFxDriverGlobals = GetFxDriverGlobals(DriverGlobals);
104 
105     //
106     // Get the parent's globals if it is present
107     //
108     if (NT_SUCCESS(FxValidateObjectAttributesForParentHandle(pFxDriverGlobals,
109                                                              Attributes))) {
110         FxObject* pParent;
111 
112         FxObjectHandleGetPtrAndGlobals(pFxDriverGlobals,
113                                        Attributes->ParentObject,
114                                        FX_TYPE_OBJECT,
115                                        (PVOID*)&pParent,
116                                        &pFxDriverGlobals);
117     }
118 
119     FxPointerNotNull(pFxDriverGlobals, Object);
120 
121     status = FxValidateObjectAttributes(pFxDriverGlobals,
122                                         Attributes,
123                                         FX_VALIDATE_OPTION_EXECUTION_LEVEL_ALLOWED
124                                         );
125     if (!NT_SUCCESS(status)) {
126         return status;
127     }
128 
129     //
130     // Create the FxObject.
131     //
132     status = FxUserObject::_Create(pFxDriverGlobals, Attributes, &pUserObject);
133     if (NT_SUCCESS(status)) {
134         handle = pUserObject->GetHandle();
135         *Object = handle;
136 
137         DoTraceLevelMessage(pFxDriverGlobals, TRACE_LEVEL_VERBOSE,
138                             TRACINGUSEROBJECT,
139                             "Created UserObject Handle 0x%p",
140                             handle);
141     }
142 
143     return status;
144 }
145 
146 } // extern "C" the entire file
147