Função CreateLogFile (clfsw32.h)

Artigo
11/20/2024

Cria ou abre um log. O log pode ser dedicado ou multiplexado e isso depende do nome do log. Use a função CloseHandle para fechar o log.

Sintaxe

CLFSUSER_API HANDLE CreateLogFile(
  [in]           LPCWSTR               pszLogFileName,
  [in]           ACCESS_MASK           fDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES psaLogFile,
  [in]           ULONG                 fCreateDisposition,
  [in]           ULONG                 fFlagsAndAttributes
);

Parâmetros

[in] pszLogFileName

O nome do log.

Esse nome é especificado ao criar o log usando CreateLogFile. O exemplo a seguir identifica o formato a ser usado.

log :<logName>[::<LogStreamName>]

Por exemplo: o caminho "LOG:c:\MyDirectory\MyLog" cria o arquivo "c:\MyDirectory\MyLog.blf". O caminho "?? \LOG:\HarddiskVolume1\MyDirectory\MyLog" cria o arquivo "\.\HarddiskVolume1\MyDirectory\MyLog.blf", assim como o caminho "\clfs\Device\HarddiskVolume1\MyDirectory\MyLog".

< LogName> corresponde a um caminho de arquivo válido no sistema de arquivos e <> LogStreamName é o nome exclusivo de um fluxo de log no log. Para obter mais informações, consulte tipos de log.

[in] fDesiredAccess

O tipo de acesso que o identificador retornado tem ao objeto de log.

Valor	Significado
GENERIC_READ	Especifica o acesso de leitura ao objeto.
GENERIC_WRITE	Especifica o acesso de gravação ao objeto.
EXCLUIR	Especificar acesso à exclusão de log

Um OR bit a bit ou de dois ou mais desses sinalizadores permite combinações de acesso de leitura, gravação e exclusão ao objeto.

Observação Você deve especificar acesso DELETE para poder excluir o log.

Windows Server 2003 R2: Esse parâmetro deve ser definido como GENERIC_WRITE.

[in] dwShareMode

O modo de compartilhamento de um arquivo.

Um cliente não pode solicitar um modo de compartilhamento que esteja em conflito com qualquer modo especificado em qualquer solicitação aberta anterior que tenha um identificador aberto.

Se esse parâmetro for zero e a função for bem-sucedida, o objeto não poderá ser compartilhado e não poderá ser aberto novamente até que o identificador seja fechado.

Esse parâmetro pode ser um ou mais dos valores a seguir.

Valor	Significado
FILE_SHARE_DELETE	Permite que operações abertas no objeto solicitem acesso de exclusão. Sem esse valor, outros processos não poderão abrir o objeto se o acesso de exclusão for solicitado.
FILE_SHARE_READ	Habilita operações abertas no objeto para solicitar acesso de leitura. Sem esse valor, outros processos não poderão abrir o objeto se o acesso de leitura for solicitado.
FILE_SHARE_WRITE	Habilita operações abertas no objeto para solicitar acesso de gravação. Sem esse valor, outros processos não poderão abrir o objeto se o acesso de gravação for solicitado.

[in, optional] psaLogFile

Um ponteiro para uma estrutura de SECURITY_ATTRIBUTES que especifica os atributos de segurança de um log.

Ele determina se o identificador retornado pode ser herdado por processos filho. Se esse parâmetro for NULL, o identificador não poderá ser herdado.

O lpSecurityDescriptor membro do SECURITY_ATTRIBUTES especifica um de descritor de segurança para o novo identificador de log. Se psaLogFile for NULL, o objeto obterá um descritor de segurança padrão. As ACL (listas de controle de acesso) no descritor de segurança padrão para um log vêm do token primário ou de representação do criador.

[in] fCreateDisposition

Uma ação a ser tomada.

Esse parâmetro pode ser um dos valores a seguir.

Valor	Significado
CREATE_NEW	Cria um novo arquivo e falha se o arquivo já existir.
OPEN_EXISTING	Abre um arquivo existente e falha se o arquivo não existir.
OPEN_ALWAYS	Abre um arquivo existente ou cria o arquivo se ele não existir.

[in] fFlagsAndAttributes

Os atributos de arquivo e os sinalizadores do arquivo.

Esse parâmetro pode levar os seguintes valores.

Valor	Significado
FILE_ATTRIBUTE_ARCHIVE	Esse log não efêmero deve ser arquivado. Se esse sinalizador não for fornecido, o log não precisará ser arquivado e uma cauda de arquivamento não será mantida para contêineres de log de reciclagem.
FILE_FLAG_OVERLAPPED	Se o sinalizador FILE_FLAG_OVERLAPPED estiver definido, todos os outros valores de sinalizador serão ignorados. Especificar FILE_FLAG_OVERLAPPED significa que um arquivo é aberto para E/S sobreposta, o que permite que mais de uma operação de E/S seja executada no identificador de log. Se esse sinalizador for definido ao criar um log, todas as chamadas de E/S assíncronas para esse log deverão especificar uma estrutura sobreposta e sincronizar com a conclusão adiada da chamada.

Valor

Significado

FILE_ATTRIBUTE_ARCHIVE

Esse log não efêmero deve ser arquivado.

Se esse sinalizador não for fornecido, o log não precisará ser arquivado e uma cauda de arquivamento não será mantida para contêineres de log de reciclagem.

FILE_FLAG_OVERLAPPED

Se o sinalizador FILE_FLAG_OVERLAPPED estiver definido, todos os outros valores de sinalizador serão ignorados.

Especificar FILE_FLAG_OVERLAPPED significa que um arquivo é aberto para E/S sobreposta, o que permite que mais de uma operação de E/S seja executada no identificador de log. Se esse sinalizador for definido ao criar um log, todas as chamadas de E/S assíncronas para esse log deverão especificar uma estrutura sobreposta e sincronizar com a conclusão adiada da chamada.

Valor de retorno

Se a função for bem-sucedida, o valor retornado será um identificador para o log.

Se a função falhar, o valor retornado será INVALID_HANDLE_VALUE. Para obter informações de erro estendidas, chame GetLastError.

A lista a seguir identifica os possíveis códigos de erro:

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2003 R2 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	clfsw32.h
biblioteca	Clfsw32.lib
de DLL	Clfsw32.dll