scsiwmi.h

书中的主要程序文件。在打开例题的.dsw文件后,请读者在 tools菜单下的 Options 的 Directories 标签中选择 Executable files

    This routine is a callback into the miniport to execute a method.

    If the request can be completed immediately without pending,
	ScsiPortWmiPostProcess should be called from within this callback and
    FALSE returned.
		
    If the request cannot be completed within this callback then TRUE should
    be returned. Once the pending operations are finished the miniport should
    call ScsiPortWmiPostProcess and then complete the srb.

Arguments:

    Context is a caller specified context value originally passed to
        ScsiPortWmiDispatchFunction.

    RequestContext is a context associated with the srb being processed.

    GuidIndex is the index into the list of guids provided when the
        miniport registered

    InstanceIndex is the index that denotes which instance of the data block
        is being called.

    MethodId has the id of the method being called

    InBufferSize has the size of the data block passed in as the input to
        the method.

    OutBufferSize on entry has the maximum size available to write the
        returned data block. If the output buffer is not large enough
        to return all of the data blocks then the miniport should call
        ScsiPortWmiPostProcess with a status of SRB_STATUS_DATA_OVERRUN
        and the size of the output buffer needed to fufill the request.
        It is important to check that there is sufficient room in the
        output buffer before performing any operations that may have
        side effects.

    Buffer on entry has the input data block and on return has the output
        output data block.


Return Value:

    TRUE if request is pending else FALSE

--*/

typedef enum
{
    ScsiWmiEventControl,       // Enable or disable an event
    ScsiWmiDataBlockControl    // Enable or disable data block collection
} SCSIWMI_ENABLE_DISABLE_CONTROL;

typedef
BOOLEAN
(*PSCSIWMI_FUNCTION_CONTROL) (
    IN PVOID DeviceContext,
    IN PSCSIWMI_REQUEST_CONTEXT RequestContext,
    IN ULONG GuidIndex,
    IN SCSIWMI_ENABLE_DISABLE_CONTROL Function,
    IN BOOLEAN Enable
    );
/*++

Routine Description:

    This routine is a callback into the miniport to enabled or disable event
    generation or data block collection. Since WMI manages reference counting
    for each of the data blocks or events, a miniport should only expect a
	single enable followed by a single disable. Data blocks will only
    receive collection enable/disable if they were registered as requiring
    it, that is include the WMIREG_FLAG_EXPENSIVE flag.

    If the request can be completed immediately without pending,
	ScsiPortWmiPostProcess should be called from within this callback and
    FALSE returned.
		
    If the request cannot be completed within this callback then TRUE should
    be returned. Once the pending operations are finished the miniport should
    call ScsiPortWmiPostProcess and then complete the srb.

Arguments:

    DeviceContext is a caller specified context value originally passed to
        ScsiPortWmiDispatchFunction.

    RequestContext is a context associated with the srb being processed.

    Function specifies which functionality is being enabled or disabled

    Enable is TRUE then the function is being enabled else disabled

Return Value:

    TRUE if request is pending else FALSE

--*/

//
// This structure supplies context information for SCSIWMILIB to process the
// WMI srbs.
//
typedef struct _SCSIWMILIB_CONTEXT
{
    //
    // WMI data block guid registration info
    ULONG GuidCount;
    PSCSIWMIGUIDREGINFO GuidList;

    //
    // WMI functionality callbacks
    PSCSIWMI_QUERY_REGINFO       QueryWmiRegInfo;
    PSCSIWMI_QUERY_DATABLOCK     QueryWmiDataBlock;
    PSCSIWMI_SET_DATABLOCK       SetWmiDataBlock;
    PSCSIWMI_SET_DATAITEM        SetWmiDataItem;
    PSCSIWMI_EXECUTE_METHOD      ExecuteWmiMethod;
    PSCSIWMI_FUNCTION_CONTROL    WmiFunctionControl;
} SCSI_WMILIB_CONTEXT, *PSCSI_WMILIB_CONTEXT;

VOID
ScsiPortWmiPostProcess(
    IN PSCSIWMI_REQUEST_CONTEXT RequestContext,
    IN UCHAR SrbStatus,
    IN ULONG BufferUsed
    );
