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 Instanzzeiger für die Minifiltertreiberinstanz, an die die Erstellungsanforderung gesendet werden soll. Die Instanz muss an das Volume für das benannte Pipe-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 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-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-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 (ACL-) und besitzerinformationen, die der benannten Pipe zugeordnet sind, können gelesen werden. |
| FILE_WRITE_DATA | Daten können in das 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 des benannten Pipes. |
| 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 | Ordnet DesiredAccess Flags zu |
|---|---|
| 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
Ein 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 | Die Anzahl der Bytes von Daten, die in der Struktur enthalten sind, auf die durch ObjectAttributesverwiesen wird. Dieser Wert muss mindestens Größe(OBJECT_ATTRIBUTES) sein. |
| PUNICODE_STRING ObjectName- | Ein Zeiger auf eine UNICODE_STRING Struktur, die den Namen der zu erstellenden oder geöffneten Pfeife 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\NamedPipe\mypipe" oder "\?? \pipe\mypipe" kann 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- | Ein optionales Handle für ein Verzeichnis, das durch einen vorherigen Aufruf von FltCreateFileEx2abgerufen wird. Wenn dieser Wert NULL-ist, muss das element ObjectNameeine vollqualifizierte Dateispezifikation sein, die den vollständigen Pfad zur Zielpipeline enthält. Wenn dieser Wert nichtNULL-ist, gibt das element ObjectName 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 durch einen solchen Sicherheitsdeskriptor angegeben werden, werden nur auf die Pipe angewendet, wenn sie erstellt wird. Wenn der Wert NULL- ist, wenn eine Pipe erstellt wird, hängt die ACL, die auf der Pipe platziert wird, vom benannten Pipedateisystem ab und kann einem Client mit jedem Zugriff auf die Erstellung einer Instanz erlauben. |
| ULONG Attributes | 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
Ein Zeiger auf eine IO_STATUS_BLOCK Struktur, die den endgültigen Abschlussstatus und Informationen zum angeforderten Vorgang empfängt. Bei rückgabe von FltCreateNamedPipeFileenthält das Information Member der Variablen einen der folgenden Werte:
FILE_CREATED
FILE_OPENED
[in] ShareAccess
Der Typ des Freigabezugriffs auf die Datei, die der Aufrufer als eine oder eine Kombination der folgenden Flags benötigt. Geben Sie für die größte Chance, Fehler bei der Freigabeverletzung zu vermeiden, alle folgenden Freigabezugriffskennzeichnungen an.
| ShareAccess- Flags | Bedeutung |
|---|---|
| FILE_SHARE_READ | Die Datei kann für den Lesezugriff durch Aufrufe anderer Threads an FltCreateNamedPipeFilegeöffnet werden. |
| FILE_SHARE_WRITE | Die Datei kann für den Schreibzugriff durch Aufrufe anderer Threads an FltCreateNamedPipeFilegeöffnet werden. |
[in] CreateDisposition
Ein Wert, der die auszuführende Aktion bestimmt, je nachdem, ob die Datei bereits vorhanden ist. Der Wert kann eine 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, schlagen Sie 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 Pfeife angewendet werden sollen, als kompatible Kombination der folgenden Flags.
| CreateOptions- Flags | Bedeutung |
|---|---|
| FILE_WRITE_THROUGH | Systemdienste, Rohrsysteme und Treiber, die Daten in das Rohr 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-attribut FILE_NO_INTERMEDIATE_BUFFERING festgelegt ist. |
| FILE_SYNCHRONOUS_IO_ALERT | Alle Vorgänge auf dem Rohr werden synchron ausgeführt. Jede Wartezeit im Auftrag des Anrufers unterliegt einer vorzeitigen Kündigung durch Warnungen. Diese Kennzeichnung bewirkt auch, dass das E/A-System den Rohrpositionskontext 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 auf dem Rohr 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] NamedPipeType
Typ der zu erstellenden benannten Pipe. Dies kann einer der folgenden Werte sein:
[in] ReadMode
Der Modus, der aus der Pfeife gelesen werden soll.
[in] CompletionMode
Der Vervollständigungsmodus für Pipe-Lese- und Schreibvorgänge.
[in] MaximumInstances
Die maximale Anzahl von Instanzen, die für diese benannte 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 wird 250 Millisekunden als –10 * 1000 * 250 angegeben.
[in, optional] DriverContext
Ein optionaler Zeiger auf eine IO_DRIVER_CREATE_CONTEXT Struktur, die bereits von IoInitializeDriverCreateContextinitialisiert wurde.
Rückgabewert
FltCreateNamedPipeFile gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. einen der folgenden.
| Rückgabecode | Beschreibung |
|---|---|
|
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. |
|
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 FltCreateNamedPipeFile--Funktion ermöglicht minifiltertreibern das Erstellen oder Öffnen von Pipeinstanzen. Dies ist nützlich zum Erstellen virtueller Rohre oder zum Erstellen von Rohrgewerkschaften für Multiplexing-E/A.
Die Instanz Parameter ist entweder NULL- oder wird zuvor durch Anfügen an das benannte Pipevolume 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 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 FltCreateNamedPipeFileist die ECP-Liste unverändert und kann an zusätzliche Aufrufe von FltCreateNamedPipeFile für andere Erstellungsvorgänge übergeben werden. Die ECP-Listenstruktur wird nicht automatisch umverteilt. Der Aufrufer von FltCreateNamedPipeFile- muss diese Struktur umgehen, indem die FltFreeExtraCreateParameterList Routine aufgerufen wird.
Wenn Instance- nicht NULL-ist, wird die Create-Anforderung von FltCreateNamedPipeFile- nur an die Instanzen gesendet, die unterhalb der angegebenen Minifiltertreiberinstanz und an das benannte Pipe-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 benannten Pipedateisystem 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