Функция SetPropA (winuser.h)

Статья
08/28/2023

Добавляет новую запись или изменяет существующую запись в списке свойств указанного окна. Функция добавляет новую запись в список, если указанная строка символов еще не существует в списке. Новая запись содержит строку и дескриптор. В противном случае функция заменяет текущий дескриптор строки указанным дескриптором.

Синтаксис

BOOL SetPropA(
  [in]           HWND   hWnd,
  [in]           LPCSTR lpString,
  [in, optional] HANDLE hData
);

Параметры

[in] hWnd

Тип: HWND

Дескриптор для окна, список свойств которого получает новую запись.

[in] lpString

Тип: LPCTSTR

Строка, завершающаяся значением NULL, или атом, идентифицирующий строку. Если этот параметр является атомом, он должен быть глобальным атомом, созданным предыдущим вызовом функции GlobalAddAtom . Атом должен быть помещен в нижнем порядке слово lpString; Слово высокого порядка должно быть равно нулю.

[in, optional] hData

Тип: HANDLE

Дескриптор данных для копирования в список свойств. Дескриптор данных может определить любое значение, полезное для приложения.

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

Тип: BOOL

Если дескриптор данных и строка добавляются в список свойств, возвращаемое значение не равно нулю.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Перед уничтожением окна (т. е. перед возвратом из обработки сообщения WM_NCDESTROY ) приложение должно удалить все записи, добавленные в список свойств. Приложение должно использовать функцию RemoveProp для удаления записей.

На SetProp распространяются ограничения изоляции привилегий пользовательского интерфейса (UIPI). Процесс может вызывать эту функцию только в окне, принадлежащем процессу с меньшим или равным уровнем целостности. Когда UIPI блокирует изменения свойств, GetLastError возвращает значение 5.

Примеры

Пример см. в разделе Добавление свойства окна.

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-window-l1-1-4 (представлено в Windows 10 версии 10.0.14393)