Funzione CreateMailslotA (winbase.h)

Articolo
03/09/2024

Crea una mailslot con il nome specificato e restituisce un handle che un server mailslot può usare per eseguire operazioni sulla mailslot. La mailslot è locale nel computer che lo crea. Si verifica un errore se esiste già un messaggio di posta elettronica con il nome specificato.

Sintassi

HANDLE CreateMailslotA(
  [in]           LPCSTR                lpName,
  [in]           DWORD                 nMaxMessageSize,
  [in]           DWORD                 lReadTimeout,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Parametri

[in] lpName

Nome della mailslot. Questo nome deve avere il modulo seguente:

\\.\mailslot\[path]name

Il campo nome deve essere univoco. Il nome può includere più livelli di pseudo directory separate da barre rovesciate. Ad esempio, sia \\.\mailslot\example_mailslot_name che \\.\mailslot\abc\def\ghi sono nomi validi.

[in] nMaxMessageSize

Dimensione massima di un singolo messaggio che può essere scritto nella mailslot, in byte. Per specificare che il messaggio può essere di qualsiasi dimensione, impostare questo valore su zero.

[in] lReadTimeout

Il tempo in cui un'operazione di lettura può attendere che un messaggio venga scritto nella mailslot prima che si verifichi un timeout, in millisecondi. I valori seguenti hanno significati speciali.

Valore	Significato
0	Restituisce immediatamente se non è presente alcun messaggio. Il sistema non considera una restituzione immediata come errore.
MAILSLOT_WAIT_FOREVER ((DWORD)-1)	Attende per sempre un messaggio.

Questo valore di timeout si applica a tutte le operazioni di lettura successive e a tutti gli handle mailslot ereditati.

[in, optional] lpSecurityAttributes

Puntatore a una struttura SECURITY_ATTRIBUTES . Il membro bInheritHandle della struttura determina se l'handle restituito può essere ereditato dai processi figlio. Se lpSecurityAttributes è NULL, l'handle non può essere ereditato.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è un handle per la mailslot, da usare nelle operazioni mailslot del server. L'handle restituito da questa funzione è asincrono o sovrapposto.

Se la funzione ha esito negativo, il valore restituito è INVALID_HANDLE_VALUE. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

La mailslot esiste fino a quando non è true una delle condizioni seguenti:

L'ultimo handle ereditato o duplicato viene chiuso usando la funzione CloseHandle .
Il processo proprietario dell'ultimo handle (eventualmente ereditato o duplicato) viene chiuso.

Il sistema usa il secondo metodo per eliminare mailslots.

Per scrivere un messaggio in una mailslot, un processo usa la funzione CreateFile , specificando il nome mailslot usando uno dei formati seguenti.

Formato	Utilizzo
\\.\mailslot\name	Recupera un handle client in una mailslot locale.
\\computername\mailslot\name	Recupera un handle client in una mailslot remota.
\\domainname\mailslot\name	Recupera un handle client in tutti i mailslot con il nome specificato nel dominio specificato.
\\\mailslot\name*	Recupera un handle client in tutti i messaggi di posta elettronica con il nome specificato nel dominio primario del sistema.

Se CreateFile specifica un dominio o usa il formato asterisco per specificare il dominio primario del sistema, l'applicazione non può scrivere più di 424 byte alla volta alla mailslot. Se l'applicazione tenta di eseguire questa operazione, la funzione WriteFile ha esito negativo e GetLastError restituisce ERROR_BAD_NETPATH.

Un'applicazione deve specificare il flag di FILE_SHARE_READ quando si usa CreateFile per recuperare un handle client in una mailslot.

Se CreateFile viene chiamato per accedere a una mailslot non esistente, verrà impostato il codice di errore ERROR_FILE_NOT_FOUND .

Esempio

Per un esempio, vedere Creazione di una mailslot.

Nota

L'intestazione winbase.h definisce CreateMailslot come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll