| ATOM GlobalAddAtom(lpszString) | |||||
| LPCTSTR lpszString; | /* address of string to add | */ | |||
The GlobalAddAtom function adds a string to the system atom table and returns a unique value identifying the string.
lpszString
Points to the null-terminated string to be added. The case of the first string added is preserved and returned by the GlobalGetAtomName function. Strings that differ only in case are considered identical.
The return value identifies the string if the function is successful. Otherwise, the return value is zero.
If the string already exists in the system atom table, the atom for the existing string is returned and the atom's reference count is incremented by one. The string associated with the atom will not be deleted from memory until its reference count is zero (see the description of the GlobalDeleteAtom function).
Global atoms are not automatically deleted when the application terminates. For every call to the GlobalAddAtom function, there must be a corresponding call to the GlobalDeleteAtom function.
The GlobalAddAtom function may be used as either a wide-character function (where text arguments must use Unicode) or an ANSI function (where text arguments must use characters from the Windows 3.x character set installed).
Atoms are not case sensitive.
The atom values returned by GlobalAddAtom are within the range 0xC000 to 0xFFFF. If lpszString has the form “#1234”, this function returns the atom value that is the 16-bit hexadecimal representation of the decimal number specified in the string (0x04D2 in this case). If the decimal value specified is 0x0000 or 0xC000 through 0xFFFF, this function will return 0 to indicate an error. If the address of the string is within the range 0x0001 through 0xBFFF, this function will return the low-order portion of the address as the atom value.
AddAtom, GlobalDeleteAtom, GlobalGetAtomName