IWDFFile2::RetrieveCountedFileName メソッド (wudfddi.h)
警告
UMDF 2 は UMDF の最新バージョンであり、UMDF 1 よりも優先されます。 すべての新しい UMDF ドライバーは、UMDF 2 を使用して記述する必要があります。 UMDF 1 には新機能が追加されておらず、新しいバージョンのWindows 10では UMDF 1 のサポートが制限されています。 ユニバーサル Windows ドライバーでは UMDF 2 を使用する必要があります。 詳細については、「UMDF を使用したはじめに」を参照してください。
RetrieveCountedFileName メソッドは、デバイスに関連付けられているファイルの完全なカウントファイル名を取得します。
構文
HRESULT RetrieveCountedFileName(
[out] WCHAR *pCountedFileName,
[in, out] DWORD *pdwCountedFileNameLengthInChars
);
パラメーター
[out] pCountedFileName
呼び出し元によって割り当てられたバッファーへのポインター。 このバッファーは、デバイスに関連付けられているファイルの完全な名前を表す NULL で終わる文字列を受け取ります。 ポインターが NULL の場合、 RetrieveCountedFileName は文字列の長さのみを取得します。
[in, out] pdwCountedFileNameLengthInChars
呼び出し元によって割り当てられた変数へのポインター。 入力時に、ドライバーは 、pdwCountedFileNameLengthInChars が指すバッファーの長さ (文字数) に変数を設定します。 出力時に、フレームワークは、バッファーに配置された文字列 (終端 の NULL 文字を含む) の長さ (文字数) に変数を設定します。 カウントされたファイル名が存在しない場合、フレームワークは変数を 0 に設定します。
戻り値
RetrieveCountedFileName は、操作が成功した場合にS_OKを返します。 それ以外の場合、メソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 説明 |
|---|---|
| E_POINTER | pdwCountedFileNameLength ポインターは NULL です。 |
| HRESULT_FROM_WIN32 (ERROR_INVALID_PARAMETER) | カウントされたファイル名が無効です。 |
| E_NOT_SUFFICIENT_BUFFER | pCountedFileName が指すバッファーが小さすぎます。 |
このメソッドは、Winerror.h の他の値のいずれかを返す場合があります。
注釈
カウントされたファイル名は、終端 の NULL に加えて、埋め込み NULL ('\0') 文字を含めることができる文字列 です。 NULL 文字を埋め込まない名前文字列を取得するには、ドライバーは IWDFFile::RetrieveFileName を呼び出すことができます。
通常、ドライバーは次の手順を使用して RetrieveCountedFileName を 2 回呼び出します。
- ドライバーは、pCountedFileName パラメーターを NULL に設定して RetrieveCountedFileName を呼び出して、必要なバッファー長を取得します。
- ドライバーは、必要なサイズのバッファーを割り当てます。
- ドライバーは RetrieveCountedFileName を再度呼び出して、ファイル名の文字列を取得します。
例
次のコード例では、ドライバーの IQueueCallbackCreate::OnCreateFile コールバック関数が受け取る IWDFFile インターフェイスから IWDFFile2 インターフェイスを取得します。 この例では 、RetrieveCountedFileName を 2 回呼び出します。ファイル名の長さを取得するには 1 回、ファイル名文字列を取得するには 1 回です。
VOID
STDMETHODCALLTYPE
CMyQueue::OnCreateFile(
__in IWDFIoQueue *pWdfQueue,
__in IWDFIoRequest *pWdfRequest,
__in IWDFFile* pWdfFileObject
)
...
IWDFFile2* pWdfFileObject2 = NULL;
WCHAR* countedFileName = NULL;
DWORD countedFileNameCch = 0;
HRESULT hr = S_OK;
//
// Obtain IWDFFile2 interface from IWDFFile.
//
hr = pWdfFileObject->QueryInterface(IID_PPV_ARGS(&pWdfFileObject2));
if (!SUCCEEDED(hr))
{
goto Done;
}
//
// Get length of counted filename.
//
hr = pWdfFileObject2->RetrieveCountedFileName(NULL,
&countedFileNameCch);
if (!SUCCEEDED(hr))
{
goto Done;
}
if (countedFileNameCch != 0)
{
//
// Allocate a buffer.
//
countedFileName = new WCHAR[countedFileNameCch];
if (countedFileName == NULL)
{
hr = E_OUTOFMEMORY;
goto Done;
}
//
// Get counted file name.
//
hr = pWdfFileObject2->RetrieveCountedFileName(countedFileName,
&countedFileNameCch);
if (!SUCCEEDED(hr))
{
goto Done;
}
}
...
要件
| 要件 | 値 |
|---|---|
| サポート終了 | UMDF 2.0 以降では使用できません。 |
| 対象プラットフォーム | デスクトップ |
| 最小 UMDF バージョン | 1.9 |
| Header | wudfddi.h (Wudfddi.h を含む) |
| [DLL] | WUDFx.dll |