HW_FIND_ADAPTER回呼函式 (storport.h)

發行項
02/26/2024

HwStorFindAdapter 例程會使用提供的組態來判斷是否支援特定的 HBA，如果是，則傳回該適配卡的組態資訊。

語法

HW_FIND_ADAPTER HwFindAdapter;

ULONG HwFindAdapter(
           PVOID DeviceExtension,
  [in]     PVOID HwContext,
  [in]     PVOID BusInformation,
  [in]     PCHAR ArgumentString,
  [in/out] PPORT_CONFIGURATION_INFORMATION ConfigInfo,
  [in]     PBOOLEAN Reserved3
)
{...}

參數

DeviceExtension

提供每個配接器儲存區域。

[in] HwContext

設定為 NULL。

[in] BusInformation

設定為 NULL。

[in] ArgumentString

提供 NULL 終止的字串，其中包含有關驅動程式的內容資訊。

[in/out] ConfigInfo

提供迷你埠驅動程式在初始化期間所使用的初始化 PORT_CONFIGURATION_INFORMATION 結構。

[in] Reserved3

保留供系統使用。

傳回值

HwStorFindAdapter 必須傳回下列其中一個狀態值：

傳回碼	Description
SP_RETURN_FOUND	指出找到支援的 HBA，且 HBA 相關的組態資訊已成功決定並在 PORT_CONFIGURATION_INFORMATION 結構中設定。
SP_RETURN_ERROR	指出找到 HBA，但取得設定資訊時發生錯誤。可能的話，應該使用 StorPortLogError 記錄這類錯誤。
SP_RETURN_BAD_CONFIG	表示提供的組態資訊對配接器無效。
SP_RETURN_NOT_FOUND	指出未找到所提供組態信息支援的 HBA。

備註

由於 Storport 驅動程式僅支援隨插即用 (PnP) 裝置，因此 HwContext 和 BusInformation 參數不會提供給非虛擬迷你埠驅動程式。

HwStorFindAdapter 必須在 ConfigInfo 結構中設定 MaximumTransferLength 和 NumberOfPhysicalBreaks 字段。除了這些欄位之外， PORT_CONFIGURATION_INFORMATION 結構一律會完整指定啟動配接器所需的所有配接器資源。

名稱 HwStorFindAdapter 只是佔位元。此例程的實際原型定義於 Storport.h 中，如下所示：

typedef
ULONG
HW_FIND_ADAPTER (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );

在大部分情況下，StorPort 會在 IRQL == PASSIVE_LEVEL呼叫 HwStorFindAdapter 例程，而不需取得任何微調鎖定。例外狀況是當迷你埠不支援使用 ScsiRestartAdapter 控件類型呼叫 HwStorAdaptorControl 時。在此情況下，StorPort 會呼叫 HwStorFindAdapter 和 HwStorInitialize 來重新初始化配接器。如果是這種情況， HwStorFindAdapter 會在 IRQL == DISPATCH_LEVEL呼叫。此外，在傾印模式中， HwStorFindAdapter 會在 IRQL == HIGH_LEVEL呼叫。

範例

若要定義 HwStorFindAdapter 回呼函式，您必須先提供函式宣告，以識別您要定義的回呼函式類型。 Windows 提供一組驅動程式的回呼函式類型。使用回呼函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證器 (SDV) ，以及其他驗證工具會尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為 MyHwFindAdapter 的 HwStorFindAdapter 回呼例程，請使用HW_FIND_ADAPTER類型，如下列程式代碼範例所示：

HW_FIND_ADAPTER MyHwFindAdapter;

然後，實作回呼例程，如下所示：

_Use_decl_annotations_
ULONG
MyHwFindAdapter (
  _In_ PVOID  DeviceExtension,
  _In_ PVOID  HwContext,
  _In_ PVOID  BusInformation,
  _In_z_ PCHAR  ArgumentString,
  _Inout_ PPORT_CONFIGURATION_INFORMATION  ConfigInfo,
  _In_ PBOOLEAN  Reserved3
  );
  {
      ...
  }

HW_FIND_ADAPTER函式類型定義於 Storport.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 註釋新增至函式定義。 Use_decl_annotations註釋可確保使用頭檔中套用至HW_FIND_ADAPTER函式類型的批註。如需函式宣告需求的詳細資訊，請參閱使用 Storport 驅動程式的函式角色類型宣告函式。如需 Use_decl_annotations的詳細資訊，請參閱標註函式行為。