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
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | shobjidl_core.h (shobjidl.h einschließen) |
| DLL | Shell32.dll (Version 4.0 oder höher) |