1 /*++
2 
3 Copyright (c) Microsoft Corporation.  All rights reserved.
4 
5 _WdfVersionBuild_
6 
7 Module Name:
8 
9     WdfQueryInterface.h
10 
11 Abstract:
12 
13     This file contains the DDIs for handling query interface
14 
15 Environment:
16 
17     kernel mode only
18 
19 Revision History:
20 
21 --*/
22 
23 //
24 // NOTE: This header is generated by stubwork.  Please make any
25 //       modifications to the corresponding template files
26 //       (.x or .y) and use stubwork to regenerate the header
27 //
28 
29 #ifndef _WDFQUERYINTERFACE_H_
30 #define _WDFQUERYINTERFACE_H_
31 
32 #ifndef WDF_EXTERN_C
33   #ifdef __cplusplus
34     #define WDF_EXTERN_C       extern "C"
35     #define WDF_EXTERN_C_START extern "C" {
36     #define WDF_EXTERN_C_END   }
37   #else
38     #define WDF_EXTERN_C
39     #define WDF_EXTERN_C_START
40     #define WDF_EXTERN_C_END
41   #endif
42 #endif
43 
44 WDF_EXTERN_C_START
45 
46 
47 
48 #if (NTDDI_VERSION >= NTDDI_WIN2K)
49 
50 
51 
52 typedef
53 _Function_class_(EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST)
54 _IRQL_requires_same_
55 _IRQL_requires_max_(PASSIVE_LEVEL)
56 NTSTATUS
57 STDCALL
58 EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST(
59     _In_
60     WDFDEVICE Device,
61     _In_
62     LPGUID InterfaceType,
63     _Inout_
64     PINTERFACE ExposedInterface,
65     _Inout_opt_
66     PVOID ExposedInterfaceSpecificData
67     );
68 
69 typedef EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST *PFN_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST;
70 
71 typedef struct _WDF_QUERY_INTERFACE_CONFIG {
72     //
73     // Size of this structure in bytes.
74     //
75     ULONG Size;
76 
77     //
78     // Interface to be returned to the caller.  Optional if BehaviorType is set
79     // to WdfQueryInterfaceTypePassThrough or ImportInterface is set to TRUE.
80     //
81     PINTERFACE Interface;
82 
83     //
84     // The GUID identifying the interface
85     //
86     CONST GUID * InterfaceType;
87 
88     //
89     // Valid only for PDOs.  The framework will allocate a new request and
90     // forward it down the parent's device stack.
91     //
92     BOOLEAN SendQueryToParentStack;
93 
94     //
95     // Driver supplied callback which is called after some basic interface
96     // validation has been performed (size, version, and guid checking).  This
97     // is an optional parameter and may be NULL unless ImportInterface is
98     // specified.
99     //
100     // If the callback returns !NT_SUCCESS, this error will be returned to the
101     // caller and the query interface will fail.
102     //
103     // In this callback, the caller is free to modify the ExposedInterface in
104     // any manner of its choosing.  For instance, the callback may change any
105     // field in the interface.  The callback may also alloate a dynamic context
106     // to be associated with the interface; the InterfaceReference and
107     // InterfaceDereference functions may also be overridden.
108     //
109     // If ImportInterface is set to TRUE, then this is a required field and the
110     // callback must initialize the interface (the framework will leave the
111     // ExposedInterface buffer exactly as it received it) since the framework
112     // has no way of knowing which fields to fill in and which to leave alone.
113     //
114     PFN_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtDeviceProcessQueryInterfaceRequest;
115 
116     //
117     // If TRUE, the interface provided by the caller contains data that the
118     // driver is interested in.  By setting to this field to TRUE, the
119     // EvtDeviceProcessQueryInterfaceRequest callback must initialize the
120     // ExposedInterface.
121     //
122     // If FALSE, the entire ExposedInterface is initialized through a memory
123     // copy before the EvtDeviceProcessQueryInterfaceRequest is called.
124     //
125     BOOLEAN ImportInterface;
126 
127 } WDF_QUERY_INTERFACE_CONFIG, *PWDF_QUERY_INTERFACE_CONFIG;
128 
129 FORCEINLINE
130 VOID
131 WDF_QUERY_INTERFACE_CONFIG_INIT(
132     _Out_ PWDF_QUERY_INTERFACE_CONFIG InterfaceConfig,
133     _In_opt_ PINTERFACE Interface,
134     _In_ CONST GUID* InterfaceType,
135     _In_opt_ PFN_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtDeviceProcessQueryInterfaceRequest
136     )
137 {
138     RtlZeroMemory(InterfaceConfig, sizeof(WDF_QUERY_INTERFACE_CONFIG));
139 
140     InterfaceConfig->Size = sizeof(WDF_QUERY_INTERFACE_CONFIG);
141     InterfaceConfig->Interface = Interface;
142     InterfaceConfig->InterfaceType = InterfaceType;
143     InterfaceConfig->EvtDeviceProcessQueryInterfaceRequest =
144         EvtDeviceProcessQueryInterfaceRequest;
145 }
146 
147 //
148 // WDF Function: WdfDeviceAddQueryInterface
149 //
150 typedef
151 _Must_inspect_result_
152 _IRQL_requires_max_(PASSIVE_LEVEL)
153 WDFAPI
154 NTSTATUS
155 (STDCALL *PFN_WDFDEVICEADDQUERYINTERFACE)(
156     _In_
157     PWDF_DRIVER_GLOBALS DriverGlobals,
158     _In_
159     WDFDEVICE Device,
160     _In_
161     PWDF_QUERY_INTERFACE_CONFIG InterfaceConfig
162     );
163 
164 _Must_inspect_result_
165 _IRQL_requires_max_(PASSIVE_LEVEL)
166 FORCEINLINE
167 NTSTATUS
168 WdfDeviceAddQueryInterface(
169     _In_
170     WDFDEVICE Device,
171     _In_
172     PWDF_QUERY_INTERFACE_CONFIG InterfaceConfig
173     )
174 {
175     return ((PFN_WDFDEVICEADDQUERYINTERFACE) WdfFunctions[WdfDeviceAddQueryInterfaceTableIndex])(WdfDriverGlobals, Device, InterfaceConfig);
176 }
177 
178 
179 
180 //
181 // The following functions can be assigned to INTERFACE::InterfaceReference
182 // and INTERFACE::InterfaceDeference
183 //
184 // o WdfDeviceInterfaceReferenceNoOp
185 // o WdfDeviceInterfaceDereferenceNoOp
186 //
187 // Thes 2 functions do nothing when called.  These are appropriate for
188 // interfaces which can be queried for and used independent of the PNP state of
189 // the WDFDEVICE the interface was retrieved from.
190 //
191 FORCEINLINE
192 VOID
193 WdfDeviceInterfaceReferenceNoOp(
194     _In_ PVOID Context
195     )
196 {
197     UNREFERENCED_PARAMETER(Context);
198 }
199 
200 FORCEINLINE
201 VOID
202 WdfDeviceInterfaceDereferenceNoOp(
203     _In_ PVOID Context
204     )
205 {
206     UNREFERENCED_PARAMETER(Context);
207 }
208 
209 #endif // (NTDDI_VERSION >= NTDDI_WIN2K)
210 
211 
212 
213 WDF_EXTERN_C_END
214 
215 #endif // _WDFQUERYINTERFACE_H_
216 
217