fxiotargetremote.hpp

Go to the documentation of this file.

/*++
 
Copyright (c) Microsoft Corporation.  All rights reserved.
 
Module Name:
 
    FxIoTargetRemote.hpp
 
Abstract:
 
    Derivation of FxIoTarget specializing in targets remote to this device
    stack.
 
Author:
 
 
 
Environment:
 
    Both kernel and user mode
 
Revision History:
 
--*/
 
#ifndef _FXIOTARGETREMOTE_H_
#define _FXIOTARGETREMOTE_H_
 
enum FxIoTargetRemoteCloseReason {
    FxIoTargetRemoteCloseReasonQueryRemove = 1,
    FxIoTargetRemoteCloseReasonPlainClose,
    FxIoTargetRemoteCloseReasonDelete
};
 
#if (FX_CORE_MODE == FX_CORE_KERNEL_MODE)
typedef PVOID               MdTargetNotifyHandle;
#else
typedef WUDF_TARGET_CONTEXT MdTargetNotifyHandle;
#endif
 
class FxIoTargetRemoteNotificationCallback;
 
struct FxIoTargetQueryRemove : public FxCallback {
 
    FxIoTargetQueryRemove(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals
        ) :
        FxCallback(FxDriverGlobals),
        m_Method(NULL)
    {
    }
 
    _Must_inspect_result_
    NTSTATUS
    Invoke(
        __in WDFIOTARGET IoTarget
        )
    {
        NTSTATUS status;
 
        CallbackStart();
        status = m_Method(IoTarget);
        CallbackEnd();
 
        return status;
    }
 
    PFN_WDF_IO_TARGET_QUERY_REMOVE  m_Method;
};
 
struct FxIoTargetRemoveCanceled : public FxCallback {
 
    FxIoTargetRemoveCanceled(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals
        ) :
        FxCallback(FxDriverGlobals),
        m_Method(NULL)
    {
    }
 
    VOID
    Invoke(
        __in WDFIOTARGET Target
        )
    {
        CallbackStart();
        m_Method(Target);
        CallbackEnd();
    }
 
    PFN_WDF_IO_TARGET_REMOVE_CANCELED  m_Method;
};
 
struct FxIoTargetRemoveComplete : public FxCallback {
 
    FxIoTargetRemoveComplete(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals
        ) :
        FxCallback(FxDriverGlobals),
        m_Method(NULL)
    {
    }
 
    VOID
    Invoke(
        __in WDFIOTARGET Target
        )
    {
        CallbackStart();
        m_Method(Target);
        CallbackEnd();
    }
 
    PFN_WDF_IO_TARGET_REMOVE_COMPLETE m_Method;
};
 
enum FxIoTargetRemoteOpenState {
    FxIoTargetRemoteOpenStateClosed = 1,
    FxIoTargetRemoteOpenStateOpening,
    FxIoTargetRemoteOpenStateOpen,
};
 
struct FxIoTargetRemoveOpenParams {
 
    FxIoTargetRemoveOpenParams()
    {
        RtlZeroMemory(this, sizeof(FxIoTargetRemoveOpenParams));
    }
 
    VOID
    Set(
        __in PWDF_IO_TARGET_OPEN_PARAMS OpenParams,
        __in PUNICODE_STRING Name,
        __in PVOID Ea,
        __in ULONG EaLength
        );
 
    VOID
    Clear(
        VOID
        );
 
    UNICODE_STRING TargetDeviceName;
 
    WDF_IO_TARGET_OPEN_TYPE OpenType;
 
    ACCESS_MASK DesiredAccess;
 
    ULONG ShareAccess;
 
    ULONG FileAttributes;
 
    ULONG CreateDisposition;
 
    ULONG CreateOptions;
 
    __field_bcount(EaBufferLength) PVOID EaBuffer;
 
    ULONG EaBufferLength;
 
    LARGE_INTEGER AllocationSize;
 
    PLARGE_INTEGER AllocationSizePointer;
 
};
 
struct FxIoTargetClearedPointers {
    MdDeviceObject TargetPdo;
    MdFileObject TargetFileObject;
    HANDLE TargetHandle;
};
 
class FxIoTargetRemote : public FxIoTarget {
 
public:
 
    static
    _Must_inspect_result_
    NTSTATUS
    _Create(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals,
        __in PWDF_OBJECT_ATTRIBUTES Attributes,
        __in FxDeviceBase* Device,
        __out FxIoTargetRemote** Target
        );
 
    ~FxIoTargetRemote();
 
    NTSTATUS
    InitRemote(
        __in FxDeviceBase* Device
        );
 
    NTSTATUS
    InitRemoteModeSpecific(
        __in FxDeviceBase* Device
        );
 
    _Must_inspect_result_
    NTSTATUS
    Open(
        __in PWDF_IO_TARGET_OPEN_PARAMS OpenParams
        );
 
    VOID
    Close(
        __in FxIoTargetRemoteCloseReason Reason
        );
 
    NTSTATUS
    GetTargetDeviceRelations(
        _Out_ BOOLEAN* Close
        );
 
    BOOLEAN
    CanRegisterForPnpNotification(
        VOID
        )
    {
        BOOLEAN canRegister = FALSE;
 
#if (FX_CORE_MODE == FX_CORE_KERNEL_MODE)
        if (m_TargetFileObject != NULL) {
            canRegister = TRUE;
        }
#else // FX_CORE_USER_MODE
        if (m_TargetHandle != NULL) {
            canRegister = TRUE;
        }
#endif
        return canRegister;
    }
 
