createLogFile 函数 (clfsw32.h)

项目
02/23/2024

创建或打开日志。日志可以是专用日志，也可以是多路复用日志，具体取决于日志名称。使用 CloseHandle 函数关闭日志。

语法

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
);

参数

[in] pszLogFileName

日志的名称。

此名称是在使用 CreateLogFile 创建日志时指定的。以下示例标识要使用的格式。

日志：<LogName>[：：<LogStreamName>]

例如：路径“LOG：c：\MyDirectory\MyLog”创建文件“c：\MyDirectory\MyLog.blf”。路径“？？\LOG：\HarddiskVolume1\MyDirectory\MyLog“ 创建文件”\.\HarddiskVolume1\MyDirectory\MyLog.blf“，路径”\clfs\Device\HarddiskVolume1\MyDirectory\MyLog“也创建文件。

<LogName> 对应于文件系统中的有效文件路径， <LogStreamName> 是日志中日志流的唯一名称。有关详细信息，请参阅日志类型。

[in] fDesiredAccess

返回的句柄对日志对象的访问类型。

值	含义
GENERIC_READ	指定对对象的读取访问权限。
GENERIC_WRITE	指定对对象的写入访问权限。
DELETE	指定日志删除访问权限

如果按位 OR 包含两个或多个这些标志，则允许对对象进行读取、写入和删除访问的组合。

注意必须指定 DELETE 访问权限才能删除日志。

Windows Server 2003 R2： 此参数必须设置为 GENERIC_WRITE。

[in] dwShareMode

文件的共享模式。

客户端无法请求的共享模式与任何具有打开句柄的先前打开请求中指定的任何模式冲突。

如果此参数为零，并且函数成功，则对象不能共享，并且不能再次打开，直到句柄关闭。

此参数可使用以下一个或多个值。

值	含义
FILE_SHARE_DELETE	对对象启用打开操作以请求删除访问权限。如果没有此值，则其他进程在请求删除访问权限时无法打开该对象。
FILE_SHARE_READ	对对象启用打开操作以请求读取访问权限。如果没有此值，其他进程将无法打开对象（如果请求读取访问权限）。
FILE_SHARE_WRITE	对对象启用打开操作以请求写入访问权限。如果没有此值，其他进程将无法打开对象（如果请求写入访问权限）。

[in, optional] psaLogFile

指向 SECURITY_ATTRIBUTES 结构的指针，该结构指定日志的安全属性。

它确定返回的句柄是否可以由子进程继承。如果此参数为 NULL，则无法继承句柄。

SECURITY_ATTRIBUTES 的 lpSecurityDescriptor 成员为新的日志句柄指定安全描述符。如果 psaLogFile 为 NULL，则对象获取默认安全描述符。访问控制在日志的默认安全描述符中列出 (ACL) 来自创建者的主令牌或模拟令牌。

[in] fCreateDisposition

要执行的操作。

此参数的取值可为下列值之一：

值	含义
CREATE_NEW	创建一个新文件，如果文件已存在，则失败。
OPEN_EXISTING	打开现有文件，如果文件不存在，则失败。
OPEN_ALWAYS	打开现有文件或创建文件（如果该文件不存在）。

[in] fFlagsAndAttributes

文件的文件属性和标志。

此参数可以采用以下值。

值	含义
FILE_ATTRIBUTE_ARCHIVE	应存档此非临时日志。如果未提供此标志，则不需要存档日志，并且不会维护存档尾部来回收日志容器。
FILE_FLAG_OVERLAPPED	如果设置了 FILE_FLAG_OVERLAPPED 标志，则忽略所有其他标志值。指定 FILE_FLAG_OVERLAPPED 意味着针对重叠 I/O 打开文件，这样就可以在日志句柄上执行多个 I/O 操作。如果在创建日志时设置了此标志，则对该日志的所有异步 I/O 调用都必须指定重叠结构并与调用的延迟完成同步。

返回值

如果函数成功，则返回值是日志的句柄。

如果函数失败，则返回值为 INVALID_HANDLE_VALUE。要获得更多的错误信息，请调用 GetLastError。

以下列表标识了可能的错误代码：

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 R2 [仅限桌面应用]
目标平台	Windows
标头	clfsw32.h
Library	Clfsw32.lib
DLL	Clfsw32.dll