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

Статья
11/20/2024

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

Синтаксис

ATOM GlobalAddAtomA(
  [in] LPCSTR lpString
);

Параметры

[in] lpString

Тип: LPCTSTR

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

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

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

Тип: ATOM

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

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

Замечания

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

Строка, связанная с атомом, не удаляется из памяти, пока ее число ссылок не равно нулю. Дополнительные сведения см. в функции GlobalDeleteAtom.

Глобальные атомы не удаляются автоматически при завершении работы приложения. Для каждого вызова функции GlobalAddAtom должен быть соответствующий вызов функции GlobalDeleteAtom.

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

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

Заметка

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

Требования

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