Функция AddAtomW (winbase.h)

Статья
08/27/2023

Добавляет строку символов в локальную таблицу atom и возвращает уникальное значение (атом), определяющее строку.

Синтаксис

ATOM AddAtomW(
  [in] LPCWSTR lpString
);

Параметры

[in] lpString

Тип: LPCTSTR

Добавляемая строка, завершающаяся нулевым значением. Строка может иметь максимальный размер 255 байт. Строки, отличающиеся только в случае, считаются идентичными. Регистр первой добавленной строки сохраняется и возвращается функцией GetAtomName .

Кроме того, можно использовать целочисленный атом, преобразованный с помощью макроса MAKEINTATOM . Дополнительные сведения см. в разделе Примечания.

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

Тип: ATOM

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

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

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

Если lpString имеет форму "#1234", AddAtom возвращает целочисленный атом, значение которого является 16-разрядным представлением десятичного числа, указанного в строке (0x04D2 в этом примере). Если указанное десятичное значение 0x0000 или больше или равно 0xC000, возвращаемое значение равно нулю, что указывает на ошибку. Если lpString был создан макросом MAKEINTATOM , слово нижнего порядка должно находиться в диапазоне 0x0001 до 0xBFFF. Если слово нижнего порядка не находится в этом диапазоне, функция завершается ошибкой.

Если lpString имеет любую другую форму, AddAtom возвращает атом строки.

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll