IShellFolder::P arseDisplayName-Methode (shobjidl_core.h)

Übersetzt den Anzeigenamen eines Dateiobjekts oder Ordners in eine Elementbezeichnerliste.

Syntax

HRESULT ParseDisplayName(
  [in]      HWND             hwnd,
  [in]      IBindCtx         *pbc,
  [in]      LPWSTR           pszDisplayName,
  [out]     ULONG            *pchEaten,
  [out]     PIDLIST_RELATIVE *ppidl,
  [in, out] ULONG            *pdwAttributes
);

Parameter

[in] hwnd

Typ: HWND

Ein Fensterhandle. Der Client sollte ein Fensterhandle bereitstellen, wenn ein Dialogfeld oder meldungsfeld angezeigt wird. Legen Sie andernfalls hwnd auf NULL fest.

[in] pbc

Typ: IBindCtx*

Optional. Ein Zeiger auf einen Bindungskontext, der verwendet wird, um Parameter als Eingaben und Ausgaben an die Analysefunktion zu übergeben. Diese übergebenen Parameter sind häufig spezifisch für die Datenquelle und werden von den Datenquellenbesitzern dokumentiert. Beispielsweise akzeptiert die Dateisystemdatenquelle den zu analysierenden Namen (als WIN32_FIND_DATA-Struktur ) mithilfe des STR_FILE_SYS_BIND_DATA bind-Kontextparameters. STR_PARSE_PREFER_FOLDER_BROWSING können übergeben werden, um anzugeben, dass URLs nach Möglichkeit mithilfe der Dateisystemdatenquelle analysiert werden. Erstellen Sie mithilfe von CreateBindCtx ein Bindungskontextobjekt, und füllen Sie die Werte mit IBindCtx::RegisterObjectParam auf. Eine vollständige Liste dieser Schlüssel finden Sie unter Binden von Kontextzeichenfolgenschlüsseln .

Wenn keine Daten an die Analysefunktion übergeben oder von dieser empfangen werden, kann dieser Wert NULL sein.

[in] pszDisplayName

Typ: LPWSTR

Eine mit NULL endende Unicode-Zeichenfolge mit dem Anzeigenamen. Da jeder Shellordner eine eigene Analysesyntax definiert, kann die Form dieser Zeichenfolge variieren. Der Desktopordner akzeptiert für instance Pfade wie "C:\My Docs\My File.txt". Außerdem werden Verweise auf Elemente im Namespace akzeptiert, denen mithilfe der Syntax "::{GUID}" eine GUID zugeordnet ist. Um beispielsweise eine vollqualifizierte Bezeichnerliste für die Systemsteuerung aus dem Desktopordner abzurufen, können Sie Folgendes verwenden:

::{CLSID for Control Panel}\::{CLSID for printers folder}

[out] pchEaten

Typ: ULONG*

Ein Zeiger auf einen ULONG-Wert , der die Anzahl der Zeichen des analysierten Anzeigenamens empfängt. Wenn Ihre Anwendung diese Informationen nicht benötigt, legen Sie pchEaten auf NULL fest, und es wird kein Wert zurückgegeben.

[out] ppidl

Typ: PIDLIST_RELATIVE*

Wenn diese Methode zurückgibt, enthält einen Zeiger auf die PIDL für das -Objekt. Die zurückgegebene Elementbezeichnerliste gibt das Element relativ zum Analyseordner an. Wenn sich das objekt, das pszDisplayName zugeordnet ist, im Analyseordner befindet, enthält die zurückgegebene Elementbezeichnerliste nur eine SHITEMID-Struktur . Wenn sich das Objekt in einem Unterordner des Analyseordners befindet, enthält die zurückgegebene Elementbezeichnerliste mehrere SHITEMID-Strukturen . Wenn ein Fehler auftritt, wird NULL in dieser Adresse zurückgegeben.

Wenn sie nicht mehr benötigt wird, liegt es in der Verantwortung des Aufrufers, diese Ressource durch Aufrufen von CoTaskMemFree frei zu geben.

[in, out] pdwAttributes

Typ: ULONG*

Der Wert, der zum Abfragen von Dateiattributen verwendet wird. Wenn sie nicht verwendet wird, sollte sie auf NULL festgelegt werden. Um ein oder mehrere Attribute abzufragen, initialisieren Sie diesen Parameter mit den SFGAO-Flags , die die relevanten Attribute darstellen. Bei der Rückgabe werden die Attribute festgelegt, die "true" sind und angefordert wurden.

Rückgabewert

Typ: HRESULT

Wenn diese Methode erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Einige Shellordner implementieren möglicherweise nicht IShellFolder::P arseDisplayName. Jeder Ordner, der dies tut, definiert seine eigene Analysesyntax.

Es wird nicht erwartet, dass ParseDisplayName die Indikatoren für den relativen Pfad oder den übergeordneten Ordner ("." oder "..") behandelt. Es liegt an dem Aufrufer, diese entsprechend zu entfernen.

Verwenden Sie nicht das flag SFGAO_VALIDATE in pdwAttributes , um das Vorhandensein des Elements zu überprüfen, dessen Name analysiert wird. IShellFolder::P arseDisplayName überprüft implizit das Vorhandensein des Elements, es sei denn, dieses Verhalten wird durch einen speziellen Bindungskontextparameter überschrieben.

Das Abfragen nach einigen Attributen kann relativ langsam sein und erhebliche Mengen an Arbeitsspeicher beanspruchen. Um beispielsweise zu ermitteln, ob eine Datei freigegeben ist, lädt die Shell Netzwerkkomponenten. Dieses Verfahren erfordert möglicherweise das Laden mehrerer DLLs. Der Zweck von pdwAttributes besteht darin, die Abfrage auf die benötigten Informationen zu beschränken. Das folgende Codefragment veranschaulicht, wie Sie herausfinden, ob eine Datei komprimiert ist.

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
}

Da pdwAttributes ein in/out-Parameter ist, sollte er immer initialisiert werden. Wenn Sie einen nicht initialisierten Wert übergeben, werden einige der Bits möglicherweise versehentlich festgelegt. IShellFolder::P arseDisplayName fragt dann die entsprechenden Attribute ab, was zu unerwünschten Verzögerungen oder Arbeitsspeicheranforderungen führen kann. Wenn Sie keine Attribute abfragen möchten, legen Sie pdwAttributes auf NULL fest, um unvorhersehbares Verhalten zu vermeiden.

Diese Methode ähnelt der IParseDisplayName::P arseDisplayName-Methode .

Anforderungen

Weitere Informationen

IShellFolder

IShellFolder2

IShellFolder::GetAttributesOf

IShellLink