GlobalAddAtom

函式功能

只適用於桌面應用程式。

向全局原子表添加一個字元串，並返回這個字元串的唯一標識符（原子ATOM）。

函式原型

ATOM WINAPI GlobalAddAtom(

_In_ LPCTSTR lpString

);

參數

lpString [in]

類型: LPCTSTR

一個以"\0"結尾的字元串。這個字元串的長度最大為255位元組（ The string can have a maximum size of 255 bytes，我的理解應該是TCHAR的長度最大為255，即最多可以有255字元，而不是位元組）。不區分字元串的大寫或者小寫，二者均被認為是相同的。字元串保存到全局原子表中，可以通過GlobalGetAtomName函式得到添加的字元串。

或者，你也可以使用MAKEINTATOM宏創建一個整數原子。更多有關信息，請參閱“備註”。

返回值

類型: ATOM

函式調用成功，則返回值為新創建的原子（ATOM）。

若函式調用失敗，則返回值為0。調用GetLastError獲得更多的錯誤信息。

備註

如果字元串中已經存在於全局原子表中，則返回現有的字元串的原子，並且原子的引用計數加1。

與原子相關的字元串不會從記憶體中刪除，直到它的引用計數為零。欲了解更多信息，請參閱GlobalDeleteAtom函式。

全局原子不會在應用程式終止時自動刪除。每次調用GlobalAddAtom函式，必須相應的調用GlobalDeleteAtom函式刪除原子。

如果lpString的形式為"#1234"，GlobalAddAtom返回一個整數原子，其值是這個十進制數指定的字元串（在這個例子中為0x04D2）。如果指定的十進制值是0x0000或大於等於0xC000，返回值為零，操作失敗。如果lpString使用MAKEINTATOM宏創建的字元串，低16位值的範圍是0x0001到0xBFFF。如果值不在此範圍內，則操作失敗。

如果lpString是其他形式的字元串，則GlobalAddAtom返回這個字元串原子。

MAKEINTATOM宏的定義如下：

#define MAKEINTATOM(i) (LPTSTR)((ULONG_PTR)((WORD)(i)))

系統需求

Minimum supported client: Windows 2000 Professional

Minimum supported server: Windows 2000 Server

Header: Winbase.h (include Windows.h)

Library: Kernel32.lib

DLL: Kernel32.dll

Unicode and ANSI names: GlobalAddAtomW (Unicode) and GlobalAddAtomA (ANSI)