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 opaco para a instância de 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 do maillot. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for NULL, a solicitação será enviada para o objeto de 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 somente 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 receberá o identificador de arquivo se a chamada para FltCreateMailslotFile for bem-sucedida.
[out, optional] FileObject
Um ponteiro para uma variável alocada pelo 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 especificam 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.
| Sinalizador DesiredAccess | Significado |
|---|---|
| FILE_READ_DATA | Os dados podem ser lidos no emaillot 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 da lista de controle de acesso e as informações de propriedade associadas ao emaillot podem ser lidas. |
| FILE_WRITE_DATA | Os dados podem ser gravados no emaillot. |
| FILE_WRITE_ATTRIBUTES | Os 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 maillot pode ser gravada. |
| WRITE_OWNER | As informações de propriedade associadas ao maillot podem ser gravadas. |
| ACCESS_SYSTEM_SECURITY | O chamador terá acesso de gravação à SACL do maillot. |
| 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 de sistema predefinidos 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
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 deverá 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 |
|---|---|
| Comprimento do ULONG | Número de bytes de dados contidos na estrutura apontada por ObjectAttributes. Esse valor deve ser pelo menos sizeof(OBJECT_ATTRIBUTES). |
| PUNICODE_STRING ObjectName | 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 em relação 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 for NULL, o membro ObjectName especificará um nome de emaillot relativo a esse diretório. |
| PSECURITY_DESCRIPTOR SecurityDescriptor | SECURITY_DESCRIPTOR opcionais a serem aplicadas a um emaillot. As 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. |
| Atributos ULONG | Um conjunto de sinalizadores que controla os atributos de 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 OBJ_KERNEL_HANDLE. Opcionalmente, o chamador também 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
Ponteiro para uma estrutura IO_STATUS_BLOCK que recebe a status de conclusão final e informações sobre a operação solicitada. No retorno de FltCreateMailslotFile, o membro Information 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.
| Flags | 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 ao encerramento prematuro de alertas. Esse sinalizador também faz com que o sistema de E/S mantenha o contexto de posição do maillot. 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 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 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] 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 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 IO_DRIVER_CREATE_CONTEXT já inicializada por IoInitializeDriverCreateContext.
Retornar valor
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 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. |
| 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 uma sintaxe incorreta para o caminho do objeto. |
Comentários
A função FltCreateMailslotFile permite que drivers de minifiltro criem ou abram instâncias do maillot. Isso é útil para criar emailslots virtuais ou para criar um grupo de emailslot que distribui para vários outros emailslots.
O parâmetro Instance é NULL ou é definido anteriormente anexando-se ao volume do maillot. 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 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 FltCreateMailslotFile, a lista ECP não é alterada e pode 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 rotina FltFreeExtraCreateParameterList .
Se Instance não for NULL, a solicitação de criação de FltCreateMailslotFile será enviada somente para as instâncias anexadas abaixo da instância de driver de minifiltro especificada e para o sistema de arquivos maillot. 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 maillot.
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