FltCreateMailslotFile-Funktion (fltkernel.h)
Minifiltertreiber rufen FltCreateMailslotFile- auf, um eine neue Pipe zu erstellen oder ein vorhandenes Maillot zu öffnen.
Syntax
NTSTATUS FLTAPI FltCreateMailslotFile(
[in] PFLT_FILTER Filter,
[in, optional] PFLT_INSTANCE Instance,
[out] PHANDLE FileHandle,
[out, optional] PFILE_OBJECT *FileObject,
[in] ULONG DesiredAccess,
[in] POBJECT_ATTRIBUTES ObjectAttributes,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] ULONG CreateOptions,
[in] ULONG MailslotQuota,
[in] ULONG MaximumMessageSize,
[in] PLARGE_INTEGER ReadTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
Parameter
[in] Filter
Ein undurchsichtiger Filterzeiger für den Aufrufer.
[in, optional] Instance
Ein undurchsichtiger Instanzzeiger für die Minifiltertreiberinstanz, an die die Erstellungsanforderung gesendet werden soll. Die Instanz muss an das Volume für das Maillot-Dateisystem angefügt werden. Dieser Parameter ist optional und kann NULL-werden. Wenn dieser Parameter NULL-ist, wird die Anforderung am oberen Rand des Dateisystemtreiberstapels für das Volume an das Geräteobjekt gesendet. Wenn es nichtNULL-ist, wird die Anforderung nur an Minifiltertreiberinstanzen gesendet, die unterhalb der angegebenen Instanz angefügt sind.
[out] FileHandle
Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die das Dateihandle empfängt, wenn der Aufruf von FltCreateMailslotFile- erfolgreich ist.
[out, optional] FileObject
Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die den Dateiobjektzeiger empfängt, wenn der Aufruf von FltCreateMailslotFile erfolgreich ist. Dieser Parameter ist optional und kann NULL-werden.
[in] DesiredAccess
Eine Bitmaske von Flags, die den Typ des Zugriffs angeben, den der Aufrufer für die Datei oder das Verzeichnis benötigt. Der Satz systemdefinierter DesiredAccess Flags bestimmt die folgenden spezifischen Zugriffsrechte für Dateiobjekte.
| DesiredAccess-Flag | Bedeutung |
|---|---|
| FILE_READ_DATA | Daten können aus dem benannten Maillot gelesen werden. |
| FILE_READ_ATTRIBUTES | FileAttributes Flags können gelesen werden. Weitere Informationen finden Sie in der Tabelle der gültigen Flagwerte im FileAttributes Parameter von FltCreateFileEx2. |
| READ_CONTROL | Die Zugriffssteuerungsliste ACL- und besitzerinformationen, die dem Maillot zugeordnet sind, können gelesen werden. |
| FILE_WRITE_DATA | Daten können in das Maillot geschrieben werden. |
| FILE_WRITE_ATTRIBUTES | FileAttributes Flags können geschrieben werden. |
| FILE_APPEND_DATA | Daten können an den Maillot angefügt werden. |
| WRITE_DAC | Die diskretionäre Zugriffssteuerungsliste DACL-, die dem Maillot zugeordnet ist, kann geschrieben werden. |
| WRITE_OWNER | Eigentümerinformationen, die dem Maillot zugeordnet sind, können geschrieben werden. |
| ACCESS_SYSTEM_SECURITY | Der Anrufer hat Schreibzugriff auf die SACL des Maillots. |
| SYNCHRONISIEREN | Der Aufrufer kann den Abschluss eines E/A-Vorgangs synchronisieren, indem auf die zurückgegebene FileHandle- auf den Signalzustand festgelegt wird. Dieses Kennzeichen muss festgelegt werden, wenn die CreateOptions- FILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERT Flag festgelegt ist. |
Alternativ können Sie für jedes Dateiobjekt, das kein Verzeichnis darstellt, eines oder mehrere der folgenden generischen ACCESS_MASK Flags angeben. (Die STANDARD_RIGHTS_XXX- Flags sind vordefinierte Systemwerte, die zum Erzwingen der Sicherheit auf Systemobjekten verwendet werden.) Sie können diese generischen Flags auch mit zusätzlichen Flags aus der vorherigen Tabelle kombinieren.
| DesiredAccess to File Values | Zugeordnet zu DesiredAccess-Flags |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA und SYNCHRONISIEREN. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA und SYNCHRONISIEREN. |
[in] ObjectAttributes
Zeiger auf eine undurchsichtige OBJECT_ATTRIBUTES Struktur, die bereits mit InitializeObjectAttributesinitialisiert wird. Wenn der Aufrufer im Systemprozesskontext ausgeführt wird, kann dieser Parameter NULL-sein. Andernfalls muss der Aufrufer das attribut OBJ_KERNEL_HANDLE im Aufruf von InitializeObjectAttributesfestlegen. Elemente dieser Struktur für ein Dateiobjekt werden in der folgenden Tabelle aufgeführt.
| Mitglied | Wert |
|---|---|
| ULONG Length | Anzahl der Bytes von Daten, die in der Struktur enthalten sind, auf die durch ObjectAttributesverwiesen wird. Dieser Wert muss mindestens sizeof(OBJECT_ATTRIBUTES)sein. |
| PUNICODE_STRING ObjectName- | Zeigen Sie auf eine UNICODE_STRING Struktur, die den Namen des zu erstellenden oder geöffneten Maillots enthält. Dieser Name muss eine vollqualifizierte Dateispezifikation oder der Name eines Geräteobjekts sein, es sei denn, es handelt sich um den Namen einer Datei relativ zum Verzeichnis, das durch RootDirectoryangegeben wird. Beispiel: "\Device\Mailslot\myslot" oder "?? \mailslot\myslot" könnte beide gültige Dateispezifikationen sein. (Hinweis: "??" ersetzt "\DosDevices" als Namen des Win32-Objektnamespaces. "\DosDevices" funktioniert weiterhin, aber "??" wird vom Objekt-Manager schneller übersetzt. |
| HANDLE RootDirectory- | Optionales Handle zu einem Verzeichnis, das durch einen vorherigen Aufruf von FltCreateFileEx2abgerufen wird. Wenn dieser Wert NULL-ist, muss der ObjectName Member eine vollqualifizierte Dateispezifikation sein, die den vollständigen Pfad zum Zielmaillot enthält. Wenn dieser Wert nichtNULL-ist, gibt das ObjectName Member einen maillot-Namen an, der relativ zu diesem Verzeichnis ist. |
| PSECURITY_DESCRIPTOR SecurityDescriptor- | Optionaler SECURITY_DESCRIPTOR, der auf ein Maillot angewendet werden soll. ACLs, die durch einen solchen Sicherheitsdeskriptor angegeben werden, werden nur auf den Maillot angewendet, wenn er erstellt wird. Wenn der Wert NULL- ist, wenn ein Maillot erstellt wird, hängt die im Maillot platzierte ACL vom Maillot-Dateisystem ab und kann einem Client mit jedem Zugriff auf die Erstellung einer Instanz erlauben. |
| ULONG-Attribute | Eine Reihe von Flags, die die Dateiobjektattribute steuern. Wenn der Aufrufer im Systemprozesskontext ausgeführt wird, kann dieser Parameter null sein. Andernfalls muss der Aufrufer das OBJ_KERNEL_HANDLE Flag festlegen. Der Aufrufer kann optional auch das OBJ_CASE_INSENSITIVE Flag festlegen, das angibt, dass der Name-Nachschlagecode die Groß-/Kleinschreibung ObjectName- ignorieren soll, anstatt eine Suche mit exakter Übereinstimmung durchzuführen. |
[out] IoStatusBlock
Zeigen Sie auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Vorgang empfängt. Bei rückgabe von FltCreateMailslotFileenthält das Information Member der Variablen einen der folgenden Werte:
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
Die Optionen, die beim Erstellen oder Öffnen des Maillots angewendet werden sollen, als kompatible Kombination der folgenden Flags.
| Flaggen | Bedeutung |
|---|---|
| FILE_WRITE_THROUGH | Systemdienste, Dateisysteme und Treiber, die Daten in das Maillot schreiben, müssen die Daten tatsächlich in das Maillot übertragen, bevor ein angeforderter Schreibvorgang als abgeschlossen betrachtet wird. Dieses Flag wird automatisch festgelegt, wenn das CreateOptions-attribut FILE_NO_INTERMEDIATE_BUFFERING festgelegt ist. |
| FILE_SYNCHRONOUS_IO_ALERT | Alle Vorgänge im Maillot werden synchron ausgeführt. Jede Wartezeit im Auftrag des Anrufers unterliegt einer vorzeitigen Kündigung durch Warnungen. Dieses Kennzeichen bewirkt auch, dass das E/A-System den E-Maillot-Positionskontext aufrecht erhält. Wenn dieses Flag festgelegt ist, muss das flag DesiredAccess SYNCHRONIZE ebenfalls festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. |
| FILE_SYNCHRONOUS_IO_NONALERT | Alle Vorgänge im Maillot werden synchron ausgeführt. Wartezeiten im System, um die E/A-Warteschlange zu synchronisieren und den Abschluss zu vervollständigen, unterliegen nicht warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext aufrecht erhält. Wenn dieses Flag festgelegt ist, muss das flag DesiredAccess SYNCHRONIZE ebenfalls festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. |
[in] MailslotQuota
Die Größe des Puffers in Bytes für Schreibvorgänge in das Maillot.
[in] MaximumMessageSize
Die maximale Größe einer Nachricht in Byte, die in den Maillot geschrieben werden soll. Eine Meldung einer beliebigen Größe wird durch den Wert 0 angegeben.
[in] ReadTimeout
Die Zeit, zu der ein Lesevorgang wartet, bis eine Nachricht im Maillot verfügbar ist. Das Standardtimeout wird in 100-Nanosekunden-Schritten als negative ganze Zahl ausgedrückt. Beispielsweise wird 250 Millisekunden als –10*1000*250angegeben. Darüber hinaus haben die folgenden Werte besondere Bedeutungen.
| Wert | Bedeutung |
|---|---|
| 0 | Gibt sofort zurück, wenn keine Nachricht vorhanden ist. |
| -1 | Wartet für immer auf eine Nachricht. |
[in, optional] DriverContext
Optionaler Zeiger auf eine IO_DRIVER_CREATE_CONTEXT Struktur, die bereits von IoInitializeDriverCreateContextinitialisiert wurde.
Rückgabewert
FltCreateMailslotFile gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert wie einen der folgenden zurück.
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_FLT_DELETING_OBJECT | Der im Filter oder Instanz Parameter angegebene Filter oder Instanz wird heruntergerissen. Dieser Statuscode kann empfangen werden, wenn die offene Anforderung einen Volume-Bereitstellungspunkt überschreitet und der Parameter Instance nichtNULL-ist. Dies ist ein Fehlercode. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | Der ObjectAttributes- Parameter enthielt kein RootDirectory-element, aber das ObjectName-Element in der OBJECT_ATTRIBUTES-Struktur war eine leere Zeichenfolge oder enthielt kein OBJECT_NAME_PATH_SEPARATOR Zeichen. Dieser Fehlercode gibt eine falsche Syntax für den Objektpfad an. |
Bemerkungen
Die FltCreateMailslotFile Funktion ermöglicht Minifiltertreibern das Erstellen oder Öffnen von Maillot-Instanzen. Dies ist nützlich zum Erstellen virtueller Mailslots oder zum Erstellen einer Maillot-Gruppe, die an mehrere andere E-Mailslots verteilt wird.
Der Parameter Instance ist entweder NULL- oder wird zuvor durch Anfügen an das Maillot-Volume festgelegt. Ein Volumezeiger wird abgerufen, indem "\Device\Mailslot" als Volumename an FltGetVolumeFromNameübergeben wird.
Um einen zusätzlichen Create-Parameter (ECP) als Teil eines Erstellungsvorgangs anzugeben, initialisieren Sie den ExtraCreateParameter Member der IO_DRIVER_CREATE_CONTEXT Struktur mit der FltAllocateExtraCreateParameterList Routine. Wenn ECPs verwendet werden, müssen sie mithilfe ihrer zugehörigen Supportroutinen zugewiesen, initialisiert und freigegeben werden. Beim Zurückgeben vom Aufruf von FltCreateMailslotFileist die ECP-Liste unverändert und kann an zusätzliche Aufrufe von FltCreateMailslotFile für andere Erstellungsvorgänge übergeben werden. Die ECP-Listenstruktur wird nicht automatisch umverteilt. Der Aufrufer von FltCreateMailslotFile- muss diese Struktur umgehen, indem die FltFreeExtraCreateParameterList Routine aufgerufen wird.
Wenn Instanz- nicht NULL-ist, wird die Erstellungsanforderung von FltCreateMailslotFile nur an die Instanzen gesendet, die unterhalb der angegebenen Minifiltertreiberinstanz und an das Maillot-Dateisystem angefügt sind. Die angegebene Instanz und die oben angefügten Instanzen erhalten nicht die Erstellungsanforderung. Wenn keine Instanz angegeben ist, wechselt die Anforderung an den Anfang des Stapels und wird von allen Instanzen und dem Maillot-Dateisystem empfangen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Verfügbar in Windows 8. |
| Zielplattform- | Universal |
| Header- | fltkernel.h (include FltKernel.h) |
| Library | Fltmgr.lib |
| IRQL- | PASSIVE_LEVEL |
Siehe auch
FltAllocateExtraCreateParameterList