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 nicht transparenter instance-Zeiger für den Minifiltertreiber instance, an den die Erstellungsanforderung gesendet werden soll. Die instance muss an das Volume für das Dateisystem mailslot angefügt werden. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter NULL ist, wird die Anforderung an das Geräteobjekt am Anfang des Dateisystemtreiberstapels für das Volume gesendet. Wenn es nicht NULL ist, wird die Anforderung nur an Minifiltertreiberinstanzen gesendet, die unterhalb der angegebenen instance angefügt sind.
[out] FileHandle
Ein Zeiger auf eine vom Aufrufer zugeordnete Variable, die das Dateihandle empfängt, wenn der Aufruf von FltCreateMailslotFile erfolgreich ist.
[out, optional] FileObject
Ein Zeiger auf eine vom Aufrufer zugeordnete Variable, die den Dateiobjektzeiger empfängt, wenn der Aufruf von FltCreateMailslotFile erfolgreich ist. Dieser Parameter ist optional und kann NULL sein.
[in] DesiredAccess
Eine Bitmaske von Flags, die den Typ des Zugriffs angeben, den der Aufrufer auf 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 und die Besitzinformationen, 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 das Maillot angefügt werden. |
| WRITE_DAC | Die dem Maillot zugeordnete DACL der zugriffskontrollierten Zugriffssteuerungsliste kann geschrieben werden. |
| WRITE_OWNER | Dem Maillot zugeordnete Besitzinformationen können geschrieben werden. |
| ACCESS_SYSTEM_SECURITY | Der Aufrufer hat Schreibzugriff auf die SACL des Maillots. |
| SYNCHRONIZE | Der Aufrufer kann den Abschluss eines E/A-Vorgangs synchronisieren, indem er darauf wartet, dass der zurückgegebene FileHandle-Wert auf den Signaled-Zustand festgelegt wird. Dieses Flag muss festgelegt werden, wenn das Flag CreateOptions FILE_SYNCHRONOUS_IO_ALERT oder FILE_SYNCHRONOUS_IO_NONALERT 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 von Sicherheit für Systemobjekte verwendet werden.) Sie können diese generischen Flags auch mit zusätzlichen Flags aus der vorherigen Tabelle kombinieren.
| DesiredAccess to File Values | Zuordnung zu DesiredAccess-Flags |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA und SYNCHRONIZE. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA und SYNCHRONIZE. |
[in] ObjectAttributes
Zeiger auf eine nicht transparente OBJECT_ATTRIBUTES Struktur, die bereits mit InitializeObjectAttributes initialisiert wurde. Wenn der Aufrufer im Systemprozesskontext ausgeführt wird, kann dieser Parameter NULL sein. Andernfalls muss der Aufrufer das attribut OBJ_KERNEL_HANDLE im Aufruf auf InitializeObjectAttributes festlegen. Member dieser Struktur für ein Dateiobjekt werden in der folgenden Tabelle aufgeführt.
| Mitglied | Wert |
|---|---|
| ULONG-Länge | Anzahl der Byte von Daten, die in der Struktur enthalten sind, auf die von ObjectAttributes verwiesen wird. Dieser Wert muss mindestens sizeof(OBJECT_ATTRIBUTES)sein. |
| PUNICODE_STRING ObjectName | Zeiger auf eine UNICODE_STRING Struktur, die den Namen des zu erstellenden oder zu öffnenden 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 durch RootDirectory angegebenen Verzeichnis. Beispiel: "\Device\Mailslot\myslot" oder "?? \mailslot\myslot" könnte gültige Dateispezifikationen sein. (Hinweis: "??" ersetzt "\DosDevices" durch den Namen des Win32-Objektnamespace. "\DosDevices" funktioniert weiterhin, aber "??" wird vom Objekt-Manager schneller übersetzt. |
| HANDLE RootDirectory | Optionales Handle für ein Verzeichnis, abgerufen durch einen vorherigen Aufruf von FltCreateFileEx2. Wenn dieser Wert NULL ist, muss das ObjectName-Element eine vollqualifizierte Dateispezifikation sein, die den vollständigen Pfad zum Ziel-Mailslot enthält. Wenn dieser Wert ungleich NULL ist, gibt das ObjectName-Element einen Maillotnamen an, der relativ zu diesem Verzeichnis ist. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Optionale SECURITY_DESCRIPTOR , die auf ein Maillot angewendet werden soll. AcLs , die von einem solchen Sicherheitsdeskriptor angegeben werden, werden nur auf das Maillot angewendet, wenn es erstellt wird. Wenn der Wert NULL ist, wenn ein Maillot erstellt wird, hängt die im Maillot platzierte ACL vom Dateisystem mailslot ab und kann einem Client mit beliebigem Zugriff erlauben, eine instance zu erstellen. |
| ULONG-Attribute | Ein Satz von Flags, der die Dateiobjektattribute steuert. Wenn der Aufrufer im Systemprozesskontext ausgeführt wird, kann dieser Parameter null sein. Andernfalls muss der Aufrufer das flag OBJ_KERNEL_HANDLE festlegen. Der Aufrufer kann optional auch das flag OBJ_CASE_INSENSITIVE festlegen, was angibt, dass name-lookup code die Groß-/Kleinschreibung von ObjectName ignorieren sollte, anstatt eine Suche nach exakter Übereinstimmung durchzuführen. |
[out] IoStatusBlock
Zeiger auf eine IO_STATUS_BLOCK-Struktur, die den endgültigen Abschluss status und Informationen zum angeforderten Vorgang empfängt. Bei der Rückgabe von FltCreateMailslotFile enthält das Information-Element der Variablen einen der folgenden Werte:
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
Die Optionen, die beim Erstellen oder Öffnen des Mailslots als kompatible Kombination der folgenden Flags angewendet werden sollen.
| Flags | 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-Flag FILE_NO_INTERMEDIATE_BUFFERING festgelegt ist. |
| FILE_SYNCHRONOUS_IO_ALERT | Alle Vorgänge im Maillot werden synchron ausgeführt. Jede Wartezeit im Namen des Anrufers unterliegt einer vorzeitigen Beendigung von Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Maillotpositionskontext behält. Wenn dieses Flag festgelegt ist, muss auch das DesiredAccess SYNCHRONIZE-Flag 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 E/A-Warteschlangen und -Abschluss zu synchronisieren, unterliegen keinen Warnungen. Dieses Flag bewirkt auch, dass das E/A-System den Dateipositionskontext verwaltet. Wenn dieses Flag festgelegt ist, muss auch das DesiredAccess SYNCHRONIZE-Flag festgelegt werden, damit der E/A-Manager das Dateiobjekt als Synchronisierungsobjekt verwendet. |
[in] MailslotQuota
Die Größe des Puffers für Schreibvorgänge in das Maillot in Bytes.
[in] MaximumMessageSize
Die maximale Größe einer Nachricht in Bytes, die in das Maillot geschrieben werden soll. Eine Nachricht beliebiger Größe wird durch den Wert 0 angegeben.
[in] ReadTimeout
Die Zeit, zu der ein Lesevorgang wartet, bis eine Nachricht im Mailslot verfügbar ist. Das Standardtimeout wird in Schritten von 100 Nanosekunden als negative ganze Zahl ausgedrückt. Beispielsweise werden 250 Millisekunden als –10*1000*250angegeben. Darüber hinaus haben die folgenden Werte eine besondere Bedeutung.
| Wert | Bedeutung |
|---|---|
| 0 | Gibt sofort zurück, wenn keine Nachricht vorhanden ist. |
| -1 | Wartet ewig auf eine Nachricht. |
[in, optional] DriverContext
Optionaler Zeiger auf eine IO_DRIVER_CREATE_CONTEXT Struktur, die bereits von IoInitializeDriverCreateContext initialisiert wurde.
Rückgabewert
FltCreateMailslotFile gibt STATUS_SUCCESS oder einen entsprechenden NTSTATUS-Wert zurück, z. B. einen der folgenden.
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_FLT_DELETING_OBJECT | Der filter oder instance, der im Parameter Filter oder Instance angegeben ist, wird abgerissen. Dieser status Code kann empfangen werden, wenn die offene Anforderung einen Volumeeinbindungspunkt kreuzt und der Instance-Parameter nicht NULL 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. |
Hinweise
Mit der Funktion FltCreateMailslotFile können Minifiltertreiber Mailslot-Instanzen erstellen oder öffnen. Dies ist nützlich, um virtuelle Mailslots zu erstellen oder eine Maillotgruppe zu erstellen, die an mehrere andere Mailslots verteilt wird.
Der Instanzparameter ist entweder NULL oder wird zuvor durch Anfügen an das Volume "mailslot" 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 das ExtraCreateParameter-Element der IO_DRIVER_CREATE_CONTEXT-Struktur mit der FltAllocateExtraCreateParameterList-Routine . Wenn ECPs verwendet werden, müssen sie mithilfe der zugehörigen Supportroutinen zugeordnet, initialisiert und freigegeben werden. Wenn sie vom Aufruf von FltCreateMailslotFile zurückgegeben wird, bleibt 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 zugeordnet. Der Aufrufer von FltCreateMailslotFile muss die Zuordnung dieser Struktur durch Aufrufen der FltFreeExtraCreateParameterList-Routine beheben.
Wenn Instance nicht NULL ist, wird die Erstellungsanforderung von FltCreateMailslotFile nur an die Instanzen gesendet, die unterhalb des angegebenen Minifiltertreibers instance und an das Dateisystem mailslot angefügt sind. Die angegebenen instance und die darüber angefügten Instanzen empfangen die Erstellungsanforderung nicht. Wenn kein instance angegeben ist, wird die Anforderung an den Anfang des Stapels geleitet und von allen Instanzen und dem Dateisystem mailslot empfangen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar in Windows 8. |
| Zielplattform | Universell |
| Header | fltkernel.h (include FltKernel.h) |
| Bibliothek | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Weitere Informationen
FltAllocateExtraCreateParameterList