GlobalAddAtomA-Funktion (winbase.h)

Artikel
08/27/2023

Fügt der globalen Atomtabelle eine Zeichenfolge hinzu und gibt einen eindeutigen Wert (ein Atom) zurück, der die Zeichenfolge identifiziert.

Syntax

ATOM GlobalAddAtomA(
  [in] LPCSTR lpString
);

Parameter

[in] lpString

Typ: LPCTSTR

Die hinzuzufügende NULL-endende Zeichenfolge. Die Zeichenfolge kann eine maximale Größe von 255 Bytes haben. Zeichenfolgen, die sich nur in der Groß-/Kleinschreibung unterscheiden, gelten als identisch. Die Groß-/Kleinschreibung der ersten Zeichenfolge dieses Namens, die der Tabelle hinzugefügt wurde, wird beibehalten und von der GlobalGetAtomName-Funktion zurückgegeben.

Alternativ können Sie ein ganzzahliges Atom verwenden, das mithilfe des MAKEINTATOM-Makros konvertiert wurde. Weitere Informationen finden Sie in den Hinweisen.

Rückgabewert

Typ: ATOM

Wenn die Funktion erfolgreich ist, ist der Rückgabewert das neu erstellte Atom.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn die Zeichenfolge bereits in der globalen Atomtabelle vorhanden ist, wird das Atom für die vorhandene Zeichenfolge zurückgegeben, und die Verweisanzahl des Atoms wird erhöht.

Die dem Atom zugeordnete Zeichenfolge wird erst aus dem Arbeitsspeicher gelöscht, wenn die Verweisanzahl null ist. Weitere Informationen finden Sie in der GlobalDeleteAtom-Funktion .

Globale Atome werden nicht automatisch gelöscht, wenn die Anwendung beendet wird. Für jeden Aufruf der GlobalAddAtom-Funktion muss ein entsprechender Aufruf der GlobalDeleteAtom-Funktion vorhanden sein.

Wenn der lpString-Parameter die Form "#1234" hat, gibt GlobalAddAtom ein ganzzahliges Atom zurück, dessen Wert die 16-Bit-Darstellung der in der Zeichenfolge angegebenen Dezimalzahl ist (in diesem Beispiel 0x04D2). Wenn der angegebene Dezimalwert 0x0000 oder größer oder gleich 0xC000 ist, ist der Rückgabewert null, was auf einen Fehler hinweist. Wenn lpString vom MAKEINTATOM-Makro erstellt wurde, muss sich das Wort mit niedriger Ordnung im Bereich befinden, der bis 0xBFFF 0x0001. Wenn sich das Wort mit niedriger Ordnung nicht in diesem Bereich befindet, schlägt die Funktion fehl.

Wenn lpString eine andere Form aufweist, gibt GlobalAddAtom ein Zeichenfolgenatom zurück.

Hinweis

Der winbase.h-Header definiert GlobalAddAtom als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll