Função FltCreateMailslotFile (fltkernel.h)
Os drivers de minifiltro chamam FltCreateMailslotFile para criar um novo pipe ou abrir um emaillot existente.
Sintaxe
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
);
Parâmetros
[in] Filter
Um ponteiro de filtro opaco para o chamador.
[in, optional] Instance
Um ponteiro de instância opaca 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 emaillot. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for NULL, a solicitação será enviada ao objeto do dispositivo na parte superior da pilha de driver do sistema de arquivos para o volume. Se não forNULL, 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 por chamador que recebe o identificador de arquivo se a chamada para FltCreateMailslotFile for bem-sucedida.
[out, optional] FileObject
Um ponteiro para uma variável alocada por chamador que receberá o ponteiro do objeto de arquivo se a chamada para FltCreateMailslotFile 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 de DesiredAccess definidos pelo sistema determina os direitos de acesso específicos a seguir para objetos de arquivo.
| Sinalizador DesiredAccess | Significado |
|---|---|
| FILE_READ_DATA | Os dados podem ser lidos do emaillot nomeado. |
| FILE_READ_ATTRIBUTES | 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 lista de controle de acesso acl e informações de propriedade associadas ao emaillot podem ser lidas. |
| FILE_WRITE_DATA | Os dados podem ser gravados no emaillot. |
| FILE_WRITE_ATTRIBUTES | sinalizadores FileAttributes podem ser gravados. |
| FILE_APPEND_DATA | Os dados podem ser acrescentados ao emaillot. |
| WRITE_DAC | A lista de controle de acesso discricionário DACL associada ao emaillot pode ser gravada. |
| WRITE_OWNER | Informações de propriedade associadas ao emaillot podem ser gravadas. |
| ACCESS_SYSTEM_SECURITY | O chamador terá acesso de gravação ao SACL do emaillot. |
| SINCRONIZAR | O chamador pode sincronizar a conclusão de uma operação de E/S aguardando o FileHandle retornado para ser 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 seguintes sinalizadores genéricos de ACCESS_MASK. (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 to File Values | Mapas 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
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 para InitializeObjectAttributes. Os membros dessa estrutura para um objeto de arquivo são listados na tabela a seguir.
| Membro | Valor |
|---|---|
| de comprimento ULONG | Número de bytes de dados contidos na estrutura apontada por ObjectAttributes. Esse valor deve ser pelo menos sizeof(OBJECT_ATTRIBUTES). |
| objectName PUNICODE_STRING | Ponteiro para uma estrutura UNICODE_STRING que contém o nome do emaillot 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\Mailslot\myslot" ou "?? \mailslot\myslot" 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 | Identificador opcional para um diretório, obtido por uma chamada anterior para FltCreateFileEx2. Se esse valor for NULL, o membro ObjectName deverá ser uma especificação de arquivo totalmente qualificada que inclua o caminho completo para o emaillot de destino. Se esse valor não forNULL, o membro ObjectName especifica um nome de emaillot relativo a esse diretório. |
| securityDescriptor PSECURITY_DESCRIPTOR | SECURITY_DESCRIPTOR opcionais a serem aplicadas a um emaillot. ACLs especificadas por esse descritor de segurança só são aplicadas ao emaillot quando ele é criado. Se o valor for NULL quando um emaillot for criado, a ACL colocada no emaillot dependerá do sistema de arquivos do maillot e poderá permitir que um cliente com qualquer acesso crie uma instância. |
| de atributos ULONG | 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 deverá definir o sinalizador de OBJ_KERNEL_HANDLE. O chamador também pode definir opcionalmente 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
Ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação solicitada. Ao retornar de FltCreateMailslotFile, o membro informações da variável contém um dos seguintes valores:
- FILE_CREATED
- FILE_OPENED
[in] CreateOptions
As opções a serem aplicadas ao criar ou abrir o emaillot, como uma combinação compatível dos sinalizadores a seguir.
| Sinalizadores | Significado |
|---|---|
| FILE_WRITE_THROUGH | Os serviços do sistema, os sistemas de arquivos e os drivers que gravam dados no emaillot devem realmente transferir os dados para o emaillot 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 emaillot são executadas de forma síncrona. Qualquer espera em nome do chamador está sujeita a encerramento prematuro de alertas. Esse sinalizador também faz com que o sistema de E/S mantenha o contexto de posição do emaillot. Se esse sinalizador estiver 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 emaillot 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 estiver 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] MailslotQuota
O tamanho, em bytes, do buffer para gravações no emaillot.
[in] MaximumMessageSize
O tamanho máximo, em bytes, de uma mensagem a ser gravada no emaillot. Uma mensagem de qualquer tamanho é especificada pelo valor 0.
[in] ReadTimeout
O tempo em que uma operação de leitura aguarda uma mensagem estar disponível no emaillot. O tempo limite padrão é expresso em incrementos de 100 nanossegundos como um inteiro negativo. Por exemplo, 250 milissegundos são especificados como –10*1000*250. Além disso, os valores a seguir têm significados especiais.
| Valor | Significado |
|---|---|
| 0 | Retorna imediatamente se nenhuma mensagem estiver presente. |
| -1 | Espera para sempre por uma mensagem. |
[in, optional] DriverContext
Ponteiro opcional para uma estrutura de IO_DRIVER_CREATE_CONTEXT já inicializada por IoInitializeDriverCreateContext .
Valor de retorno
FltCreateMailslotFile retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes.
| Código de retorno | Descrição |
|---|---|
| STATUS_FLT_DELETING_OBJECT | O filtro ou a instância especificado nos parâmetros de Filtro ou Instância está sendo derrubado. Esse código de status poderá ser recebido se a solicitação aberta cruzar um ponto de montagem de volume e o parâmetro da Instância não forNULL. Este é um código de erro. |
| STATUS_OBJECT_PATH_SYNTAX_BAD | 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 a sintaxe incorreta para o caminho do objeto. |
Observações
A função FltCreateMailslotFile permite que drivers de minifiltro criem ou abram instâncias de emaillot. Isso é útil para criar emailslots virtuais ou para criar um grupo de emailslot que distribui para vários outros emailslots.
O parâmetro da Instância de é NULL ou é definido anteriormente anexando ao volume de emaillot. Um ponteiro de volume é obtido passando "\Device\Mailslot" 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 rotinaFltAllocateExtraCreateParameterList. Se os ECPs forem usados, eles deverão ser alocados, inicializados e liberados usando suas rotinas de suporte associadas. Ao retornar da chamada de FltCreateMailslotFile, a lista ECP não será alterada e poderá ser passada para chamadas adicionais de FltCreateMailslotFile para outras operações de criação. A estrutura de lista ECP não é desalocada automaticamente. O chamador de FltCreateMailslotFile deve desalocar essa estrutura chamando a rotinaFltFreeExtraCreateParameterList.
Se Instância não for NULL, a solicitação de criação do FltCreateMailslotFile será enviada apenas para as instâncias anexadas abaixo da instância do driver de minifiltro especificada e para o sistema de arquivos de emaillot. A instância especificada e as instâncias anexadas acima 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 maillot.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível no Windows 8. |
| da Plataforma de Destino | Universal |
| cabeçalho | fltkernel.h (inclua FltKernel.h) |
| biblioteca | Fltmgr.lib |
| IRQL | PASSIVE_LEVEL |
Consulte também
FltAllocateExtraCreateParameterList