IShellFolder::P arseDisplayName メソッド (shobjidl_core.h)
ファイル オブジェクトまたはフォルダーの表示名をアイテム識別子リストに変換します。
構文
HRESULT ParseDisplayName(
[in] HWND hwnd,
[in] IBindCtx *pbc,
[in] LPWSTR pszDisplayName,
[out] ULONG *pchEaten,
[out] PIDLIST_RELATIVE *ppidl,
[in, out] ULONG *pdwAttributes
);
パラメーター
[in] hwnd
型: HWND
ウィンドウ ハンドル。 クライアントは、ダイアログ ボックスまたはメッセージ ボックスを表示する場合に、ウィンドウ ハンドルを提供する必要があります。 それ以外の場合 は、hwnd を NULL に設定 します。
[in] pbc
種類: IBindCtx*
省略可能。 パラメーターを入力および出力として解析関数に渡すために使用されるバインド コンテキストへのポインター。 これらの渡されたパラメーターは、多くの場合、データ ソースに固有であり、データ ソースの所有者によって文書化されます。 たとえば、ファイル システム データ ソースは、 STR_FILE_SYS_BIND_DATA バインド コンテキスト パラメーターを使用して、解析される名前を ( WIN32_FIND_DATA 構造体として) 受け入れます。 STR_PARSE_PREFER_FOLDER_BROWSING を渡して、可能な場合はファイル システム データ ソースを使用して URL が解析されることを示すことができます。 CreateBindCtx を使用してバインド コンテキスト オブジェクトを構築し、IBindCtx::RegisterObjectParam を使用して値を設定します。 これらの完全な一覧については、「 バインド コンテキスト文字列キー 」を参照してください。
解析関数に渡されたり、解析関数から受信されたりするデータがない場合、この値は NULL になります。
[in] pszDisplayName
種類: LPWSTR
表示名を持つ null で終わる Unicode 文字列。 各シェル フォルダーは独自の解析構文を定義するため、この文字列の形式は異なる場合があります。 たとえば、デスクトップ フォルダーは、"C:\My Docs\My File.txt" などのパスを受け入れます。 また、"::{GUID}" 構文を使用して、GUID が関連付けられている名前空間内の項目への参照も受け入れます。 たとえば、デスクトップ フォルダーからコントロール パネルの完全修飾識別子リストを取得するには、次のコマンドを使用します。
::{CLSID for Control Panel}\::{CLSID for printers folder}
[out] pchEaten
種類: ULONG*
解析された表示名の文字数を受け取る ULONG 値へのポインター。 アプリケーションでこの情報が必要ない場合は、 pchEaten を NULL に設定し、値は返されません。
[out] ppidl
種類: PIDLIST_RELATIVE*
このメソッドが返されるときに、 オブジェクトの PIDL へのポインターが含まれます。 返されるアイテム識別子リストは、解析フォルダーに対する相対的な項目を指定します。 pszDisplayName に関連付けられているオブジェクトが解析フォルダー内にある場合、返される項目識別子リストには、1 つの SHITEMID 構造体のみが含まれます。 オブジェクトが解析フォルダーのサブフォルダーにある場合、返される項目識別子リストには複数の SHITEMID 構造体が 含まれます。 エラーが発生した場合は、このアドレスに NULL が返されます。
不要になったら、呼び出し元が CoTaskMemFree を呼び出してこのリソースを解放する必要があります。
[in, out] pdwAttributes
種類: ULONG*
ファイル属性のクエリに使用される値。 使用しない場合は、 NULL に設定する必要があります。 1 つ以上の属性を照会するには、対象の属性を表す SFGAO フラグを使用してこのパラメーターを初期化します。 返されると、true で 要求された属性が設定されます。
戻り値
種類: HRESULT
このメソッドは、成功すると S_OK を返します。 そうでない場合は、HRESULT エラー コードを返します。
注釈
一部のシェル フォルダーでは 、IShellFolder::P arseDisplayName を実装できない場合があります。 を実行する各フォルダーは、独自の解析構文を定義します。
ParseDisplayName は、相対パスまたは親フォルダーインジケーター ("." または "..") を処理することは想定されていません。 これらを適切に削除するのは呼び出し元次第です。
pdwAttributes で SFGAO_VALIDATE フラグを使用して、名前が解析されている項目の存在を確認しないでください。 IShellFolder::P arseDisplayName は、その動作が特別なバインド コンテキスト パラメーターによってオーバーライドされない限り、アイテムの存在を暗黙的に検証します。
一部の属性のクエリは比較的遅く、大量のメモリを使用する場合があります。 たとえば、ファイルが共有されているかどうかを判断するために、シェルはネットワーク コンポーネントを読み込みます。 この手順では、複数の DLL の読み込みが必要になる場合があります。 pdwAttributes の目的は、クエリを必要な情報のみに制限できるようにすることです。 次のコード フラグメントは、ファイルが圧縮されているかどうかを調べる方法を示しています。
LPITEMIDLIST pidl;
ULONG cbEaten;
DWORD dwAttribs = SFGAO_COMPRESSED;
hres = psf->ParseDisplayName(NULL,
NULL,
lpwszDisplayName,
&cbEaten, // This can be NULL
&pidl,
&dwAttribs);
if(dwAttribs & SFGAO_COMPRESSED)
{
// Do something with the compressed file
}
pdwAttributes は in/out パラメーターであるため、常に初期化する必要があります。 初期化されていない値を渡すと、一部のビットが誤って設定される可能性があります。 IShellFolder::P arseDisplayName は、対応する属性のクエリを実行します。これにより、望ましくない遅延やメモリ要求が発生する可能性があります。 属性のクエリを実行しない場合は、予期しない動作を避けるために pdwAttributes を NULL に設定します。
このメソッドは、 IParseDisplayName::P arseDisplayName メソッドに似ています。
要件
要件 | 値 |
---|---|
サポートされている最小のクライアント | Windows XP (デスクトップ アプリのみ) |
サポートされている最小のサーバー | Windows 2000 Server [デスクトップ アプリのみ] |
対象プラットフォーム | Windows |
ヘッダー | shobjidl_core.h (Shobjidl.h を含む) |
[DLL] | Shell32.dll (バージョン 4.0 以降) |