| 术语 | controltrace |
| 释义 | ControlTrace 语法： C++ ULONG ControlTrace( __in TRACEHANDLE SessionHandle, __in LPCTSTR SessionName, __inout PEVENT_TRACE_PROPERTIES Properties, __in ULONG ControlCode ); ControlTrace功能 冲的ControlTrace功能，查询，更新或停止指定的事件跟踪会话。 参数 SessionHandle [in] 处理的事件跟踪会话，或NULL。您必须指定SessionHandle如果SessionName为NULL。然而，ETW忽略处理，如果SessionName不为NULL。句柄是由StartTrace函数返回。 SessionName [in] 名称的跟踪会话，或NULL事件。您必须指定SessionName如果SessionHandle为NULL。 要指定NT内核记录器会议后，设立SessionName为KERNEL_LOGGER_NAME。 属性[ in , out ] 指针初始化EVENT_TRACE_PROPERTIES结构。 如果ControlCode指定EVENT_TRACE_CONTROL_STOP，EVENT_TRACE_CONTROL_QUERY或EVENT_TRACE_CONTROL_FLUSH，您只需要设置Wnode.BufferSize，Wnode.Guid，LoggerNameOffset，以及EVENT_TRACE_PROPERTIES结构LogFileNameOffset成员。如果这次会议是一次非公开会议，您还需要设置LogFileMode。您可以使用的最大会话名称(1024字)和最大日志文件的名称(1024个字符)的长度来计算的缓冲区大小，如果不知道偏移。 如果ControlCode指定EVENT_TRACE_CONTROL_UPDATE的投入，各成员必须指定的属性，更新新的价值观。对产出，属性包含用于跟踪会话事件属性和统计。您可以更新下列属性。 MemberUse EnableFlagsSet为0禁用所有成员提供的内核。否则，您必须指定核心供应商，您要启用或保持启用。仅适用于NT内核记录器会话。 FlushTimerSet该成员如果您想改变的时间才刷新缓冲区。如果这个成员为0，成员不更新。 LogFileNameOffsetSet该会员如果您想切换到另一个日志文件。如果这个成员是0，文件名没有更新。如果偏移量不为零，您不要更改日志文件的名称，该函数返回一个错误。 LogFileModeSet该成员如果要打开和关闭EVENT_TRACE_REAL_TIME_MODE。要打开实时耗时关闭，设置为0的成员。要打开实时上耗费时间，设置此成员EVENT_TRACE_REAL_TIME_MODE，它将与目前的模式OR'd。 MaximumBuffersSet这个会员，如果您想改变缓冲区的最大数量ETW使用。如果这个成员为0，成员不更新。 至于私人记录会话，您可以只更新LogFileNameOffset和FlushTimer成员。 如果您使用的是新初始化EVENT_TRACE_PROPERTIES结构，您需要指定，比您要更新的成员外，只有成员，是Wnode.BufferSize，Wnode.Guid和Wnode.Flags。 如果您使用您的财产结构传递给StartTrace，确保LogFileNameOffset成员为0，除非您改变日志文件的名称。 假如ControlTrace您调用函数来查询当前会话属性，然后更新这些属性以更新会议，请确保您设置LogFileNameOffset为0(除非您正在改变日志文件的名称)，并设置EVENT_TRACE_PROPERTIES.Wnode.Flags在WNODE_FLAG_TRACED_GUID。 ControlCode [in] 要求控制功能。您可以指定下列值之一。 ValueMeaning EVENT_TRACE_CONTROL_FLUSHFlushes会议的积极缓冲区。通常，您不需要自己刷新缓冲区。但是，您可能需要刷新缓冲区，如果事件发生率低，您提供实时的事件。 Windows 2000中：此值不支持。 EVENT_TRACE_CONTROL_QUERYRetrieves会话属性和统计。 EVENT_TRACE_CONTROL_STOPStops了会议。这次会议句柄不再有效。 EVENT_TRACE_CONTROL_UPDATEUpdates会话属性。 请注意，是不可靠的刷新缓冲区或停止跟踪从DllMain会议。 返回值 如果函数成功，返回值是ERROR_SUCCESS。 如果函数失败，返回值是系统错误代码之一。下表列出了一些常见的错误及其原因。 返回codeDescription 以下ERROR_BAD_LENGTHOne是正确的： 物业的Wnode.BufferSize成员指定一个不正确的大小。 属性没有足够的空间分配举行会议的名称和日志文件的名称副本(如果使用)。 以下ERROR_INVALID_PARAMETEROne是正确的： 属性为NULL。 SessionName和SessionHandle都是空。 物业的LogFileNameOffset成员是无效的。 物业的LoggerNameOffset成员是无效的。 物业的LogFileMode成员指定的标志的组合无效。 物业的Wnode.Guid成员SystemTraceControlGuid，但SessionName参数不KERNEL_LOGGER_NAME。 ERROR_BAD_PATHNAMEAnother会议已经使用的文件名由属性结构LogFileNameOffset成员中指定。 ERROR_MORE_DATAThe的EVENT_TRACE_PROPERTIES缓冲区太小，无法容纳所有的会话信息。如果您不需要会话的属性信息，您可以忽略此错误。如果您收到此错误时停止会议，ETW将已经停止在产生这个错误了会议。 ERROR_ACCESS_DENIEDOnly具有管理权限的用户，在性能日志用户组的用户，服务本地系统，本地服务运行，是NetworkService可以控制事件跟踪会话。要授予受限用户能够控制跟踪会话，将它们添加到性能日志用户组。具有管理权限和服务作为LocalSystem可以控制的NT内核记录器会话中运行的用户。 Windows XP和Windows 2000：任何人都可以控制跟踪会话。 ERROR_WMI_INSTANCE_NOT_FOUNDThe某次会议没有运行。 备注 事件跟踪控制器调用这个函数。 这个函数取代FlushTrace，QueryTrace，StopTrace和UpdateTrace功能。 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderEvntrace.h LibraryAdvapi32.lib DLLAdvapi32.dll Unicode和ANSI namesControlTraceW(Unicode)和ControlTraceA(ANSI)的 参见 EVENT_TRACE_PROPERTIES QueryAllTraces StartTrace 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年7月30日 ＝＝英文原文＝＝ControlTrace Function The ControlTrace function flushes, queries, updates, or stops the specified event tracing session. Syntax C++ ULONG ControlTrace( __in TRACEHANDLE SessionHandle, __in LPCTSTR SessionName, __inout PEVENT_TRACE_PROPERTIES Properties, __in ULONG ControlCode ); Parameters SessionHandle [in] Handle to an event tracing session, or NULL. You must specify SessionHandle if SessionName is NULL. However, ETW ignores the handle if SessionName is not NULL. The handle is returned by the StartTrace function. SessionName [in] Name of an event tracing session, or NULL. You must specify SessionName if SessionHandle is NULL. To specify the NT Kernel Logger session, set SessionName to KERNEL_LOGGER_NAME. Properties [in, out] Pointer to an initialized EVENT_TRACE_PROPERTIES structure. If ControlCode specifies EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY or EVENT_TRACE_CONTROL_FLUSH, you only need to set the Wnode.BufferSize, Wnode.Guid, LoggerNameOffset, and LogFileNameOffset members of the EVENT_TRACE_PROPERTIES structure. If the session is a private session, you also need to set LogFileMode. You can use the maximum session name (1024 characters) and maximum log file name (1024 characters) lengths to calculate the buffer size and offsets if not known. If ControlCode specifies EVENT_TRACE_CONTROL_UPDATE, on input, the members must specify the new values for the properties to update. On output, Properties contains the properties and statistics for the event tracing session. You can update the following properties. MemberUse EnableFlagsSet this member to 0 to disable all kernel providers. Otherwise, you must specify the kernel providers that you want to enable or keep enabled. Applies only to NT Kernel Logger sessions. FlushTimerSet this member if you want to change the time to wait before flushing buffers. If this member is 0, the member is not updated. LogFileNameOffsetSet this member if you want to switch to another log file. If this member is 0, the file name is not updated. If the offset is not zero and you do not change the log file name, the function returns an error. LogFileModeSet this member if you want to turn EVENT_TRACE_REAL_TIME_MODE on and off. To turn real time consuming off, set this member to 0. To turn real time consuming on, set this member to EVENT_TRACE_REAL_TIME_MODE and it will be OR'd with the current modes. MaximumBuffersSet this member if you want to change the maximum number of buffers that ETW uses. If this member is 0, the member is not updated. For private logger sessions, you can update only the LogFileNameOffset and FlushTimer members. If you are using a newly initialized EVENT_TRACE_PROPERTIES structure, the only members you need to specify, other than the members you are updating, are Wnode.BufferSize, Wnode.Guid, and Wnode.Flags. If you use the property structure you passed to StartTrace, make sure the LogFileNameOffset member is 0 unless you are changing the log file name. If you call the ControlTrace function to query the current session properties and then update those properties to update the session, make sure you set LogFileNameOffset to 0 (unless you are changing the log file name) and set EVENT_TRACE_PROPERTIES.Wnode.Flags to WNODE_FLAG_TRACED_GUID. ControlCode [in] Requested control function. You can specify one of the following values. ValueMeaning EVENT_TRACE_CONTROL_FLUSHFlushes the session's active buffers. Typically, you do not need to flush buffers yourself. However, you may want to flush buffers if the event rate is low and you are delivering events in real time. Windows 2000: This value is not supported. EVENT_TRACE_CONTROL_QUERYRetrieves session properties and statistics. EVENT_TRACE_CONTROL_STOPStops the session. The session handle is no longer valid. EVENT_TRACE_CONTROL_UPDATEUpdates the session properties. Note that it is not safe to flush buffers or stop a trace session from DllMain. Return Value If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is one of the system error codes . The following table includes some common errors and their causes. Return codeDescription ERROR_BAD_LENGTHOne of the following is true: The Wnode.BufferSize member of Properties specifies an incorrect size. Properties does not have sufficient space allocated to hold a copy of the session name and log file name (if used). ERROR_INVALID_PARAMETEROne of the following is true: Properties is NULL. SessionName and SessionHandle are both NULL. The LogFileNameOffset member of Properties is not valid. The LoggerNameOffset member of Properties is not valid. The LogFileMode member of Properties specifies a combination of flags that is not valid. The Wnode.Guid member of Properties is SystemTraceControlGuid, but the SessionName parameter is not KERNEL_LOGGER_NAME. ERROR_BAD_PATHNAMEAnother session is already using the file name specified by the LogFileNameOffset member of the Properties structure. ERROR_MORE_DATAThe buffer for EVENT_TRACE_PROPERTIES is too small to hold all the information for the session. If you do not need the session's property information, you can ignore this error. If you receive this error when stopping the session, ETW will have already stopped the session before generating this error. ERROR_ACCESS_DENIEDOnly users with administrative privileges, users in the Performance Log Users group, and services running as LocalSystem, LocalService, NetworkService can control event tracing sessions. To grant a restricted user the ability to control trace sessions, add them to the Performance Log Users group. Only users with administrative privileges and services running as LocalSystem can control an NT Kernel Logger session. Windows XP and Windows 2000: Anyone can control a trace session. ERROR_WMI_INSTANCE_NOT_FOUNDThe given session is not running. Remarks Event trace controllers call this function. This function supersedes the FlushTrace , QueryTrace , StopTrace , and UpdateTrace functions. Requirements Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderEvntrace.h LibraryAdvapi32.lib DLLAdvapi32.dll Unicode and ANSI namesControlTraceW (Unicode) and ControlTraceA (ANSI) See Also EVENT_TRACE_PROPERTIES QueryAllTraces StartTrace Send comments about this topic to Microsoft Build date: 7/30/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa363696(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。