Funzione CreateMailslotA (winbase.h)

Articolo
11/20/2024

Crea un oggetto mailslot con il nome specificato e restituisce un handle che un server mailslot può utilizzare per eseguire operazioni sul file mailslot. Mailslot è locale nel computer che lo crea. Se esiste già un messaggio di posta elettronica con il nome specificato, si verifica un errore.

Sintassi

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

Parametri

[in] lpName

Nome del file mailslot. Il nome deve avere il formato seguente:

\\.\mailslot\[ percorso]nome

Il campo nome deve essere univoco. Il nome può includere più livelli di pseudodirectory 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 nel file mailslot, in byte. Per specificare che il messaggio può essere di qualsiasi dimensione, impostare questo valore su zero.

[in] lReadTimeout

L'ora in cui un'operazione di lettura può attendere la scrittura di un messaggio nel file 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 un risultato immediato 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 bInheritHandle membro 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 mailslot, da utilizzare 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 ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

La mailslot esiste fino a quando non viene soddisfatta una delle condizioni seguenti:

L'ultimo handle ,possibilmente 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 definitivamente i messaggi di posta.

Per scrivere un messaggio in un messaggio mailslot, un processo utilizza la funzione CreateFile, specificando il nome mailslot utilizzando uno dei formati seguenti.

Formato	Uso
\\.\mailslot\ nome	Recupera un handle client in un messaggio di posta elettronica locale.
\\nomecomputer\mailslot\nome	Recupera un handle client in un oggetto mailslot remoto.
\\nomedominio\mailslot\nome	Recupera un handle client in tutti i messaggi di posta elettronica con il nome specificato nel dominio specificato.
\\*\mailslot\ nome	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 utilizza il formato asterisco per specificare il dominio primario del sistema, l'applicazione non può scrivere più di 424 byte alla volta nel file 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 un messaggio di posta elettronica.

Se createFile viene chiamato per accedere a un file mailslot inesistente, verrà impostato il codice di errore ERROR_FILE_NOT_FOUND.

Esempi

Per un esempio, vedere Creazione di unMailslot.

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 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