IControlManager

  • Article

Represents the Windows Performance Recorder manager, which controls Event Tracing for Windows (ETW) sessions. The client passes a collection of profiles using the IProfileCollection interface, and the manager can start, update, cancel, save, stop, or query the ETW session or providers that each profile describes. The client can pass in a pointer to the IControlProgressHandler handler to receive updates about the operation that the manager performs.

Syntax

{
  [propget, id(1), helpstring("property ControlProgressHandler")] HRESULT ControlProgressHandler
    ([out, retval] IControlProgressHandler** ppControlProgressHandler);
  [propput, id(1), helpstring("property ControlProgressHandler")] HRESULT ControlProgressHandler
    ([in] IControlProgressHandler* pControlProgressHandler);
  [id(2), helpstring("Start")] HRESULT Start
    ([in] IProfileCollection* pProfileCollection);
  [id(3), helpstring("Update")] HRESULT Update
    ([in] IProfileCollection* pProfileCollection);
  [id(4), helpstring("Cancel")] HRESULT Cancel
    ([in] IProfileCollection* pProfileCollection);
  [id(5), helpstring("Save")] HRESULT Save
    ([in] BSTR bstrFileName,
    [in] IProfileCollection* pProfileCollection,
    [in] ITraceMergeProperties* pTraceMergeProperties);
  [id(6), helpstring("Stop")] HRESULT Stop
    ([in] BSTR bstrFileName,
    [in] IProfileCollection* pProfileCollection,
    [in] ITraceMergeProperties* pTraceMergeProperties);
  [id(7), helpstring("QueryXML")] HRESULT QueryXML
    ([out] BSTR* pbstrResults,
    [in] VARIANT_BOOL fValidateRuntimeState);
  [id(8), helpstring("Query")] HRESULT Query
    ([out] IProfileCollection** ppProfileCollection,
    [in] VARIANT_BOOL fValidateRuntimeState);
  [propget, id(9), helpstring("property TraceMergeTextHandler")] HRESULT TraceMergeTextHandler
    ([out, retval] ITraceMergeTextHandler** ppTraceMergeTextHandler);
  [propput, id(9), helpstring("property TraceMergeTextHandler")] HRESULT TraceMergeTextHandler
    ([in] ITraceMergeTextHandler* pTraceMergeTextHandler);
  [propget, id(10), helpstring("property TemporaryTraceDirectory")] HRESULT TemporaryTraceDirectory
    ([out, retval] BSTR* pbstrTemporaryTraceDirectory);
  [propput, id(10), helpstring("property TemporaryTraceDirectory")] HRESULT TemporaryTraceDirectory
    ([in] BSTR bstrTemporaryTraceDirectory);
  [id(11), helpstring("GetProviderNameFromGuid")] HRESULT GetProviderNameFromGuid
    ([out] BSTR* bstrProviderIdStr,
    [in] REFGUID ProviderId);
  [id(12), helpstring("GetProviderGuidFromName")] HRESULT GetProviderGuidFromName
    ([out] GUID* ProviderId,
    [in] BSTR bstrProViderName);
};

Functions

The following table describes the functions that this interface provides.

Function Description

Start

Starts a recording.

Update

Updates a profile collection.

Cancel

Stops a recording without saving any data.

Save

Saves a recording that is logged to circular buffers in memory to the specified event trace log (ETL) file.

Stop

Stops a recording and saves it to the specified event trace log (ETL) file.

QueryXML

Indicates the XML format of the currently running profile and whether the profile is running properly.

Query

Queries the properties of session and providers in all profiles.

propget

Gets the specified property.

propput

Sets the specified property.

GetProviderNameFromGuid

Gets the provider name of the specified GUID.

GetProviderGuidFromName

Gets the provider GUID of the specified name.

Properties

The following table describes the parameters of properties that this interface can get or set.

Property Parameters Description

ControlProgressHandler

ppControlProgressHandler [out]

Pointer to the client-side implementation of the IControlProgressHandler interface.

ControlProgressHandler

pControlProgressHandler [in]

Pointer to the client-side implementation of the IControlProgressHandler interface. E_POINTER indicates an invalid pointer.

TraceMergeTextHandler

ppTraceMergeTextHandler [out]

Pointer to the text and some other merge time information in the trace injected by the ITraceMergeTextHandler interface.

TraceMergeTextHandler

pTraceMergeTextHandler [in]

Pointer to the text and some other merge time information in the trace injected by the ITraceMergeTextHandler interface. E_POINTER indicates an invalid pointer.

TemporaryTraceDirectory

pbstrTemporaryTraceDirectory [out]

Pointer to the path of the directory where the pre-merged trace files are logged. The default is the %temp% folder.

TemporaryTraceDirectory [in]

bstrTemporaryTraceDirectory

Path of the directory where the pre-merged trace files are logged.

Interfaces