AssocQueryStringA-Funktion (shlwapi.h)

Artikel
03/04/2024

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

Syntax

LWSTDAPI AssocQueryStringA(
  [in]            ASSOCF   flags,
  [in]            ASSOCSTR str,
  [in]            LPCSTR   pszAssoc,
  [in, optional]  LPCSTR   pszExtra,
  [out, optional] LPSTR    pszOut,
  [in, out]       DWORD    *pcchOut
);

Parameter

[in] flags

Typ: ASSOCF

Die Flags, die zum Steuern der Suche verwendet werden können. 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-endende Zeichenfolge, die zum Bestimmen des Stammschlüssels verwendet wird. Die folgenden vier Zeichenfolgentypen können verwendet werden.

Dateinamenerweiterung: Eine Dateinamenerweiterung, z. B. .txt.
CLSID: Eine CLSID-GUID im Standardformat "{GUID}".
ProgID: 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-beendete Zeichenfolge mit zusätzlichen Informationen zum Speicherort der Zeichenfolge. Es ist 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-endende Zeichenfolge, die die angeforderte Zeichenfolge empfängt, wenn diese Funktion erfolgreich zurückgegeben wird. 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 pszOut-Puffer 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 zurück, und pcchOut zeigt auf die erforderliche Größe des Puffers in Zeichen.

Rückgabewert

Typ: HRESULT

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

Fehler	Bedeutung
S_OK	Erfolg.
E_POINTER	Der pszOut-Puffer 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.

Nachdem ein Element ausgewählt wurde, muss der Host entscheiden, welcher Vorschauhandler (falls vorhanden) 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 die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, 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)

Freigeben über