AddAtomA-Funktion (winbase.h)

Artikel
08/27/2023

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

Syntax

ATOM AddAtomA(
  [in] LPCSTR lpString
);

Parameter

[in] lpString

Typ: LPCTSTR

Die hinzuzufügende NULL-Zeichenfolge. Die Zeichenfolge kann eine maximale Größe von 255 Bytes aufweisen. Zeichenfolgen unterscheiden sich nur, wenn sie als identisch gelten. Der Groß-/Kleinschreibung der ersten hinzugefügten Zeichenfolge wird beibehalten und von der GetAtomName-Funktion zurückgegeben.

Alternativ können Sie ein ganzzahliges Atom verwenden, das mit dem MAKEINTATOM-Makro 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

Die AddAtom-Funktion speichert nicht mehr als eine Kopie einer bestimmten Zeichenfolge in der Atomtabelle. Wenn sich die Zeichenfolge bereits in der Tabelle befindet, gibt die Funktion das vorhandene Atom zurück und erhöht im Fall eines Zeichenfolgenatoms die Verweisanzahl der Zeichenfolge.

Wenn lpString das Format "#1234" hat, gibt AddAtom 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 0, was einen Fehler angibt. Wenn lpString vom MAKEINTATOM-Makro erstellt wurde, muss sich das Wort mit niedriger Reihenfolge im Bereich befinden, der bis 0xBFFF 0x0001. Wenn sich das Wort mit niedriger Reihenfolge nicht in diesem Bereich befindet, schlägt die Funktion fehl.

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

Hinweis

Der winbase.h-Header definiert AddAtom 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 nicht codierungsneutralem Code 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 (einschließlich Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll