Функция GlobalAddAtomA (winbase.h)
Добавляет строку символов в глобальную таблицу atom и возвращает уникальное значение (атом), определяющее строку.
Синтаксис
ATOM GlobalAddAtomA(
[in] LPCSTR lpString
);
Параметры
[in] lpString
Тип: LPCTSTR
Добавляемая строка, завершающаяся нулевым значением. Строка может иметь максимальный размер 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 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | winbase.h (включая Windows.h) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |
См. также
Справочные материалы