IWDFFile::RetrieveFileName メソッド (wudfddi.h)
[警告: UMDF 2 は UMDF の最新バージョンであり、UMDF 1 よりも優先されます。 すべての新しい UMDF ドライバーは、UMDF 2 を使用して記述する必要があります。 UMDF 1 には新機能が追加されておらず、Windows 10 の新しいバージョンでは UMDF 1 のサポートが制限されています。 ユニバーサル Windows ドライバーでは、UMDF 2 を使用する必要があります。 詳細については、「UMDFの概要」を参照してください。
RetrieveFileName メソッドは、基になるカーネル モード デバイスに関連付けられているファイルの完全な名前を取得します。
構文
HRESULT RetrieveFileName(
[out] PWSTR pFileName,
[in, out] DWORD *pdwFileNameLengthInChars
);
パラメーター
[out] pFileName
基になるカーネル モード デバイスに関連付けられているファイルの完全な名前を表す、NULL-terminated 文字列を受け取る呼び出し元が指定したバッファーへのポインター。指定されたポインターが NULL場合、RetrieveFileName が成功します。
[in, out] pdwFileNameLengthInChars
pFileName が指す完全なファイル 名のサイズ (文字数) を受け取る呼び出し元が指定した変数へのポインター。 pFileName のバッファーが NULL以外の場合、フレームワークはファイル名文字列のサイズを文字で返します。
入力時に、ドライバーは、pFileName が指すバッファーのサイズ (文字単位) にこの変数 設定します。 ドライバー pFileName NULL を指定し、pdwFileNameLengthInChars が指す変数に対して 0 を指定した場合、フレームワークは、ファイル名文字列に必要なサイズ (文字) に変数を設定します。
戻り値
RetrieveFileName は、次のシナリオでS_OKを返します。
- pFileName パラメーターが指すバッファーは、NULL で、NULL 文字を含む名前文字列を保持するのに十分な大きさであり、フレームワークは指定されたバッファーに文字列を正常にコピーし、pdwFileNameLengthInChar s パラメーターが指す変数を文字列内の文字数に設定しました。
- pFileName のバッファーが NULL されました。ドライバーは pdwFileNameLengthInChars の変数を 0 に事前設定し、フレームワークは pdwFileNameLengthInChars の変数を文字列に必要な文字数に設定しました。
RetrieveFileName は、他の HRESULT 値も返す場合があります。
備考
ドライバーは、IQueueCallbackCreate::OnCreateFile コールバック関数から RetrieveFileName を呼び出す場合があります。 詳細については、「UMDF ドライバー でデバイス インターフェイスを使用するを参照してください。
例
次のコード例は、ファイルの名前を取得する方法を示しています。
ULONG fileNameCch = 0;
PWSTR fileName = NULL;
ULONG index;
CComObject<CUmdfHidFile> *file = NULL;
HRESULT hr;
// Get the length of the file name to allocate a buffer.
hr = WdfFile->RetrieveFileName(NULL, &fileNameCch);
//
// Allocate the buffer.
//
if (SUCCEEDED(hr))
{
fileName = new WCHAR[fileNameCch];
if (fileName == NULL)
{
hr = E_OUTOFMEMORY;
}
}
//
// Get the file name.
//
if (SUCCEEDED(hr))
{
hr = WdfFile->RetrieveFileName(fileName, &fileNameCch);
}
必要条件
| 要件 | 価値 |
|---|---|
| サポート終了 | UMDF 2.0 以降では使用できません。 |
| ターゲット プラットフォーム の | デスクトップ |
| UMDF の最小バージョン を する | 1.5 |
| ヘッダー | wudfddi.h (Wudfddi.h を含む) |
| DLL | WUDFx.dll |
関連項目
IWDFFile の