AssocQueryStringW-Funktion (shlwapi.h)

  • Artikel

Sucht nach einer Datei- oder Protokollzuordnungszeichenfolge und ruft sie aus der Registrierung ab.

Syntax

LWSTDAPI AssocQueryStringW(
  [in]            ASSOCF   flags,
  [in]            ASSOCSTR str,
  [in]            LPCWSTR  pszAssoc,
  [in, optional]  LPCWSTR  pszExtra,
  [out, optional] LPWSTR   pszOut,
  [in, out]       DWORD    *pcchOut
);

Parameter

[in] flags

Typ: ASSOCF

Die Flags, mit denen die Suche gesteuert werden kann. Es kann sich um eine beliebige Kombination von ASSOCF-Werten handeln, mit der Ausnahme, dass nur ein ASSOCF_INIT Wert eingeschlossen werden kann.

[in] str

Typ: ASSOCSTR

Der ASSOCSTR-Wert , der den Typ der zurückzugebenden Zeichenfolge angibt.

[in] pszAssoc

Typ: LPCTSTR

Ein Zeiger auf eine NULL-Zeichenfolge, die zum Bestimmen des Stammschlüssels verwendet wird. Die folgenden vier Arten von Zeichenfolgen können verwendet werden.

Dateinamenerweiterung

Eine Dateinamenerweiterung, z. B. .txt.

CLSID

Eine CLSID-GUID im Standardformat "{GUID}".

ProgID

Die ProgID einer Anwendung, z. B. Word. Document.8.

Name der ausführbaren Datei

Der Name der .exe-Datei einer Anwendung. Das ASSOCF_OPEN_BYEXENAME-Flag muss in Flags festgelegt werden.

[in, optional] pszExtra

Typ: LPCTSTR

Eine optionale NULL-Zeichenfolge mit zusätzlichen Informationen zum Speicherort der Zeichenfolge. Es wird in der Regel auf ein Shell-Verb festgelegt, z. B. open. Legen Sie diesen Parameter auf NULL fest, wenn er nicht verwendet wird.

[out, optional] pszOut

Typ: LPTSTR

Zeiger auf eine NULL-beendete Zeichenfolge, die bei erfolgreicher Rückgabe dieser Funktion die angeforderte Zeichenfolge empfängt. Legen Sie diesen Parameter auf NULL fest, um die erforderliche Puffergröße abzurufen.

[in, out] pcchOut

Typ: DWORD*

Ein Zeiger auf einen Wert, der beim Aufrufen der Funktion auf die Anzahl der Zeichen im Puffer pszOut festgelegt wird. Wenn die Funktion erfolgreich zurückgegeben wird, wird der Wert auf die Anzahl der Zeichen festgelegt, die tatsächlich im Puffer platziert sind.

Wenn das ASSOCF_NOTRUNCATE-Flag in Flags festgelegt ist und der in pszOut angegebene Puffer zu klein ist, gibt die Funktion E_POINTER zurück, und der Wert wird auf die erforderliche Größe des Puffers festgelegt.

Wenn pszOutNULL ist, gibt die Funktion S_FALSE- und pcchOut-Punkte auf die erforderliche Größe des Puffers in Zeichen zurück.

Rückgabewert

Typ: HRESULT

Gibt einen COM-Standardfehlerwert zurück, einschließlich der folgenden:

Fehler Bedeutung
S_OK Erfolg.
E_POINTER Der puffer pszOut ist zu klein, um die gesamte Zeichenfolge zu speichern.
S_FALSE pszOut ist NULL. pcchOut enthält die erforderliche Puffergröße.

Hinweise

Diese Funktion ist ein Wrapper für die IQueryAssociations-Schnittstelle . Die AssocQueryString-Funktion soll die Verwendung der IQueryAssociations-Schnittstelle vereinfachen.

Sobald ein Element ausgewählt wurde, muss der Host entscheiden, welcher (falls vorhanden) Vorschauhandler für dieses Element verfügbar ist. Vorschauhandler werden in der Regel für Dateinamenerweiterungen oder ProgID registriert, aber einige Vorschauhandler werden nur für Elemente in bestimmten Shellordnern instanziiert (der MAPI-Vorschauhandler ist z. B. allen Elementen zugeordnet, die aus dem MAPI Shell-Ordner stammen). Daher muss der Host IQueryAssociations verwenden, um zu bestimmen, welcher Vorschauhandler verwendet werden soll. Weitere Informationen zur Funktionsweise der Datei- und Protokollzuordnungsfunktionen finden Sie unter IQueryAssociations.

Hinweis

Der shlwapi.h-Header definiert AssocQueryString als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional, Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile shlwapi.h
Bibliothek Shlwapi.lib
DLL Shlwapi.dll (Version 5.0 oder höher)