Функция AssocQueryStringA (shlwapi.h)

Статья
11/20/2024

Выполняет поиск и получение строки сопоставления файлов или протоколов из реестра.

Синтаксис

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, которая используется для определения корневого ключа. Можно использовать следующие четыре типа строк.

расширение имени файла: расширение имени файла, например .txt.
CLSID: GUID CLSID в стандартном формате "{GUID}".
ProgID: progID приложения, например Word.Document.8.
имя исполняемого файла: имя файла .exe приложения. Флаг ASSOCF_OPEN_BYEXENAME должен быть задан в флагах .

[in, optional] pszExtra

Тип: LPCTSTR

Необязательная строка, завершающаяся значением NULL, с дополнительными сведениями о расположении строки. Обычно для него задано значение команд оболочки, например открыть. Задайте для этого параметра значение NULL, если он не используется.

[out, optional] pszOut

Тип: LPTSTR

Указатель на строку, завершающуюся значением NULL, которая, когда эта функция возвращается успешно, получает запрошенную строку. Задайте для этого параметра значение null, чтобы получить требуемый размер буфера.

[in, out] pcchOut

Тип: DWORD*

Указатель на значение, которое при вызове функции устанавливается на число символов в буфере pszOut. Когда функция возвращается успешно, значение задается числом символов, фактически помещенных в буфер.

Если флаг ASSOCF_NOTRUNCATE задан в флагах , а буфер, указанный в pszOut, слишком мал, функция возвращает E_POINTER, а значение имеет требуемый размер буфера.

Если pszOutNULL, функция возвращает S_FALSE и pcchOut указывает на требуемый размер буфера в символах.

Возвращаемое значение

Тип: HRESULT

Возвращает стандартное значение ошибки COM, в том числе следующее:

Ошибка	Значение
S_OK	Успех.
E_POINTER	Буфер pszOut слишком мал, чтобы сохранить всю строку.
S_FALSE	pszOutNULL. pcchOut содержит требуемый размер буфера.

Замечания

Эта функция представляет собой оболочку для интерфейса IQueryAssociations. Функция assocQueryString предназначена для упрощения процесса использования интерфейса IQueryAssociations.

После выбора элемента узел должен решить, какой обработчик предварительной версии доступен для этого элемента. Обработчики предварительной версии обычно регистрируются в расширениях имени файла или ProgID, но некоторые обработчики предварительного просмотра создаются только для элементов в определенных папках оболочки (обработчик предварительной версии MAPI связан с любыми элементами, поступающими из папки MAPI Shell, например). Таким образом, узел должен использовать IQueryAssociations для определения используемого обработчика предварительной версии. Дополнительные сведения о работе функций сопоставления файлов и протоколов см. в IQueryAssociations.

Заметка

Заголовок shlwapi.h определяет AssocQueryString как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный, Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	shlwapi.h
библиотеки	Shlwapi.lib
DLL	Shlwapi.dll (версия 5.0 или более поздняя версия)

Поделиться через