    VOID
    ResetTargetNotifyHandle(
        VOID
        )
    {
#if (FX_CORE_MODE == FX_CORE_KERNEL_MODE)
    m_TargetNotifyHandle = NULL;
#else // FX_CORE_USER_MODE
    m_TargetNotifyHandle = WUDF_TARGET_CONTEXT_INVALID;
#endif
    }
 
    NTSTATUS
    OpenTargetHandle(
        _In_ PWDF_IO_TARGET_OPEN_PARAMS OpenParams,
        _Inout_ FxIoTargetRemoveOpenParams* pParams
        );
 
    VOID
    CloseTargetHandle(
        VOID
        );
 
    HANDLE
    GetTargetHandle(
        VOID
        );
 
    NTSTATUS
    RegisterForPnpNotification(
        VOID
        );
 
    VOID
    UnregisterForPnpNotification(
        _In_ MdTargetNotifyHandle Handle
        );
 
    __inline
    WDFIOTARGET
    GetHandle(
        VOID
        )
    {
        return (WDFIOTARGET) GetObjectHandle();
    }
 
    virtual
    VOID
    Remove(
        VOID
        );
 
    VOID
    RemoveModeSpecific(
        VOID
        );
 
protected:
    FxIoTargetRemote(
        __in PFX_DRIVER_GLOBALS FxDriverGlobals
        );
 
    virtual
    VOID
    ClearTargetPointers(
        VOID
        );
 
    _Must_inspect_result_
    NTSTATUS
    QueryInterface(
        __in FxQueryInterfaceParams* Params
        )
    {
        if (Params->Type == FX_TYPE_IO_TARGET_REMOTE) {
            *Params->Object = (FxIoTargetRemote*) this;
            return STATUS_SUCCESS;
        }
        else {
            return FxIoTarget::QueryInterface(Params); // __super call
        }
    }
 
    _Must_inspect_result_
    NTSTATUS
    OpenLocalTargetByFile(
        _In_ PWDF_IO_TARGET_OPEN_PARAMS OpenParams
        );
 
#if (FX_CORE_MODE == FX_CORE_KERNEL_MODE)
    static
    DRIVER_NOTIFICATION_CALLBACK_ROUTINE
    _PlugPlayNotification;
 
#else // FX_CORE_USER_MODE
    //
    // I/O dispatcher to be used for IRPs forwarded to this remote target. It is
    // created when the CWdfRemoteTarget is created. The win32 handle is
    // associated with it via a call to m_pRemoteDispatcher->BindToHandle()
    // right after we call CreateFile(...). We must call
    // m_pRemoteDispatcher->CloseHandle() to close the handle.
    //
    // Because of the plug-in pattern of the IoDispatcher, we need two
    // interface pointers (one to the outer object, and one to the plug-in.
    //
    IWudfIoDispatcher     * m_pIoDispatcher;
    IWudfRemoteDispatcher * m_pRemoteDispatcher;
 
    //
    // Implements host's callback interface for pnp notification
    //
    FxIoTargetRemoteNotificationCallback* m_NotificationCallback;
 
    VOID
    Forward(
        _In_ MdIrp Irp
        )
    {
        if (m_OpenParams.OpenType == WdfIoTargetOpenLocalTargetByFile) {
            //
            // Ignore the return value because once we have sent the request, we
            // want all processing to be done in the completion routine.
            //
            (void) Irp->Forward();
        }
        else {
            IWudfIoIrp* pSubmitIrp = FxIrp(Irp).GetIoIrp();
 
            //
            // Move the stack location to the next location
            //
            pSubmitIrp->SetNextIrpStackLocation();
 
            //
            // Route it using Remote dispatcher
            //
            m_pIoDispatcher->Dispatch(pSubmitIrp, NULL);
        }
    }
 
private:
 
    NTSTATUS
    BindToHandle(
        VOID
        );
 
    VOID
    UnbindHandle(
        _In_ FxIoTargetClearedPointers* TargetPointers
        );
 
    NTSTATUS
    CreateWdfFileObject(
        _In_opt_ PUNICODE_STRING  FileName,
        _Out_ MdFileObject* FileObject
        );
 
    VOID
    CloseWdfFileObject(
        _In_ MdFileObject FileObject
        );
 
#endif // FX_CORE_USER-MODE)
 
public:
    //
    // File handle for m_TargetHandle
    //
    HANDLE m_TargetHandle;
 
    //
    // Notification handle returned by IoRegisterPlugPlayNotification for KMDF,
    // or host's notification registartion interface for UMDf. Note that host
    // uses the term RegistrationId for the same (with WUDF_CONTEXT_TYPE which
    // is UINT64).
    //
    MdTargetNotifyHandle m_TargetNotifyHandle;
 
    //
    // Driver writer callbacks to indicate state changes
    //
    FxIoTargetQueryRemove m_EvtQueryRemove;
    FxIoTargetRemoveCanceled m_EvtRemoveCanceled;
    FxIoTargetRemoveComplete m_EvtRemoveComplete;
 
    FxCREvent m_OpenedEvent;
 
    FxIoTargetClearedPointers* m_ClearedPointers;
 
    //
    // Value from FxIoTargetRemoteOpenState
    //
    UCHAR m_OpenState;
 
protected:
    FxIoTargetRemoveOpenParams m_OpenParams;
};
 
#if (FX_CORE_MODE == FX_CORE_KERNEL_MODE)
#include "fxiotargetremotekm.hpp"
#else
#include "fxiotargetremoteum.hpp"
#endif
 
#endif // _FXIOTARGETREMOTE_H_