FilterVolumeFindFirst 函式 (fltuser.h)

發行項
08/23/2023

FilterVolumeFindFirst函式會傳回磁片區的相關資訊。

語法

HRESULT FilterVolumeFindFirst(
  [in]  FILTER_VOLUME_INFORMATION_CLASS dwInformationClass,
  [out] LPVOID                          lpBuffer,
  [in]  DWORD                           dwBufferSize,
  [out] LPDWORD                         lpBytesReturned,
  [out] PHANDLE                         lpVolumeFind
);

參數

[in] dwInformationClass

要求的資訊類型。此參數可以是下列其中一個值。

值	意義
FilterVolumeBasicInformation	lpBuffer參數指向的緩衝區會收到磁片區的FILTER_VOLUME_BASIC_INFORMATION結構。
FilterVolumeStandardInformation	lpBuffer參數指向的緩衝區會收到磁片區的FILTER_VOLUME_STANDARD_INFORMATION結構。從 Windows Vista 開始，即可使用此結構。

[out] lpBuffer

接收所要求資訊的呼叫端配置緩衝區指標。緩衝區中傳回的資訊類型是由 dwInformationClass 參數所定義。

[in] dwBufferSize

lpBuffer參數所指向緩衝區的大小，以位元組為單位。呼叫端應該根據指定的 dwInformationClass來設定此參數。

[out] lpBytesReturned

呼叫端配置的變數指標，如果FilterVolumeFindFirst的呼叫成功，則會接收lpBuffer指向之緩衝區中傳回的位元組數目。這個參數是必要的，而且不能是 Null。

[out] lpVolumeFind

呼叫端配置的變數指標，如果 FilterVolumeFindFirst 呼叫成功，則會接收迷你篩選的搜尋控制碼;否則，它會收到INVALID_HANDLE_VALUE。此搜尋控制碼可用於 FilterVolumeFindNext 和 FilterVolumeFindClose的後續呼叫。

傳回值

FilterVolumeFindFirst 如果成功傳回磁片區的相關資訊，則會傳回S_OK。否則，它會傳回 HRESULT 錯誤值，例如下列其中一項：

傳回碼	描述
HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)	lpBuffer指向的緩衝區不夠大，無法包含要求的資訊。傳回此值時， lpBytesReturned 會包含指定 dwInformationClass 結構所需的緩衝區大小，以位元組為單位。
HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER)	為 dwInformationClass 參數指定了不正確值。例如，如果在 Windows Vista 之前為作業系統指定 FilterVolumeStandardInformation ， FilterVolumeFindFirst 會傳回此 HRESULT 值。
HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS)	在篩選管理員已知的磁片區清單中找不到磁片區。

備註

此 FilterVolumeFindFirst 函式可用來開始掃描篩選管理員已知的磁片區。

FilterVolumeFindFirst 會開啟搜尋控制碼，並傳回篩選管理員已知磁片區清單中第一個磁片區的相關資訊。建立搜尋控制碼之後，請使用 FilterVolumeFindNext 函式來搜尋篩選管理員清單中的其他磁片區。不再需要搜尋控制碼時，請呼叫 FilterVolumeFindClose加以關閉。

請注意，使用 FilterVolumeFindFirst 和 FilterVolumeFindNext 列舉篩選管理員已知的磁片區清單時，清單中有兩個以上的磁片區可以有相同的名稱。如需詳細資訊，請參閱瞭解具有重複磁片區名稱的磁片區列舉。