AssocQueryStringA-Funktion (shlwapi.h)

Artikel
11/20/2024

Sucht nach einer datei- oder protokollzuordnungsbezogenen Zeichenfolge aus der Registrierung und ruft sie 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 aus 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 mit Null beendete Zeichenfolge, die zum Ermitteln 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-: ProgID einer Anwendung, z. B. Word.Document.8-.
Ausführbarer Name: Der Name der .exe Datei einer Anwendung. Das ASSOCF_OPEN_BYEXENAME Flag muss in Flagsfestgelegt werden.

[in, optional] pszExtra

Typ: LPCTSTR-

Eine optionale null-beendete Zeichenfolge mit zusätzlichen Informationen zum Speicherort der Zeichenfolge. Es wird in der Regel auf ein Shell-Verb wie geöffnetefestgelegt. Legen Sie diesen Parameter auf NULL- fest, wenn er nicht verwendet wird.

[out, optional] pszOut

Typ: LPTSTR-

Zeiger auf eine mit Null beendete Zeichenfolge, die, wenn diese Funktion erfolgreich zurückgegeben wird, 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 pszOut Puffer festgelegt ist. Wenn die Funktion erfolgreich zurückgegeben wird, wird der Wert auf die Anzahl der Zeichen festgelegt, die tatsächlich im Puffer platziert wurden.

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 pszOut-NULL-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 standardmäßigen COM-Fehlerwert zurück, einschließlich der folgenden:

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

Bemerkungen

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

Nachdem 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 innerhalb bestimmter Shellordner instanziiert (der MAPI-Vorschauhandler ist beispielsweise 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 Protokollzuordnung finden Sie unter IQueryAssociations.

Anmerkung

Der Header "shlwapi.h" 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
mindestens unterstützte Client-	Windows 2000 Professional, Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	shlwapi.h
Library	Shlwapi.lib
DLL-	Shlwapi.dll (Version 5.0 oder höher)

Freigeben über