Função ClfsCreateLogFile (wdm.h)

  • Artigo

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

Confira também

ClfsCloseAndResetLogFile

ClfsCloseLogFileObject

ClfsDeleteLogByPointer

ClfsDeleteLogFile