CreateMailslotA-Funktion (winbase.h)

Artikel
11/20/2024

Erstellt einen Maillot mit dem angegebenen Namen und gibt ein Handle zurück, mit dem ein Maillot-Server Vorgänge für den Maillot ausführen kann. Der Maillot ist lokal auf dem Computer, der es erstellt. Wenn bereits ein Maillot mit dem angegebenen Namen vorhanden ist, tritt ein Fehler auf.

Syntax

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

Parameter

[in] lpName

Der Name des Maillots. Dieser Name muss das folgende Formular aufweisen:

\\.\mailslot\[Pfad]Namen

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

[in] nMaxMessageSize

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

[in] lReadTimeout

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

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

Dieser Timeoutwert gilt für alle nachfolgenden Lesevorgänge und alle geerbten Maillot-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, für die Verwendung in Servermaillot-Vorgängen. Das von dieser Funktion zurückgegebene Handle ist asynchron oder überlappend.

Wenn die Funktion fehlschlägt, wird der Rückgabewert INVALID_HANDLE_VALUE. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Der Maillot ist vorhanden, bis eine der folgenden Bedingungen zutrifft:

Der letzte (möglicherweise geerbte oder duplizierte) Handle wird mit der CloseHandle--Funktion geschlossen.
Der Prozess, der den letzten (möglicherweise geerbten oder duplizierten) Handle besitzt, 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 Maillots mithilfe eines der folgenden Formate angegeben wird.

Format	Verwendung
\\.\mailslot\Name	Ruft ein Clienthandle zu einem lokalen Maillot ab.
\\Computername\mailslot\Name	Ruft ein Clienthandle zu einem Remotemaillot ab.
\\Domänenname\mailslot\Namen	Ruft ein Clienthandle für alle Maillots mit dem angegebenen Namen in der angegebenen Domäne ab.
\\\mailslot\Name*	Ruft ein Clienthandle für alle Maillots mit dem angegebenen Namen in der primären Domäne des Systems ab.

Wenn CreateFile- eine Domäne angibt oder das Sternchenformat verwendet, um die primäre Domäne des Systems anzugeben, kann die Anwendung nicht mehr als 424 Byte gleichzeitig in das Maillot schreiben. Wenn die Anwendung versucht, dies zu tun, schlägt die WriteFile--Funktion fehl und GetLastError gibt ERROR_BAD_NETPATHzurück.

Eine Anwendung muss das FILE_SHARE_READ-Flag angeben, wenn CreateFile- zum Abrufen eines Clienthandle zu einem Maillot verwendet wird.

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 Creating a Mailslot.

Anmerkung

Der winbase.h-Header definiert CreateMailslot als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, 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
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winbase.h (enthalten Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll