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

Статья
11/20/2024

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

Синтаксис

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 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winuser.h (включая Windows.h)
библиотеки	User32.lib
DLL	User32.dll
набор API	ext-ms-win-ntuser-window-l1-1-4 (представлено в Windows 10 версии 10.0.14393)