AssocQueryStringA function (shlwapi.h)

Article
02/09/2023

Searches for and retrieves a file or protocol association-related string from the registry.

Syntax

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

Parameters

[in] flags

Type: ASSOCF

The flags that can be used to control the search. It can be any combination of ASSOCF values, except that only one ASSOCF_INIT value can be included.

[in] str

Type: ASSOCSTR

The ASSOCSTR value that specifies the type of string that is to be returned.

[in] pszAssoc

Type: LPCTSTR

A pointer to a null-terminated string that is used to determine the root key. The following four types of strings can be used.

File name extension: A file name extension, such as .txt.
CLSID: A CLSID GUID in the standard "{GUID}" format.
ProgID: An application's ProgID, such as Word.Document.8.
Executable name: The name of an application's .exe file. The ASSOCF_OPEN_BYEXENAME flag must be set in flags.

[in, optional] pszExtra

Type: LPCTSTR

An optional null-terminated string with additional information about the location of the string. It is typically set to a Shell verb such as open. Set this parameter to NULL if it is not used.

[out, optional] pszOut

Type: LPTSTR

Pointer to a null-terminated string that, when this function returns successfully, receives the requested string. Set this parameter to NULL to retrieve the required buffer size.

[in, out] pcchOut

Type: DWORD*

A pointer to a value that, when calling the function, is set to the number of characters in the pszOut buffer. When the function returns successfully, the value is set to the number of characters actually placed in the buffer.

If the ASSOCF_NOTRUNCATE flag is set in flags and the buffer specified in pszOut is too small, the function returns E_POINTER and the value is set to the required size of the buffer.

If pszOut is NULL, the function returns S_FALSE and pcchOut points to the required size, in characters, of the buffer.

Return value

Type: HRESULT

Returns a standard COM error value, including the following:

Error	Meaning
S_OK	Success.
E_POINTER	The pszOut buffer is too small to hold the entire string.
S_FALSE	pszOut is NULL. pcchOut contains the required buffer size.

Remarks

This function is a wrapper for the IQueryAssociations interface. The AssocQueryString function is intended to simplify the process of using IQueryAssociations interface.

Once an item is selected, the host must decide which (if any) preview handler is available for that item. Preview handlers are typically registered on file name extensions or ProgID, but some preview handlers are only instantiated for items within particular shell folders (the MAPI preview handler is associated with any items that came from the MAPI Shell folder, for example). Thus, the host must use IQueryAssociations to determine which preview handler to use. For further discussion of how the file and protocol association functions work, see IQueryAssociations.

Note

The shlwapi.h header defines AssocQueryString as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional, Windows XP [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (version 5.0 or later)

Share via