Funzione GlobalAddAtomA (winbase.h)

Articolo
11/20/2024

Aggiunge una stringa di caratteri alla tabella atom globale e restituisce un valore univoco (un atomo) che identifica la stringa.

Sintassi

ATOM GlobalAddAtomA(
  [in] LPCSTR lpString
);

Parametri

[in] lpString

Tipo: LPCTSTR

Stringa con terminazione Null da aggiungere. La stringa può avere una dimensione massima di 255 byte. Le stringhe che differiscono solo nel caso siano considerate identiche. Il caso della prima stringa di questo nome aggiunta alla tabella viene mantenuta e restituita dalla funzione GlobalGetAtomName.

In alternativa, è possibile utilizzare un atomo intero convertito utilizzando la macro MAKEINTATOM. Per altre informazioni, vedere la sezione Osservazioni.

Valore restituito

Tipo: atom

Se la funzione ha esito positivo, il valore restituito è l'atom appena creato.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

Se la stringa esiste già nella tabella atom globale, viene restituito l'atomo per la stringa esistente e il conteggio dei riferimenti dell'atom viene incrementato.

La stringa associata all'atom non viene eliminata dalla memoria fino a quando il numero di riferimenti non è zero. Per altre informazioni, vedere la funzione GlobalDeleteAtom.

Gli atom globali non vengono eliminati automaticamente quando l'applicazione termina. Per ogni chiamata alla funzione GlobalAddAtom, deve essere presente una chiamata corrispondente alla funzione GlobalDeleteAtom .

Se il parametro lpString ha il formato "#1234", GlobalAddAtom restituisce un atom intero il cui valore è la rappresentazione a 16 bit del numero decimale specificato nella stringa (0x04D2, in questo esempio). Se il valore decimale specificato è 0x0000 o è maggiore o uguale a 0xC000, il valore restituito è zero, che indica un errore. Se lpString è stato creato dalla macro MAKEINTATOM , la parola in ordine basso deve essere compresa nell'intervallo 0x0001 da 0xBFFF. Se la parola in ordine basso non è in questo intervallo, la funzione ha esito negativo.

Se lpString ha un altro formato, GlobalAddAtom restituisce un atom di stringa.

Nota

L'intestazione winbase.h definisce GlobalAddAtom come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winbase.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll