Função ClfsCreateLogFile (wdm.h)
A rotina ClfsCreateLogFile cria ou abre um fluxo CLFS. Se necessário, ClfsCreateLogFile também cria 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 UNICODE_STRING que fornece o nome do fluxo ou o log físico subjacente.
Se o fluxo já existir e for o único fluxo de um log dedicado, o nome terá o nome log:physical log do formulário, em que o nome do 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 nome log:physical log do formulário, em que o nome do 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 terá o nome log:physical log::stream, em que o nome do log físico é o nome do caminho, no sistema de arquivos subjacente, do log físico que contém os registros do fluxo e o 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 por enquanto, use um nome do formulário log:physical log name::, em que nome do 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 em busca de 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:
| Sinalizador | Significado |
|---|---|
| GENERIC_READ | O cliente tem acesso de leitura ao fluxo. |
| GENERIC_WRITE | O cliente tem acesso de gravação ao fluxo. |
| DELETE | 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:
| Sinalizador | 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. Este 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. Falha 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 dos seguintes sinalizadores:
| Sinalizador | 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 ao 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 fila de E/S e a conclusão 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á se cbContext é maior que zero. Caso contrário, pvContext e cbContext serã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á se cbContext é maior que zero. Caso contrário, pvContext e cbContext serã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 mesmo 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 destino não NULL no parâmetro pvContext com cbContext definido para o tamanho apropriado. O CLFS usa a rotina 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 o 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 desativa 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 registro em log. O chamador passa o objeto de contexto de minifiltro não NULL 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.
Retornar valor
ClfsCreateLogFile retornará STATUS_SUCCESS se for bem-sucedido; caso contrário, retornará um dos códigos de erro definidos em Ntstatus.h.
Comentários
Quando você cria um fluxo CLFS, ele é apoiado por um log CLFS físico subjacente. O log subjacente pode ser dedicado (só faz backup de 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 |
|---|---|
| Cliente mínimo com suporte | Disponível no Windows Server 2003 R2, Windows Vista e versões posteriores do Windows. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | wdm.h (inclua Wdm.h) |
| Biblioteca | Clfs.lib |
| DLL | Clfs.sys |
| IRQL | <= APC_LEVEL |