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

Комментарии

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

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

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

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

См. также

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

DeleteAtom

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

ATOM DeleteAtom (

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

);

Параметры

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

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

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

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

Комментарии

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

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

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

См. также

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

FindAtom

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

ATOM FindAtom (

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

);

Параметры

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

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

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

Комментарии

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

См. также

AddAtom, DeleteAtom, GlobalAddAtom, GlobalDeleteAtom, GlobalFindAtom .

GetAtomName

Функция GetAtomName возвращает копию символьной строки, связанной с указанным локальным атомом. Эта функция заменяет функцию GetAtomHandle .

UINT GetAtomName (

ATOM nAtom , // атом, идентифицирующий символьную строку

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

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

);

Параметры

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

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

nSize - определяет размер буфера в символах.

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

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

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

Примечания

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

См. также

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

GlobalAddAtom

Функция GlobalAddAtom добавляет строку символов в таблицу глобальных атомов и возвращает уникальное значение (атом), идентифицирующее строку.

ATOM GlobalAddAtom (

LPCTSTR lpString // указатель на добавляемую строку

);

Параметры

lpString - указатель на добавляемую строку, завершающуюся нулем. Строка может иметь максимальный размер в 255 байт. Строки, отличающиеся только регистром, считаются идентичными.

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

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

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

Комментарии

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

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

Глобальные атомы не удаляются автоматически по завершению приложения. Для каждого вызова функции 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 уменьшает счетчик ссылок глобальной строки атома. Если счетчик ссылок атома достигает нулевого значения, GlobalDeleteAtom удаляет строку, связанную с атомом, из таблицы глобальных атомов.

ATOM GlobalDeleteAtom (

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

);

Параметры

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

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

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

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

Комментарии

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

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

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

См. также

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

GlobalFindAtom

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