Função ClfsCreateLogFile (wdm.h)
A rotina de ClfsCreateLogFile cria ou abre um fluxo CLFS. Se necessário, ClfsCreateLogFile também criará o log físico subjacente que contém os registros do fluxo.
Sintaxe
CLFSUSER_API NTSTATUS ClfsCreateLogFile(
[out] PPLOG_FILE_OBJECT pplfoLog,
[in] PUNICODE_STRING puszLogFileName,
[in] ACCESS_MASK fDesiredAccess,
[in] ULONG dwShareMode,
[in, optional] PSECURITY_DESCRIPTOR psdLogFile,
[in] ULONG fCreateDisposition,
[in] ULONG fCreateOptions,
[in] ULONG fFlagsAndAttributes,
[in] ULONG fLogOptionFlag,
[in, optional] PVOID pvContext,
[in] ULONG cbContext
);
Parâmetros
[out] pplfoLog
Um ponteiro para uma variável que recebe um ponteiro para uma estrutura LOG_FILE_OBJECT que representa uma instância aberta do fluxo.
[in] puszLogFileName
Um ponteiro para uma estrutura de UNICODE_STRING que fornece o nome do fluxo ou do log físico subjacente.
Se o fluxo já existir e for o único fluxo de um log dedicado, o nome terá o log de formulários:nome de log físico, em que nome de log físico é o nome do caminho, no sistema de arquivos subjacente, do log físico existente que contém os registros do fluxo.
Se o fluxo ainda não existir e se tornar o único fluxo de um log dedicado (que ainda não existe), o nome terá o log de formulários:nome de log físico, em que nome de log físico é o nome do caminho, no sistema de arquivos subjacente, do log físico que será criado para manter os registros do fluxo.
Se o fluxo for (ou se tornar) um dos fluxos de um log multiplexado, o nome tem o log de formulários:nome de log físico::nome do fluxo, em que nome de log físico é o nome do caminho, no sistema de arquivos subjacente, do log físico que contém os registros do fluxo e nome do fluxo é o nome de um fluxo que compartilha (ou compartilhará) esse log físico.
Se você quiser criar um log multiplexado que não tenha fluxos no momento, use um nome do log de formulários:nome de log físico::, em que nome de log físico é o nome do caminho, no sistema de arquivos subjacente, do log físico a ser criado.
A lista a seguir fornece alguns exemplos de nomes válidos.
- "Log:c:\myLog" cria ou abre um log dedicado e seu único fluxo.
- "Log:c:\myCommonLog::" cria um log multiplexado que ainda não tem fluxos.
- "Log:c:\myCommonLog::Stream1" cria ou abre um dos fluxos (Stream1) de um log multiplexado.
[in] fDesiredAccess
Um ACCESS_MASK que fornece o tipo de acesso que o cliente terá (usando o ponteiro retornado em pplfoLog) para o fluxo. Se esse parâmetro for zero, os clientes poderão consultar o fluxo para seus atributos, mas não poderão ler ou gravar no fluxo. Esse parâmetro pode ser zero ou qualquer combinação dos seguintes sinalizadores:
| Bandeira | Significado |
|---|---|
| GENERIC_READ | O cliente tem acesso de leitura ao fluxo. |
| GENERIC_WRITE | O cliente tem acesso de gravação ao fluxo. |
| EXCLUIR | O cliente pode marcar o fluxo para exclusão. |
[in] dwShareMode
O modo de compartilhamento do fluxo, que pode ser zero (não compartilhado) ou qualquer combinação dos seguintes sinalizadores:
| Bandeira | Significado |
|---|---|
| FILE_SHARE_DELETE | As solicitações subsequentes para abrir o fluxo com acesso de exclusão serão bem-sucedidas. |
| FILE_SHARE_READ | As solicitações subsequentes para abrir o fluxo com acesso de leitura serão bem-sucedidas. |
| FILE_SHARE_WRITE | As solicitações subsequentes para abrir o fluxo com acesso de gravação serão bem-sucedidas. |
[in, optional] psdLogFile
Um ponteiro para uma estrutura SECURITY_DESCRIPTOR que fornece atributos de segurança para o fluxo. Esse parâmetro pode ser NULL.
[in] fCreateDisposition
A ação a ser tomada depende se o fluxo já existe. Esse parâmetro deve ser definido como um dos seguintes valores:
| Valor | Significado |
|---|---|
| CREATE_NEW | Crie um novo fluxo se o fluxo ainda não for encerrado. Falhará se o fluxo já existir. |
| OPEN_EXISTING | Abra um fluxo existente. Falhará se o fluxo ainda não existir. |
| OPEN_ALWAYS | Abra um fluxo existente. Crie o fluxo se ele ainda não existir. |
[in] fCreateOptions
Um conjunto de sinalizadores que especificam opções a serem aplicadas ao criar ou abrir o fluxo. Esse parâmetro pode ser zero ou uma combinação compatível com os seguintes sinalizadores:
| Bandeira | Significado |
|---|---|
| FILE_NO_INTERMEDIATE_BUFFERING | Os registros do fluxo não podem ser armazenados em cache nos buffers internos de um driver. |
| FILE_SYNCHRONOUS_IO_ALERT | Todas as operações no fluxo são executadas de forma síncrona. Qualquer espera em nome do chamador está sujeita a encerramento prematuro de alertas. Se esse sinalizador estiver definido, o sinalizador FILE_SYNCHRONOUS_IO_NONALERT deverá ser limpo. |
| FILE_SYNCHRONOUS_IO_NONALERT | Todas as operações no fluxo são executadas de forma síncrona. As esperas no sistema que sincronizam a enfileiramento e a conclusão de E/S não estão sujeitas a alertas. Se esse sinalizador estiver definido, o sinalizador FILE_SYNCHRONOUS_IO_ALERT deverá ser limpo. |
[in] fFlagsAndAttributes
Um valor que especifica se o fluxo é aberto para acesso normal ou somente leitura. Esse parâmetro deve ser definido como
FILE_ATTRIBUTE_NORMAL ou FILE_ATTRIBUTE_READONLY.
[in] fLogOptionFlag
Uma dica sobre a relação entre o CLFS e o componente que cria ou abre o fluxo. Esse parâmetro deve ser definido como um dos seguintes valores:
| Valor | Significado |
|---|---|
| CLFS_FLAG_NO_FLAGS | O CLFS e o componente de criação têm a relação padrão e normal. Os componentes do modo kernel usam esse valor, a menos que se enquadram em uma das três outras categorias listadas nesta tabela. Se pvContext não for NULL, o CLFS verificará que cbContext é maior que zero. Caso contrário, pvContext e cbContext são ignorados. |
| CLFS_FLAG_REENTRANT_FILE_SYSTEM | O componente de criação é o sistema de arquivos que fornece o armazenamento subjacente para CLFS. O CLFS usa o sistema de arquivos para alocar contêineres e o sistema de arquivos usa fluxos CLFS. Nesse caso, é possível que o sistema de arquivos chame CLFS e CLFS para fazer chamadas de volta para o sistema de arquivos no mesmo thread ou threads diferentes. Se pvContext não for NULL, o CLFS verificará que cbContext é maior que zero. Caso contrário, pvContext e cbContext são ignorados. |
| CLFS_FLAG_NON_REENTRANT_FILTER | O componente de criação é um driver de filtro do sistema de arquivos que envia toda a E/S do CLFS para um nível especificado abaixo de si na pilha de filtros. Essa opção permite que um driver de filtro crie um log CLFS sem ver sua própria E/S de log. O chamador passa o objeto de dispositivo de destinoNULL não no parâmetro pvContext com cbContext definido como o tamanho apropriado. O CLFS usa a rotina de IoCreateFileSpecifyDeviceObjectHint para criar contêineres em um nível de destino na pilha de filtros de E/S especificada pelo objeto do dispositivo. |
| CLFS_FLAG_REENTRANT_FILTER | O componente de criação é um driver de filtro do sistema de arquivos que envia toda a E/S do CLFS para a parte superior da pilha de filtros. O filtro tem uma relação recursiva com CLFS porque filtra sua própria E/S de log quando o CLFS executa qualquer operação do sistema de arquivos em seus contêineres. O parâmetro pvContext fornece um meio para os filtros associarem um contexto reconhecível a seus contêineres CLFS à medida que a E/S de log desce a pilha de filtros. O parâmetro cbContext especifica o tamanho do contexto opaco em bytes. |
| CLFS_FLAG_MINIFILTER_LEVEL | O componente de criação é um driver de minifiltro do sistema de arquivos que envia toda a E/S do CLFS para um nível especificado abaixo de si mesmo na pilha de filtros. Essa opção permite que um minifiltro crie um log CLFS sem ver sua própria E/S de log. O chamador passa o objeto de contexto de minifiltro NULLnão no parâmetro pvContext com cbContext definido como o tamanho apropriado. O CLFS usa a rotina IoCreateFileSpecifyDeviceObjectHint para criar contêineres em uma altitude (especificada dentro do contexto de minifiltro) na pilha de minifiltros do gerenciador de filtros. |
[in, optional] pvContext
Um ponteiro para um contexto. A maneira como o contexto é interpretado depende do valor passado para fLogOptionsFlag.
[in] cbContext
O tamanho, em bytes, do contexto apontado por pvContext. Se pvContext não for NULL, esse parâmetro deverá ser maior que zero.
Valor de retorno
ClfsCreateLogFile retornará STATUS_SUCCESS se tiver êxito; caso contrário, ele retorna um dos códigos de erro definidos em Ntstatus.h.
Observações
Quando você cria um fluxo CLFS, ele é apoiado por um log CLFS físico subjacente. O log subjacente pode ser dedicado (faz backup de apenas um fluxo) ou multiplexado (faz backup de vários fluxos). Um log dedicado não pode ser convertido em um log multiplexado e um log multiplexado não pode ser convertido em um log dedicado.
Um nome de log CLFS físico não inclui a extensão .blf.
Para obter uma explicação dos conceitos e terminologia do CLFS, consulte Common Log File System.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível no Windows Server 2003 R2, Windows Vista e versões posteriores do Windows. |
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | wdm.h (inclua Wdm.h) |
| biblioteca | Clfs.lib |
| de DLL | Clfs.sys |
| IRQL | <= APC_LEVEL |