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

Статья
11/20/2024

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

Синтаксис

ATOM AddAtomA(
  [in] LPCSTR lpString
);

Параметры

[in] lpString

Тип: LPCTSTR

Добавляемая строка, завершающаяся значением NULL. Строка может иметь максимальный размер 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 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll