GlobalAddAtom

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function adds a character string to the global atom table and returns a unique value, known as an atom, that identifies the string.

Syntax

ATOM GlobalAddAtom(
  LPCTSTR lpString
);

Parameters

• lpString
  [in] Pointer to the null-terminated string that you want to add to the global atom table, or an integer atom that you have converted to a string by using the MAKEINTATOM macro. The string can have a maximum size of 256 bytes. The operating system (OS) considers strings that differ only in case to be identical. The OS preserves the case of the first string of this name that you add to the table.

Return Value

The newly created atom indicates success. 0 indicates failure. To get extended error information, call GetLastError.

Remarks

If the string already exists in the global atom table, GlobalAddAtom returns the atom for the existing string and increments the reference count for the atom.

The OS does not delete the string associated with the atom from memory until the reference count for the atom is zero. For more information, see the GlobalDeleteAtom function.

The OS does not delete global atoms automatically when the application terminates. Every call that an application makes to GlobalAddAtom must be matched by a corresponding call to GlobalDeleteAtom.

If you created the value of lpString by using the MAKEINTATOM macro, the low-order word of lpString must be in the range 0x0001 through 0xBFFF. If the low-order word is not in this range, GlobalAddAtom fails.

If lpString has any other form, GlobalAddAtom returns a string atom.

Requirements

See Also

Reference

GlobalDeleteAtom
GlobalFindAtom
MAKEINTATOM
Atoms Functions