Тарас Сорока - Русский справочник по Win32 API

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

GlobalAddAtomвозвращает строковый атом, чье значение лежит в диапазоне от 0 xC 000 до 0 xFFFF .

Если значение lpString имеет вид "#1234", GlobalAddAtomвозвращает целый атом, чье значение являет собой 16-битное представление десятичного числа, указанного в строке (в данном случае 0 x 04 D 2). Если указанное десятичное значение представляет собой 0 x 0000 или значение, лежащее в диапазоне от 0 xC 000 до 0 xFFFF, возвращается нуль, указывающий на ошибку. Если значение lpString лежит в диапазоне от 0 x 0001 до 0 xBFFF, возвращается младшее слово lpString .

Для преобразования значения WORD в строку, которая может быть добавлена функцией GlobalAddAtomв таблицу атомов, может быть использован макрос MAKEINTATOM.

См . также

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName, MAKEINTATOM.

Функция GlobalDeleteAtomуменьшает счетчик ссылок глобальной строки атома. Если счетчик ссылок атома достигает нулевого значения, GlobalDeleteAtomудаляет строку, связанную с атомом, из таблицы глобальных атомов.

ATOM GlobalDeleteAtom(

ATOM nAtom // удаляемый атом

);

Параметры

nAtom - идентифицирует удаляемые атом и строку символов.

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

В случае успеха возвращается нуль.

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

Комментарии

Счетчик ссылок строки атома определяет, сколько раз строка была добавлена или удалена в/из таблицы глобальных атомов. Функция GlobalDeleteAtomуменьшает счетчик ссылок строки, которая уже содержится в таблице глобальных атомов, при каждом вызове.

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

Вызов GlobalDeleteAtomне воздействует на целый атом (атом, созданный макросом MAKEINTATOM). Функция всегда возвращает нуль для целого атома.

См. также

AddAtom, DeleteAtom, FindAtom, GlobalAddAtom, GlobalFindAtom, MAKEINTATOM.

Функция GlobalFindAtomищет в таблице глобальных атомов заданную строку символов и возвращает глобальный атом, связанный с данной строкой.

ATOM GlobalFindAtom(

LPCTSTR lpString // указатель на строку поиска

);

Параметры

lpString - указывает на завершающуюся нулем строку символов.

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

В случае успеха возвращается глобальный атом, связанный с данной строкой.

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

Комментарии

Несмотря на то, что Windows сохраняет регистр строки в таблице атомов, поиск, выполняемый функцией GlobalFindAtom, не чувствителен к регистру.

См. также

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalGetAtomName.

Функция GlobalGetAtomNameизвлекает копию строки символов, связанной с указанным глобальным атомом.

UINT GlobalGetAtomName(

ATOM nAtom , // идентификатор атома

LPTSTR lpBuffer , // указатель на буфер для строки

int nSize // размер буфера

);

Параметры

nAtom - идентифицирует глобальный атом, связанный с извлекаемой строкой символов.

lpBuffer - указывает на буфер для строки символов.

nSize - указывает размер буфера в символах.

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

В случае успеха возвращается длина строки, в символах, скопированной в буфер, не считая завершающий нулевой символ.

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

Комментарии

Строка, возвращаемая для целого атома (атома, созданного макросом MAKEINTATOM), представляет собой завершающуюся нулем строку, в которой первым символом является символ фунта ('#'), а оставшиеся символы - беззнаковое целое, первоначально переданное в макрос MAKEINTATOM.

См. также

AddAtom, DeleteAtom, FindAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, MAKEINTATOM.

Функция InitAtomTableинициализирует таблицу локальных атомов и задает ее размер.

BOOL InitAtomTable(

DWORD nSize // размер таблицы атомов

);

Параметры

nSize - задает размер, в количестве элементов, таблицы атомов. Этот параметр должен представлять собой простое число.

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

В случае успеха возвращается ненулевое значение.

В случае неудачи возвращается нуль.

Комментарии

Приложению нет необходимости использовать эту функцию для использования таблицы локальных атомов. Размер по умолчанию таблиц локальных и глобальных атомов составляет 37 элементов. Если приложение использует функцию InitAtomTable, то, впрочем, оно должно вызвать эту функцию перед любой другой функцией управления атомами.

Если приложение использует большое число локальных атомов, оно может уменьшить время, необходимое для добавления атома в таблицу локальных атомов или для поиска атома в таблицы, увеличив размер таблицы. Однако, это увеличит количество памяти, необходимое для таблицы.

Размер таблицы глобальных атомов не может быть изменен.

См. также

AddAtom, DeleteAtom, FindAtom, GetAtomName, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom, GlobalGetAtomName.

Макрос MAKEINTATOMсоздает целый атом, который представляет символьную строку десятичных цифр.

Целые атомы, созданные этим макросом, могут быть добавлены в таблицу атомов, используя функции AddAtomили GlobalAddAtom.

LPTSTR MAKEINTATOM(

WORD wInteger // целое для создания атома

);

Параметры

wInteger - определяет числовое значение, из которого создается целый атом.

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

Возвращается указатель на атом, созданный из данного целого.

Комментарии

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

Вызовы функций DeleteAtomи GlobalDeleteAtomвсегда успешны для целых атомов.