/*++

Routine Description:


    This routine will do the work of post-processing a WMI srb.

Arguments:

    RequestContext is a context associated with the srb being processed. After
        this api returns the ReturnStatus and ReturnSize fields are updated.

    SrbStatus has the return status code for the srb. If a query or method
        callback was passed an output buffer that was not large enough
        then SrbStatus should be SRB_STATUS_DATA_OVERRUN and BufferUsed
        should be the number of bytes needed in the output buffer.

    BufferUsed has the number of bytes required by the miniport to return the
       data requested in the WMI srb. If SRB_STATUS_DATA_OVERRUN was passed
       in SrbStatus then BufferUsed has the number of needed in the output
       buffer. If SRB_STATUS_SUCCESS is passed in SrbStatus then BufferUsed
       has the actual number of bytes used in the output buffer.

Return Value:


--*/

BOOLEAN
ScsiPortWmiDispatchFunction(
    IN PSCSI_WMILIB_CONTEXT WmiLibInfo,
    IN UCHAR MinorFunction,
    IN PVOID DeviceContext,
    IN PSCSIWMI_REQUEST_CONTEXT RequestContext,
    IN PVOID DataPath,
    IN ULONG BufferSize,
    IN PVOID Buffer
    );
/*++

Routine Description:

    Dispatch helper routine for WMI srb requests. Based on the Minor
    function passed the WMI request is processed and this routine
    invokes the appropriate callback in the WMILIB structure.

Arguments:

    WmiLibInfo has the SCSI WMILIB information control block associated
        with the adapter or logical unit

    DeviceContext is miniport defined context value passed on to the callbacks
        invoked by this api.

    RequestContext is a pointer to a context structure that maintains
        information about this WMI srb. This request context must remain
        valid throughout the entire processing of the srb, at least until
        ScsiPortWmiPostProcess returns with the final srb return status and
        buffer size. If the srb can pend then memory for this buffer should
        be allocated from the SRB extension. If not then the memory can be
        allocated from a stack frame that does not go out of scope, perhaps
        that of the caller to this api.

    DataPath is value passed in wmi request

    BufferSize is value passed in wmi request

    Buffer is value passed in wmi request

Return Value:

    TRUE if request is pending else FALSE

--*/

#define ScsiPortWmiFireAdapterEvent(    \
    HwDeviceExtension,                  \
    Guid,                               \
    InstanceIndex,                      \
    EventDataSize,                      \
    EventData                           \
    )                                   \
        ScsiPortWmiFireLogicalUnitEvent(\
    HwDeviceExtension,                  \
    0xff,                               \
    0,                                  \
    0,                                  \
    Guid,                               \
    InstanceIndex,                      \
    EventDataSize,                      \
    EventData)
/*++

Routine Description:

    This routine will fire a WMI event associated with an adapter using
    the data buffer passed. This routine may be called at or below DPC level.

Arguments:

    HwDeviceExtension is the adapter device extension

    Guid is pointer to the GUID that represents the event

    InstanceIndex is the index of the instance of the event

    EventDataSize is the number of bytes of data that is being fired with
       with the event. This size specifies the size of the event data only
       and does NOT include the 0x40 bytes of preceeding padding.

    EventData is the data that is fired with the events. There must be exactly
        0x40 bytes of padding preceeding the event data.

Return Value:

--*/

VOID
ScsiPortWmiFireLogicalUnitEvent(
    IN PVOID HwDeviceExtension,
    IN UCHAR PathId,
    IN UCHAR TargetId,
    IN UCHAR Lun,
    IN LPGUID Guid,
    IN ULONG InstanceIndex,
    IN ULONG EventDataSize,
    IN PVOID EventData
    );
/*++

Routine Description:

    This routine will fire a WMI event using the data buffer passed. This
    routine may be called at or below DPC level

Arguments:

    HwDeviceExtension is the adapter device extension

    PathId identifies the SCSI bus if a logical unit is firing the event
        or is 0xff if the adapter is firing the event.

    TargetId identifies the target controller or device on the bus

    Lun identifies the logical unit number of the target device

    Guid is pointer to the GUID that represents the event

    InstanceIndex is the index of the instance of the event

    EventDataSize is the number of bytes of data that is being fired with
       with the event. This size specifies the size of the event data only
       and does NOT include the 0x40 bytes of preceeding padding.

    EventData is the data that is fired with the events. There must be exactly
        0x40 bytes of padding preceeding the event data.

Return Value:

--*/

#ifdef __cplusplus
}
#endif

#endif