AssocQueryStringA 函数 (shlwapi.h)

从注册表中搜索并检索与文件或协议关联相关的字符串。

语法

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

参数

[in] flags

类型： ASSOCF

可用于控制搜索的标志。 它可以是 ASSOCF 值的任意组合，但只能包含一个ASSOCF_INIT值。

[in] str

类型： ASSOCSTR

ASSOCSTR 值，该值指定要返回的字符串的类型。

[in] pszAssoc

类型： LPCTSTR

指向以 null 结尾的字符串的指针，该字符串用于确定根键。 可以使用以下四种类型的字符串。

1. 文件扩展名：文件扩展名，如 .txt。
2. CLSID：采用标准“{GUID}”格式的 CLSID GUID。
3. ProgID：应用程序的 ProgID，例如Word。Document.8.
4. 可执行文件名称：应用程序的 .exe 文件的名称。 必须在标志中设置ASSOCF_OPEN_BYEXENAME标志。

[in, optional] pszExtra

类型： LPCTSTR

一个可选的以 null 结尾的字符串，其中包含有关字符串位置的其他信息。 它通常设置为 Shell 谓词，例如 open。 如果未使用此参数，请将此参数设置为 NULL 。

[out, optional] pszOut

类型： LPTSTR

指向以 null 结尾的字符串的指针，当此函数成功返回时，该字符串接收请求的字符串。 将此参数设置为 NULL 以检索所需的缓冲区大小。

[in, out] pcchOut

类型： DWORD*

指向一个值的指针，在调用函数时，该值设置为 pszOut 缓冲区中的字符数。 函数成功返回时，该值设置为实际放置在缓冲区中的字符数。

如果在标志中设置了ASSOCF_NOTRUNCATE标志，并且 pszOut 中指定的缓冲区太小，则函数将返回E_POINTER并将值设置为所需的缓冲区大小。

如果 pszOut 为 NULL，则该函数将返回S_FALSE， 并且 pcchOut 指向缓冲区的所需大小（以字符为单位）。

返回值

类型： HRESULT

返回标准 COM 错误值，包括以下内容：

错误	含义
S_OK	成功。
E_POINTER	pszOut 缓冲区太小，无法容纳整个字符串。
S_FALSE	pszOut 为 NULL。 pcchOut 包含所需的缓冲区大小。

注解

此函数是 IQueryAssociations 接口的 包装器。 AssocQueryString 函数旨在简化使用 IQueryAssociations 接口的过程。

选择项后，主机必须决定哪个 (是否有任何) 预览处理程序可用于该项目。 预览处理程序通常在文件扩展名或 ProgID 上注册，但某些预览处理程序仅针对特定 shell 文件夹中的项目进行实例化， (MAPI 预览处理程序与来自 MAPI Shell 文件夹的任何项相关联，例如) 。 因此，主机必须使用 IQueryAssociations 来确定要使用的预览处理程序。 有关文件和协议关联函数工作原理的进一步讨论，请参阅 IQueryAssociations。

注意

shlwapi.h 标头将 AssocQueryString 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 专业版、Windows XP [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	shlwapi.h
Library	Shlwapi.lib
DLL	Shlwapi.dll (5.0 或更高版本)