Função FltCreateNamedPipeFile (fltkernel.h)
Os drivers de minifiltro chamam FltCreateNamedPipeFile para criar um novo pipe ou abrir um pipe existente.
Sintaxe
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
);
Parâmetros
[in] Filter
Um ponteiro de filtro opaco para o chamador.
[in, optional] Instance
Um ponteiro de instância opaco para a instância do driver de minifiltro para a qual a solicitação de criação deve ser enviada. A instância deve ser anexada ao volume do sistema de arquivos de pipe nomeado. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for NULL, a solicitação será enviada para o objeto do dispositivo na parte superior da pilha de driver do sistema de arquivos para o volume. Se não for NULL, a solicitação será enviada apenas para instâncias de driver de minifiltro anexadas abaixo da instância especificada.
[out] FileHandle
Um ponteiro para uma variável alocada pelo chamador que recebe o identificador de arquivo se a chamada para FltCreateNamedPipeFile for bem-sucedida.
[out, optional] FileObject
Um ponteiro para uma variável alocada pelo chamador que recebe o ponteiro do objeto de arquivo se a chamada para FltCreateNamedPipeFile for bem-sucedida. Esse parâmetro é opcional e pode ser NULL.
[in] DesiredAccess
Uma máscara de bits de sinalizadores que especifica o tipo de acesso que o chamador requer para o arquivo ou diretório. O conjunto de sinalizadores DesiredAccess definidos pelo sistema determina os direitos de acesso específicos a seguir para objetos de arquivo.
| Sinalizadores DesiredAccess | Significado |
|---|---|
| FILE_READ_DATA | Os dados podem ser lidos do pipe nomeado. |
| FILE_READ_ATTRIBUTES | Os sinalizadores FileAttributes podem ser lidos . Para obter informações adicionais, consulte a tabela de valores de sinalizador válidos no parâmetro FileAttributes de FltCreateFileEx2. |
| READ_CONTROL | A ACL (lista de controle de acesso) e as informações de propriedade associadas ao pipe nomeado podem ser lidas. |
| FILE_WRITE_DATA | Os dados podem ser gravados no pipe nomeado. |
| FILE_WRITE_ATTRIBUTES | Os sinalizadores FileAttributes podem ser gravados . |
| FILE_APPEND_DATA | Os dados podem ser acrescentados ao arquivo. |
| WRITE_DAC | A DACL (lista de controle de acesso discricionário) associada ao pipe nomeado pode ser gravada. |
| WRITE_OWNER | As informações de propriedade associadas ao pipe nomeado podem ser gravadas. |
| ACCESS_SYSTEM_SECURITY | O chamador terá acesso de gravação ao SACL do pipe nomeado |
| SYNCHRONIZE | O chamador pode sincronizar a conclusão de uma operação de E/S aguardando que o FileHandle retornado seja definido como o estado Sinalizado. Esse sinalizador deverá ser definido se o sinalizador CreateOptions FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT estiver definido. |
Como alternativa, para qualquer objeto de arquivo que não represente um diretório, você pode especificar um ou mais dos sinalizadores genéricos de ACCESS_MASK a seguir. (Os sinalizadores STANDARD_RIGHTS_XXX são valores predefinidos do sistema que são usados para impor a segurança em objetos do sistema.) Você também pode combinar esses sinalizadores genéricos com sinalizadores adicionais da tabela anterior.
| DesiredAccess para valores de arquivo | Mapeia para Sinalizadores DesiredAccess |
|---|---|
| GENERIC_READ | STANDARD_RIGHTS_READ, FILE_READ_DATA e SYNCHRONIZE. |
| GENERIC_WRITE | STANDARD_RIGHTS_WRITE, FILE_WRITE_DATA, FILE_APPEND_DATA e SYNCHRONIZE. |
[in] ObjectAttributes
Um ponteiro para uma estrutura de OBJECT_ATTRIBUTES opaca que já está inicializada com InitializeObjectAttributes. Se o chamador estiver em execução no contexto do processo do sistema, esse parâmetro poderá ser NULL. Caso contrário, o chamador deve definir o atributo OBJ_KERNEL_HANDLE na chamada como InitializeObjectAttributes. Os membros dessa estrutura para um objeto de arquivo são listados na tabela a seguir.
| Membro | Valor |
|---|---|
| Comprimentodo ULONG | O número de bytes de dados contidos na estrutura apontada por ObjectAttributes. Esse valor deve ser pelo menos sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | Um ponteiro para uma estrutura UNICODE_STRING que contém o nome do pipe a ser criado ou aberto. Esse nome deve ser uma especificação de arquivo totalmente qualificada ou o nome de um objeto de dispositivo, a menos que seja o nome de um arquivo relativo ao diretório especificado por RootDirectory. Por exemplo, "\Device\NamedPipe\mypipe" ou "\?? \pipe\mypipe" pode ser especificações de arquivo válidas. (Observação: "\??" substitui "\DosDevices" como o nome do namespace do objeto Win32. "\DosDevices" ainda funciona, mas "\??" é traduzido mais rapidamente pelo gerenciador de objetos.) |
| Handle RootDirectory | Um identificador opcional para um diretório, obtido por uma chamada anterior para FltCreateFileEx2. Se esse valor for NULL, o membro ObjectNamedeverá ser uma especificação de arquivo totalmente qualificada que inclua o caminho completo para o pipe de destino. Se esse valor não for NULL, o membro ObjectName especificará um nome de pipe relativo a esse diretório. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | Um descritor de segurança opcional (SECURITY_DESCRIPTOR) a ser aplicado a um pipe. As ACLs especificadas por esse descritor de segurança só são aplicadas ao pipe quando ele é criado. Se o valor for NULL quando um pipe for criado, a ACL colocada no pipe dependerá do sistema de arquivos de pipe nomeado e poderá permitir que um cliente com qualquer acesso crie uma instância. |
| AtributosULONG | Um conjunto de sinalizadores que controla os atributos do objeto de arquivo. Se o chamador estiver em execução no contexto do processo do sistema, esse parâmetro poderá ser zero. Caso contrário, o chamador deve definir o sinalizador OBJ_KERNEL_HANDLE. Opcionalmente, o chamador pode definir o sinalizador OBJ_CASE_INSENSITIVE, que indica que o código de pesquisa de nome deve ignorar o caso de ObjectName em vez de executar uma pesquisa de correspondência exata. |
[out] IoStatusBlock
Um ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação solicitada. No retorno de FltCreateNamedPipeFile, o membro Information da variável contém um dos seguintes valores:
FILE_CREATED
FILE_OPENED
[in] ShareAccess
O tipo de acesso de compartilhamento ao arquivo que o chamador requer como um ou uma combinação dos sinalizadores a seguir. Para obter a maior chance de evitar erros de violação de compartilhamento, especifique todos os sinalizadores de acesso de compartilhamento a seguir.
| Sinalizadores do ShareAccess | Significado |
|---|---|
| FILE_SHARE_READ | O arquivo pode ser aberto para acesso de leitura por chamadas de outros threads para FltCreateNamedPipeFile. |
| FILE_SHARE_WRITE | O arquivo pode ser aberto para acesso de gravação por chamadas de outros threads para FltCreateNamedPipeFile. |
[in] CreateDisposition
Um valor que determina a ação a ser tomada, dependendo se o arquivo já existe. O valor pode ser qualquer um dos descritos na tabela a seguir.
| Valores createDisposition | Significado |
|---|---|
| FILE_CREATE | Se o arquivo já existir, falhe na solicitação e não crie ou abra o arquivo especificado. Se isso não acontecer, crie o arquivo. |
| FILE_OPEN | Se o arquivo já existir, abra-o em vez de criar um novo arquivo. Caso contrário, falhe na solicitação e não crie um novo arquivo. |
| FILE_OPEN_IF | Se o arquivo já existir, abra-o. Caso contrário, crie o arquivo. |
[in] CreateOptions
As opções a serem aplicadas ao criar ou abrir o pipe, como uma combinação compatível dos sinalizadores a seguir.
| Sinalizadores CreateOptions | Significado |
|---|---|
| FILE_WRITE_THROUGH | Os serviços do sistema, os sistemas de pipe e os drivers que gravam dados no pipe devem realmente transferir os dados para o pipe antes que qualquer operação de gravação solicitada seja considerada concluída. Esse sinalizador será definido automaticamente se o sinalizador CreateOptions FILE_NO_INTERMEDIATE_BUFFERING estiver definido. |
| FILE_SYNCHRONOUS_IO_ALERT | Todas as operações no pipe são executadas de forma síncrona. Qualquer espera em nome do chamador está sujeita ao encerramento prematuro de alertas. Esse sinalizador também faz com que o sistema de E/S mantenha o contexto de posição do pipe. Se esse sinalizador for definido, o sinalizador DesiredAccess SYNCHRONIZE também deverá ser definido para que o Gerenciador de E/S use o objeto de arquivo como um objeto de sincronização. |
| FILE_SYNCHRONOUS_IO_NONALERT | Todas as operações no pipe são executadas de forma síncrona. As esperas no sistema para sincronizar a fila de E/S e a conclusão não estão sujeitas a alertas. Esse sinalizador também faz com que o sistema de E/S mantenha o contexto de posição do arquivo. Se esse sinalizador for definido, o sinalizador DesiredAccess SYNCHRONIZE também deverá ser definido para que o Gerenciador de E/S use o objeto de arquivo como um objeto de sincronização. |
[in] NamedPipeType
Tipo de pipe nomeado a ser criado. Pode ser um dos seguintes valores:
[in] ReadMode
O modo a ser lido do pipe.
[in] CompletionMode
O modo de conclusão para leituras e gravações de pipe.
[in] MaximumInstances
O número máximo de instâncias permitidas para esse pipe nomeado.
InboundQuota
O número de bytes a serem reservados para o buffer de entrada.
OutboundQuota
O número de bytes a serem reservados para o buffer de saída.
[in, optional] DefaultTimeout
O tempo limite padrão em incrementos de 100 nanossegundos. Esse valor é expresso como um inteiro negativo. Por exemplo, 250 milissegundos são especificados como –10 * 1000 * 250.
[in, optional] DriverContext
Um ponteiro opcional para uma estrutura IO_DRIVER_CREATE_CONTEXT já inicializada por IoInitializeDriverCreateContext.
Retornar valor
FltCreateNamedPipeFile retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes.
| Código de retorno | Descrição |
|---|---|
|
O filtro ou instância especificado nos parâmetros Filter ou Instance está sendo dividido. Esse código status poderá ser recebido se a solicitação aberta cruzar um ponto de montagem de volume e o parâmetro Instance não for NULL. Este é um código de erro. |
|
O parâmetro ObjectAttributes não continha um membro RootDirectory , mas o membro ObjectName na estrutura OBJECT_ATTRIBUTES era uma cadeia de caracteres vazia ou não continha um caractere OBJECT_NAME_PATH_SEPARATOR. Esse código de erro indica uma sintaxe incorreta para o caminho do objeto. |
Comentários
A função FltCreateNamedPipeFile permite que drivers de minifiltro criem ou abram instâncias de pipe. Isso é útil para criar pipes virtuais ou para criar uniões de pipe para multiplexação de E/S.
O parâmetro de instância é NULL ou é definido anteriormente anexando-se ao volume de pipe nomeado. Um ponteiro de volume é obtido passando "\Device\NamedPipe" como o nome do volume para FltGetVolumeFromName.
Para especificar um parâmetro de criação extra (ECP) como parte de uma operação de criação, inicialize o membro ExtraCreateParameter da estrutura IO_DRIVER_CREATE_CONTEXT com a rotina FltAllocateExtraCreateParameterList . Se os ECPs forem usados, eles deverão ser alocados, inicializados e liberados usando suas rotinas de suporte associadas. Ao retornar da chamada de FltCreateNamedPipeFile, a lista ECP não é alterada e pode ser passada para chamadas adicionais de FltCreateNamedPipeFile para outras operações de criação. A estrutura de lista ECP não é desalocada automaticamente. O chamador de FltCreateNamedPipeFile deve desalocar essa estrutura chamando a rotina FltFreeExtraCreateParameterList .
Se Instance não for NULL, a solicitação de criação de FltCreateNamedPipeFile será enviada somente para as instâncias anexadas abaixo da instância de driver de minifiltro especificada e para o sistema de arquivos de pipe nomeado. A instância especificada e as instâncias anexadas acima dela não recebem a solicitação de criação. Se nenhuma instância for especificada, a solicitação irá para a parte superior da pilha e será recebida por todas as instâncias e pelo sistema de arquivos de pipe nomeado.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível em Windows 8. |
| Plataforma de Destino | Universal |
| Cabeçalho | fltkernel.h (inclua FltKernel.h) |
| Biblioteca | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Confira também
FltAllocateExtraCreateParameterList