FltCreateNamedPipeFile-Funktion (fltkernel.h)
Minifiltertreiber rufen FltCreateNamedPipeFile auf, um eine neue Pipe zu erstellen oder eine vorhandene Pipe zu öffnen.
Syntax
NTSTATUS FLTAPI FltCreateNamedPipeFile(
[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 ShareAccess,
[in] ULONG CreateDisposition,
[in] ULONG CreateOptions,
[in] ULONG NamedPipeType,
[in] ULONG ReadMode,
[in] ULONG CompletionMode,
[in] ULONG MaximumInstances,
ULONG InboundQuota,
ULONG OutboundQuota,
[in, optional] PLARGE_INTEGER DefaultTimeout,
[in, optional] PIO_DRIVER_CREATE_CONTEXT DriverContext
);
Parameter
[in] Filter
Ein undurchsichtiger Filterzeiger für den Aufrufer.
[in, optional] Instance
Ein undurchsichtiger instance Zeiger für den Minifiltertreiber instance, an den die Erstellungsanforderung gesendet werden soll. Die instance muss an das Volume für das Named Pipe-Dateisystem angefügt werden. Dieser Parameter ist optional und kann NULL sein. Wenn dieser Parameter NULL ist, wird die Anforderung an das Geräteobjekt am oberen Rand des Dateisystemtreiberstapels für das Volume gesendet. Wenn sie 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 zugewiesene Variable, die das Dateihandle empfängt, wenn der Aufruf von FltCreateNamedPipeFile erfolgreich ist.
[out, optional] FileObject
Ein Zeiger auf eine vom Aufrufer zugewiesene Variable, die den Dateiobjektzeiger empfängt, wenn der Aufruf von FltCreateNamedPipeFile 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-Flags | Bedeutung |
|---|---|
| FILE_READ_DATA | Daten können aus der benannten Pipe 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 (Access Control List, ACL) und die Besitzinformationen, die der benannten Pipe zugeordnet sind, können gelesen werden. |
| FILE_WRITE_DATA | Daten können in die benannte Pipe geschrieben werden. |
| FILE_WRITE_ATTRIBUTES | FileAttributes-Flags können geschrieben werden. |
| FILE_APPEND_DATA | Daten können an die Datei angefügt werden. |
| WRITE_DAC | Die diskretionäre Zugriffssteuerungsliste (DACL), die der benannten Pipe zugeordnet ist, kann geschrieben werden. |
| WRITE_OWNER | Besitzerinformationen, die der benannten Pipe zugeordnet sind, können geschrieben werden. |
| ACCESS_SYSTEM_SECURITY | Der Aufrufer hat Schreibzugriff auf die SACL der benannten Pipe. |
| SYNCHRONIZE | Der Aufrufer kann den Abschluss eines E/A-Vorgangs synchronisieren, indem er darauf wartet, dass der zurückgegebene FileHandle-Wert auf den Signalzustand festgelegt wird. Dieses Flag muss festgelegt werden, wenn das 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 von Systemobjekten 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
Ein Zeiger auf eine undurchsichtige OBJECT_ATTRIBUTES Struktur, die bereits mit InitializeObjectAttributes initialisiert ist. 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 InitializeObjectAttributes festlegen. Member dieser Struktur für ein Dateiobjekt werden in der folgenden Tabelle aufgeführt.
| Mitglied | Wert |
|---|---|
| ULONG-Länge | Die Anzahl der Bytes 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 | Ein Zeiger auf eine UNICODE_STRING-Struktur , die den Namen der zu erstellenden oder zu öffnenden Pipe 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 von RootDirectory angegebenen Verzeichnis. Beispiel: "\Device\NamedPipe\mypipe" oder "\?? \pipe\mypipe" können gültige Dateispezifikationen sein. (Hinweis: "\??" ersetzt "\DosDevices" als Namen des Win32-Objektnamespaces. "\DosDevices" funktioniert weiterhin, aber "\??" wird vom Objekt-Manager schneller übersetzt.) |
| HANDLE RootDirectory | Ein optionales Handle für ein Verzeichnis, das durch einen vorherigen Aufruf von FltCreateFileEx2 abgerufen wurde. Wenn dieser Wert NULL ist, muss das ObjectName-Elementeine vollqualifizierte Dateispezifikation sein, die den vollständigen Pfad zur Zielpipeline enthält. Wenn dieser Wert nicht NULL ist, gibt das ObjectName-Element einen Pipenamen an, der relativ zu diesem Verzeichnis ist. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Ein optionaler Sicherheitsdeskriptor (SECURITY_DESCRIPTOR), der auf eine Pipe angewendet werden soll. AcLs , die von einem solchen Sicherheitsdeskriptor angegeben werden, werden nur auf die Pipe angewendet, wenn sie erstellt wird. Wenn der Wert NULL ist, wenn eine Pipe erstellt wird, ist die auf der Pipe platzierte ACL vom Dateisystem der benannten Pipe abhängig und kann einem Client mit beliebigem Zugriff das Erstellen einer instance ermöglichen. |
| ULONG-Attribute | Eine Reihe von Flags, die die Dateiobjektattribute steuern. Wenn der Aufrufer im Systemprozesskontext ausgeführt wird, kann dieser Parameter 0 sein. Andernfalls muss der Aufrufer das flag OBJ_KERNEL_HANDLE festlegen. Der Aufrufer kann auch optional das OBJ_CASE_INSENSITIVE-Flag festlegen, das angibt, dass name-lookup code die Groß-/Kleinschreibung von ObjectName ignorieren soll, anstatt eine Suche nach exakter Übereinstimmung durchzuführen. |
[out] IoStatusBlock
Ein Zeiger auf eine IO_STATUS_BLOCK-Struktur, die die endgültige Vervollständigung status und Informationen zum angeforderten Vorgang empfängt. Beim Zurückgeben von FltCreateNamedPipeFile enthält das Information-Element der Variablen einen der folgenden Werte:
FILE_CREATED
FILE_OPENED
[in] ShareAccess
Der Typ des Freigabezugriffs auf die Datei, den der Aufrufer als eine oder eine Kombination der folgenden Flags benötigt. Geben Sie alle folgenden Freigabezugriffsflags an, um die größte Chance zu vermeiden, Fehler bei der Freigabeverletzung zu vermeiden.
| ShareAccess-Flags | Bedeutung |
|---|---|
| FILE_SHARE_READ | Die Datei kann für den Lesezugriff durch Aufrufe anderer Threads an FltCreateNamedPipeFile geöffnet werden. |
| FILE_SHARE_WRITE | Die Datei kann für den Schreibzugriff durch Aufrufe anderer Threads an FltCreateNamedPipeFile geöffnet werden. |
[in] CreateDisposition
Ein Wert, der die auszuführende Aktion bestimmt, je nachdem, ob die Datei bereits vorhanden ist. Der Wert kann einer der in der folgenden Tabelle beschriebenen Werte sein.
| CreateDisposition-Werte | Bedeutung |
|---|---|
| FILE_CREATE | Wenn die Datei bereits vorhanden ist, schlägt die Anforderung fehl, und erstellen oder öffnen Sie die angegebene Datei nicht. Wenn dies nicht der Fall ist, erstellen Sie die Datei. |
| FILE_OPEN | Wenn die Datei bereits vorhanden ist, öffnen Sie sie, anstatt eine neue Datei zu erstellen. Wenn dies nicht der Fall ist, schlägt die Anforderung fehl, und erstellen Sie keine neue Datei. |
| FILE_OPEN_IF | Wenn die Datei bereits vorhanden ist, öffnen Sie sie. Wenn dies nicht der Fall ist, erstellen Sie die Datei. |
[in] CreateOptions
Die Optionen, die beim Erstellen oder Öffnen der Pipe als kompatible Kombination der folgenden Flags angewendet werden sollen.
| CreateOptions-Flags | Bedeutung |
|---|---|
| FILE_WRITE_THROUGH | Systemdienste, Pipesysteme und Treiber, die Daten in die Pipe schreiben, müssen die Daten tatsächlich in die Pipe ü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 in der Pipe 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 Pipepositionskontext 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 in der Pipe 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] NamedPipeType
Typ der zu erstellenden Named Pipe. Folgenden Werte sind möglich:
[in] ReadMode
Der Modus zum Lesen aus der Pipe.
[in] CompletionMode
Der Vervollständigungsmodus für Pipelese- und Schreibvorgänge.
[in] MaximumInstances
Die maximale Anzahl von Instanzen, die für diese Named Pipe zulässig sind.
InboundQuota
Die Anzahl der Bytes, die für den Eingabepuffer reserviert werden sollen.
OutboundQuota
Die Anzahl der Bytes, die für den Ausgabepuffer reserviert werden sollen.
[in, optional] DefaultTimeout
Das Standardtimeout in 100-Nanosekunden-Schritten. Dieser Wert wird als negative ganze Zahl ausgedrückt. Beispielsweise werden 250 Millisekunden als –10 * 1000 * 250 angegeben.
[in, optional] DriverContext
Ein optionaler Zeiger auf eine IO_DRIVER_CREATE_CONTEXT Struktur, die bereits von IoInitializeDriverCreateContext initialisiert wurde.
Rückgabewert
FltCreateNamedPipeFile gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden.
| Rückgabecode | Beschreibung |
|---|---|
|
Der filter oder instance, der in den Parametern Filter oder Instance angegeben ist, wird abgerissen. Dieser status Code kann empfangen werden, wenn die offene Anforderung einen Volumebereitstellungspunkt überschreitet und der Instance-Parameter ungleich NULL ist. Dies ist ein Fehlercode. |
|
Der Parameter ObjectAttributes 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 FltCreateNamedPipeFile können Minifiltertreiber Pipeinstanzen erstellen oder öffnen. Dies ist nützlich, um virtuelle Rohre zu erstellen oder Pipe-Unions für Multiplexing-E/A zu erstellen.
Der parameter instance ist entweder NULL oder wurde zuvor durch Anfügen an das Named Pipe-Volume festgelegt. Ein Volumezeiger wird abgerufen, indem "\Device\NamedPipe" 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 FltCreateNamedPipeFile zurückgegeben wird, bleibt die ECP-Liste unverändert und kann für andere Erstellungsvorgänge an zusätzliche Aufrufe von FltCreateNamedPipeFile übergeben werden. Die ECP-Listenstruktur wird nicht automatisch aufgehoben. Der Aufrufer von FltCreateNamedPipeFile muss die Zuordnung dieser Struktur aufheben, indem er die FltFreeExtraCreateParameterList-Routine aufruft .
Wenn Instance nicht NULL ist, wird die Erstellungsanforderung von FltCreateNamedPipeFile nur an die Instanzen gesendet, die unterhalb des angegebenen Minifiltertreibers instance und an das Named Pipe-Dateisystem angefügt sind. Die angegebene 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 weitergeleitet und von allen Instanzen und dem Named Pipe-Dateisystem empfangen.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar in Windows 8. |
| Zielplattform | Universell |
| Header | fltkernel.h (fltKernel.h einschließen) |
| Bibliothek | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Weitere Informationen
FltAllocateExtraCreateParameterList