189 lines
7.0 KiB
C++
189 lines
7.0 KiB
C++
/*
|
|
* Copyright (C) 2006 The Android Open Source Project
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
* you may not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
|
|
#ifndef ANDROID_USB_WDF_OBJECT_H__
|
|
#define ANDROID_USB_WDF_OBJECT_H__
|
|
/** \file
|
|
This file consists of declaration of a class AndroidUsbWdfObject that
|
|
encapsulates a basic extension to all KMDF objects. Currently, device and
|
|
file object extensions ared derived from it.
|
|
*/
|
|
|
|
/** AndroidUsbWdfObject class encapsulates a basic extension to all KMDF
|
|
objects. Currently, device and file object extensions ared derived from it.
|
|
Instances of this and derived classes must be allocated from NonPagedPool.
|
|
*/
|
|
class AndroidUsbWdfObject {
|
|
public:
|
|
/** \brief Constructs the object.
|
|
|
|
@param obj_type[in] Type of the object that this wrapper represents.
|
|
This method must be called at low IRQL.
|
|
*/
|
|
AndroidUsbWdfObject(AndroidUsbWdfObjectType obj_type);
|
|
|
|
/** \brief Destructs the object.
|
|
|
|
This method can be called at any IRQL.
|
|
*/
|
|
virtual ~AndroidUsbWdfObject();
|
|
|
|
/** \brief Initializes object attributes for new KMDF object.
|
|
|
|
Each KMDF extension object must perform attribute initializations in order
|
|
to register an extension with KMDF framework. Since all our extensions are
|
|
derived from the base AndroidUsbWdfObject we use a single WDF object
|
|
extension context for all KMDF objects that we extend. So we can initialize
|
|
and register our context extension structure here. Note that object
|
|
attributes for file object wrappers are initialized globaly, when device
|
|
object is created. So file object extensions must not call this method.
|
|
This method must be called at low IRQL.
|
|
@param wdf_obj_attr[out] Object attributes to initialize.
|
|
@param parent[in] Parent object for this object. Can be NULL.
|
|
@return STATUS_SUCCESS on success or an appropriate error code.
|
|
*/
|
|
virtual NTSTATUS InitObjectAttributes(PWDF_OBJECT_ATTRIBUTES wdf_obj_attr,
|
|
WDFOBJECT parent);
|
|
|
|
/** \brief Initializes context for this extension
|
|
|
|
This method initializes AndroidUsbWdfObjectContext structure that KMDF
|
|
allocated for the object that is being extended with this class.
|
|
InitObjectAttributes method must be called prior to the call to this
|
|
method. Besides, before calling this method, instance of this class must
|
|
be already attached to the KMDF object it represents. Otherwise this
|
|
method will fail with STATUS_INTERNAL_ERROR.
|
|
This method must be called at low IRQL.
|
|
@return STATUS_SUCCESS on success or an appropriate error code
|
|
*/
|
|
virtual NTSTATUS InitializeContext();
|
|
|
|
|
|
protected:
|
|
/** \brief Returns syncronisation scope for this extension type.
|
|
|
|
This method is called from InitObjectAttributes method to specify what
|
|
type of synchronization is required for instances of this type. By
|
|
default we return WdfSynchronizationScopeNone which makes KMDF not
|
|
to synchronize access to this type of object.
|
|
This method can be called at IRQL <= DISPATCH_LEVEL.
|
|
*/
|
|
virtual WDF_SYNCHRONIZATION_SCOPE GetWdfSynchronizationScope();
|
|
|
|
/** \brief Handler for cleanup event fired for associated KMDF object.
|
|
|
|
The framework calls this callback function when either the framework or a
|
|
driver attempts to delete the object.
|
|
This method can be called at IRQL <= DISPATCH_LEVEL.
|
|
*/
|
|
virtual void OnEvtCleanupCallback();
|
|
|
|
/** \brief Handler for destroy callback
|
|
|
|
The framework calls the EvtDestroyCallback callback function after the
|
|
object's reference count has been decremented to zero. The framework
|
|
deletes the object immediately after the EvtDestroyCallback callback
|
|
function returns.
|
|
This callback can be called at IRQL <= DISPATCH_LEVEL.
|
|
*/
|
|
virtual void OnEvtDestroyCallback();
|
|
|
|
/** \brief Removes driver's references on an object so it can be deleted.
|
|
|
|
The framework calls the callback function when either the framework or a
|
|
driver attempts to delete the object.
|
|
This callback can be called at IRQL <= DISPATCH_LEVEL.
|
|
@param wdf_obj[in] A handle to a framework object this class wraps.
|
|
*/
|
|
static void EvtCleanupCallbackEntry(WDFOBJECT wdf_obj);
|
|
|
|
/** \brief Called when framework object is being deleted
|
|
|
|
The framework calls the EvtDestroyCallback callback function after the
|
|
object's reference count has been decremented to zero. The framework
|
|
deletes the object immediately after the EvtDestroyCallback callback
|
|
function returns.
|
|
This callback can be called at IRQL <= DISPATCH_LEVEL.
|
|
@param wdf_obj[in] A handle to a framework object this class wraps.
|
|
*/
|
|
static void EvtDestroyCallbackEntry(WDFOBJECT wdf_obj);
|
|
|
|
public:
|
|
|
|
/// Gets KMDF object extended with this instance
|
|
__forceinline WDFOBJECT wdf_object() const {
|
|
return wdf_object_;
|
|
}
|
|
|
|
/// Sets KMDF object associated with this extension
|
|
__forceinline void set_wdf_object(WDFOBJECT wdf_obj) {
|
|
ASSERT(NULL == wdf_object_);
|
|
wdf_object_ = wdf_obj;
|
|
}
|
|
|
|
/// Gets KMDF object type for this extension
|
|
__forceinline AndroidUsbWdfObjectType object_type() const {
|
|
return object_type_;
|
|
}
|
|
|
|
/** \brief Checks if this extension represends KMDF object of the given type
|
|
|
|
@param obj_type[in] Object type to check
|
|
@return true if this wrapper represents object of that type and
|
|
false otherwise.
|
|
*/
|
|
__forceinline Is(AndroidUsbWdfObjectType obj_type) const {
|
|
return (obj_type == object_type());
|
|
}
|
|
|
|
/// Checks if extension is attached to a KMDF object
|
|
__forceinline bool IsAttached() const {
|
|
return (NULL != wdf_object());
|
|
}
|
|
|
|
protected:
|
|
/// KMDF object that is extended with this instance
|
|
WDFOBJECT wdf_object_;
|
|
|
|
/// KMDF object type for this extension
|
|
AndroidUsbWdfObjectType object_type_;
|
|
};
|
|
|
|
/** \brief Gets our extension for the given KMDF object
|
|
|
|
This method can be called at any IRQL
|
|
@param wdf_obj[in] KMDF handle describing an object
|
|
@return Instance of AndroidUsbWdfObject associated with this object or NULL
|
|
if association is not found.
|
|
*/
|
|
__forceinline AndroidUsbWdfObject* GetAndroidUsbWdfObjectFromHandle(
|
|
WDFOBJECT wdf_obj) {
|
|
ASSERT(NULL != wdf_obj);
|
|
if (NULL != wdf_obj) {
|
|
AndroidUsbWdfObjectContext* context =
|
|
GetAndroidUsbWdfObjectContext(wdf_obj);
|
|
ASSERT((NULL != context) && (NULL != context->wdf_object_ext) &&
|
|
(context->wdf_object_ext->Is(context->object_type)));
|
|
if ((NULL != context) && (NULL != context->wdf_object_ext) &&
|
|
context->wdf_object_ext->Is(context->object_type)) {
|
|
return context->wdf_object_ext;
|
|
}
|
|
}
|
|
return NULL;
|
|
}
|
|
|
|
#endif // ANDROID_USB_WDF_OBJECT_H__
|