CreateMailslotA-Funktion (winbase.h)

Artikel
03/06/2024

Erstellt ein Maillot mit dem angegebenen Namen und gibt ein Handle zurück, das ein maillot-Server zum Ausführen von Vorgängen für das Maillot verwenden kann. Das Mailslot ist lokal für den Computer, der es erstellt. Ein Fehler tritt auf, wenn bereits ein Maillot mit dem angegebenen Namen vorhanden ist.

Syntax

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

Parameter

[in] lpName

Der Name des Mailslots. Dieser Name muss die folgende Form aufweisen:

\\.\mailslot\[Pfad]name

Das Feld name muss eindeutig sein. Der Name kann mehrere Ebenen von Pseudoverzeichnissen enthalten, die durch umgekehrte Schrägstriche getrennt sind. Beispielsweise sind \\.\mailslot\example_mailslot_name und \\.\mailslot\abc\def\ghi gültige Namen.

[in] nMaxMessageSize

Die maximale Größe einer einzelnen Nachricht, die in das Maillot geschrieben werden kann, in Bytes. Um anzugeben, dass die Nachricht eine beliebige Größe haben kann, legen Sie diesen Wert auf 0 fest.

[in] lReadTimeout

Die Zeit, zu der ein Lesevorgang warten kann, bis eine Nachricht in das Maillot geschrieben wird, bevor ein Timeout auftritt, in Millisekunden. Die folgenden Werte haben eine besondere Bedeutung.

Wert	Bedeutung
0	Gibt sofort zurück, wenn keine Nachricht vorhanden ist. (Das System behandelt eine sofortige Rückgabe nicht als Fehler.)
MAILSLOT_WAIT_FOREVER ((DWORD)-1)	Wartet ewig auf eine Nachricht.

Dieser Timeoutwert gilt für alle nachfolgenden Lesevorgänge und alle geerbten Mailslot-Handles.

[in, optional] lpSecurityAttributes

Ein Zeiger auf eine SECURITY_ATTRIBUTES-Struktur . Das bInheritHandle-Element der Struktur bestimmt, ob das zurückgegebene Handle von untergeordneten Prozessen geerbt werden kann. Wenn lpSecurityAttributesNULL ist, kann das Handle nicht geerbt werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Maillot, das in Server-Mailslot-Vorgängen verwendet werden kann. Das von dieser Funktion zurückgegebene Handle ist asynchron oder überlappend.

Wenn die Funktion fehlschlägt, ist der Rückgabewert INVALID_HANDLE_VALUE. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Das Mailslot ist so lange vorhanden, bis eine der folgenden Bedingungen erfüllt ist:

Das letzte (möglicherweise geerbte oder duplizierte) Handle wird mit der CloseHandle-Funktion geschlossen.
Der Prozess, der das letzte (möglicherweise geerbte oder duplizierte) Handle besitzt, wird beendet.

Das System verwendet die zweite Methode, um Mailslots zu zerstören.

Um eine Nachricht in ein Maillot zu schreiben, verwendet ein Prozess die CreateFile-Funktion , wobei der Name des Mailslots mithilfe eines der folgenden Formate angegeben wird.

Format	Verbrauch
\\.\mailslot\name	Ruft ein Clienthandle zu einem lokalen Maillot ab.
\\computername\mailslot\name	Ruft ein Clienthandle zu einem Remotemaillot ab.
\\domänenname\mailslot\name	Ruft ein Clienthandle für alle Mailslots mit dem angegebenen Namen in der angegebenen Domäne ab.
\\\mailslot\name*	Ruft ein Clienthandle für alle Mailslots mit dem angegebenen Namen in der primären Domäne des Systems ab.

Wenn CreateFile eine Domäne angibt oder das Sternchenformat zum Angeben der primären Domäne des Systems verwendet, kann die Anwendung nicht mehr als 424 Bytes gleichzeitig in das Maillot schreiben. Wenn die Anwendung dies versucht, schlägt die WriteFile-Funktion fehl, und GetLastError gibt ERROR_BAD_NETPATH zurück.

Eine Anwendung muss das FILE_SHARE_READ-Flag angeben, wenn Sie CreateFile verwenden, um ein Clienthandle für ein Maillot abzurufen.

Wenn CreateFile aufgerufen wird, um auf ein nicht vorhandenes Maillot zuzugreifen, wird der ERROR_FILE_NOT_FOUND Fehlercode festgelegt.

Beispiele

Ein Beispiel finden Sie unter Erstellen eines Mailslots.

Hinweis

Der winbase.h-Header definiert CreateMailslot 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

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