3.2.4.1 IDataCollectorSet

Article
06/24/2021

The IDataCollectorSet interface is used to query, update, and control a data collector set.

Objects that implement this interface represent a data collector set. The following are the properties that MUST be implemented by objects that implement the IDataCollectorSet interface.

Property	Read/write	Description
DataCollectors	R	List of data collectors in this set.
DataManager	R	Object that defines the policies for data retention and report generation. An example of data retention policies include when and if to compress data to a cabinet file or delete it. Example report generation policies include the steps to take to generate the report. The IDataManager interface, which the DataManager object implements, is specified in section 3.2.4.2.
Description	RW	The localizable description of the data collector set.
DescriptionUnresolved	R	The description of the data collector set in its raw form (prior to localization).
DisplayName	RW	The localizable display name of the data collector set.
DisplayNameUnresolved	R	The display name of the data collector set in its raw form (prior to localization).
Duration	RW	Determines the maximum amount of time that a data collector set MUST run. A value of 0 indicates that the data collector set MUST NOT not be stopped automatically.
Keywords	RW	List of keywords associated with the data collector sets. Keywords are metadata for describing a data collector set; they are not parsed by the data collector set. They are intended to help the end user understand the contents of the data collector set, and serve no functional purpose as to how the data collector set is executed on the server. There MUST be at most 256 keywords that are associated with a data collector set; each keyword MUST NOT be more than 1024 characters in length. The keyword string cannot be the empty string, nor can the keyword string contain the semicolon (";") character.
LatestOutputLocation	RW	The full path of the directory where data was stored the last time the data collector set ran.
Name	R	Name of the data collector set.
OutputLocation	R	The full path of the directory where data would be stored if the data collector set were to start now.
RootPath	RW	The full path of the directory under which the data collector set stores its files. When subdirectories are used, they are created under this root directory.
Schedules	R	List of schedules that determines when the data collector set runs automatically. Each schedule specifies a time when the data collector will be started, the first day it will be started at that time, the last day it will be started at that time, and the days of the week it will be started. Each schedule is specified by an object implementing the ISchedule interface, specified in section 3.2.4.12.
SchedulesEnabled	RW	Determines if the automatic start of the data collector set based on its schedules MUST be enabled or disabled. If enabled, the data collector set is automatically started when the conditions for one of the schedules (stored in the Schedules property) is met. If the data collector set is already running when a schedule condition is met, it is not restarted, and instead continues to run. If disabled, the data collector set can only be started manually. A data collector set is manually started by a call to Start, as specified in section 3.2.4.1.56.
Security	RW	The security descriptor of the data collector set that determines the access rights of groups or users. The security descriptor is expressed using the Security Descriptor Description Language (SDDL), as specified in [MS-DTYP] section 2.5.1. Changing the security descriptor can impact the ability of both local and remote users to read, modify, run, and delete the data collector set.
Segment	RW	If this property is set to TRUE, the server MUST stop all data collectors when a segmentation condition occurs, increment the SerialNumber property, update LatestOutputLocation property, and restart all the data collectors, which begins logging to the new LatestOutputLocation. The FileNameFormat and SubdirectoryNameFormat properties are used to determine the new value of LatestOutputLocation. If both FileNameFormatPattern and SubdirectoryFormatPattern are set to plaNone, or both are set to plaPattern but no value is specified for FileNameFormatPattern and SubdirectoryFormatPattern, then the value of the LatestOutputLocation is not changed. In this case, the retention of the data that was obtained during the previous execution of the data collector depends on the respective properties of the data collector. For example, if LogAppend is specified for a data collector, then the events generated in the new segment are appended to the events that were added to the file during the previous segment execution. If this property is set to FALSE, the server MUST stop all the data collectors when a segmentation condition occurs. The segmentation condition is specified either by SegmentMaxDuration or SegmentMaxSize. PLA SHOULD NOT <12> stop the data collector set when the size of the active log file reaches SegmentMaxSize; rather, it creates a new file to enable the data collector set to continue logging information.
SegmentMaxDuration	RW	Determines for how long a data collector set MUST run, in seconds, before a new segment MUST be created. A value of 0 indicates that there is no segment time limit. The default value is zero. Any unsigned long is a valid value for this property.
SegmentMaxSize	RW	Determines the maximum size, in megabytes, of a log file. When the size is reached, a new log file MUST be created. A value of 0 indicates that there is no segment size limit. The segment size is unlimited. The default value is zero. Any unsigned long is a valid value for this property.
SerialNumber	RW	The serial number of the data collector set. Each time the data collector set runs it is assigned a serial number. The serial number for each data collector set starts at 1 and is incremented each time the data collector set runs. Each run of the data collector set has a serial number that is unique across all runs of the data collector set. Accordingly, each run of the data collector set has its own serial number and no two runs of the same data collector set have the same serial number. However, it is possible that two different runs of two different data collector sets will have the same serial number (the serial number is unique among all runs of one data collector set; it is not unique among all runs of all data collector sets). The serial number can optionally be used by an AutoPathFormat, which will cause the serial number to be appended to the name of the directory or files pertaining to each run of the data collector set. Using the serial number as an AutoPathFormat prevents possible collisions in directory or file naming. This property serves as a serial number across all runs of a particular data collector set on a particular machine, not across all data collector sets or all machines. Any unsigned long is a valid value for this property.
Server	R	Name of the server this data collector set belongs to.
Status	R	Status of the data collector set.
StopOnCompletion	RW	Determines whether a data collector set MUST stop when all data collectors complete. A data collector completes when the first segment is collected. The definition of completion depends on the data collector type, and is not generally defined as the point at which the data collector has collected all possible data. For an IConfigurationDataCollector, completion occurs when all data has been collected. For an IAlertDataCollector or IApiTracingDataCollector, completion occurs immediately (that is, no data will be collected if this property is set to true). For an IPerformanceCounterDataCollector or ITraceDataCollector, completion occurs immediately if no limit is set on the output file size or time spent writing to the output file. If there is a maximum file size per output file, or a maximum duration per output file, completion occurs when the data collector has finished writing to the current file.
Subdirectory	RW	Retrieves or sets a base subdirectory of the root path where the next instance of the data collector set will write its logs.
SubdirectoryFormat	RW	Determines what to include in the decoration the subdirectory name.
SubdirectoryFormatPattern	RW	If patterns are to be included in the decoration of subdirectory names, determines the pattern to use.
Task	RW	Name of the task that is executed when the data collector set stops or prior to switching to a new segment. The name of the task needs to correspond to the name of a job stored in the Task Scheduler. When a task is created, the creator of a task specifies its name as a BSTR. More information on the names of Task Scheduler jobs (referred to as paths in the Task Scheduler documentation) is specified in [MS-TSCH] section 2.3.11. This documentation describes the semantics of the task name and explains the restrictions on task names.
TaskArguments	RW	If a task is to run, this specifies what arguments MUST be passed to it.
TaskRunAsSelf	RW	When a Task Scheduler job is executed by the DataCollectorSet, this property determines which user it will run as. If the property is set to true, the Task Scheduler job runs as the same user that the DataCollectorSet is running as. By default, this means the Task Scheduler job will run with System credentials. Consequently, it is not advisable to set this property to true when the task to be run is not fully trusted, unless the UserAccount property for the DataCollectorSet has been carefully configured. When the property is set to false, the Task Scheduler job will run with the credentials it was created with. The mechanism in use here is delegation. When the creator of a data collector set sets this property to true, this task is thereby granted the same rights that the data collector set has. When the RunAsSelf property is set to false, no delegation occurs. The task will run only with the permissions it was created with. The credentials that the task runs with are initially created with SchRpcRegisterTask specified in [MS-TSCH] section 3.2.5.4.2 and can be updated by SASetAccountInformation specified in [MS-TSCH] section 3.2.5.3.4.
TaskUserTextArguments	RW	If a task is to run and the arguments, as specified in section 3.2.4.1.38, include the {usertext} variable, this property determines the value of this variable.
UserAccount	R	Determines the user account under which the data collector set will run.
Xml	R	The XML representation of the data collector set.

A data collector set can be represented as an XML file, which can be used to serialize (using IDataCollectorSet::Xml (Get)3.2.4.1.46) and deserialize (using IDataCollectorSet::SetXml 3.2.4.1.58) it. The format of the XML that defines a data collector set is as follows. All the elements of the data collector set, as well as all child elements within the data collector set element, are specified in section 3.2.4.19:

 <DataCollectorSet>
    <Status></Status>
   <Duration></Duration>
   <Description></Description>
   <DescriptionUnresolved></DescriptionUnresolved>
   <DisplayName></DisplayName>
   <DisplayNameUnresolved></DisplayNameUnresolved>
   <SchedulesEnabled></SchedulesEnabled>
   <Schedule>
      <StartDate/>
      <EndDate/>
      <StartTime/>
      <Days/>
   </Schedule>
   <LatestOutputLocation></LatestOutputLocation>
   <Name></Name>
   <OutputLocation></OutputLocation>
   <RootPath></RootPath>
   <Segment></Segment>
   <SegmentMaxDuration></SegmentMaxDuration>
   <SegmentMaxSize></SegmentMaxSize>
   <SerialNumber></SerialNumber>
   <Server></Server>
   <Subdirectory></Subdirectory>
   <SubdirectoryFormat></SubdirectoryFormat>
   <SubdirectoryFormatPattern></SubdirectoryFormatPattern>
   <Task></Task>
   <TaskRunAsSelf></TaskRunAsSelf>
   <TaskArguments></TaskArguments>
   <TaskUserTextArguments></TaskUserTextArguments>
   <UserAccount></UserAccount>
   <Security></Security>
   <StopOnCompletion></StopOnCompletion>
   <!-- elements for different data collector types…please see respective sections -->
 </DataCollectorSet:>

The nodes "Keyword", "Schedule", and "FolderAction" can have multiple copies—one for each keyword, schedule, or folder action, respectively. For each data collector, one node under the "DataCollectorSet" node is also added; the name of the node depends on the type of data collector, and is documented in the data collector section.

The Keywords property is a safearray, which is translated into XML as a series of Keyword nodes. For example, if Keywords is set to {"A", "B", "C"}, there are three Keyword nodes, one for each keyword.

Similarly, Schedules is a collection of Schedule objects, which means that if the Schedules property contains three schedules, three nodes called "Schedule" are created for each schedule.

DataCollectors is not in XML for the same reason as Schedules. However, because data collectors have types instead of having a number of "DataCollector" nodes, there are a number of typed data collector nodes. For example, "AlertDataCollector" or "PerformanceCounterDataCollector".

Methods in RPC Opnum order:

Method	Description
DataCollectors (Get)	List of data collectors in this data collector set. Opnum: 7
Duration (Get)	Retrieves the Duration property. Opnum: 8
Duration (Put)	Sets the Duration property. Opnum: 9
Description (Get)	Retrieves the Description property. Opnum: 10
Description (Put)	Sets the Description property. Opnum: 11
DescriptionUnresolved (Get)	Retrieves the DescriptionUnresolved property. Opnum: 12
DisplayName (Get)	Retrieves the display name of the data collector set . Opnum: 13
DisplayName (Put)	Sets the DisplayName property. Opnum: 14
DisplayNameUnresolved (Get)	Receives the display name of the data collector set in its original form. Opnum: 15
Keywords (Get)	Retrieves the Keywords property. Opnum: 16
Keywords (Put)	Sets the Keywords property. Opnum: 17
LatestOutputLocation (Get)	Retrieves the LatestOutputLocation property. Opnum: 18
LatestOutputLocation (Put)	Sets the LatestOutputLocation property. Opnum: 19
Name (Get)	Retrieves the Name property. Opnum: 20
OutputLocation (Get)	Retrieves the OutputLocation property. Opnum: 21
RootPath (Get)	Retrieves the RootPath property. Opnum: 22
RootPath (Put)	Sets the RootPath property. Opnum: 23
Segment (Get)	Retrieves the Segment property. Opnum: 24
Segment (Put)	Sets the Segment property. Opnum: 25
SegmentMaxDuration (Get)	Retrieves the SegmentMaxDuration property. Opnum: 26
SegmentMaxDuration (Put)	Sets the SegmentMaxDuration property. Opnum: 27
SegmentMaxSize (Get)	Retrieves the SegmentMaxSize property. Opnum: 28
SegmentMaxSize (Put)	Sets the SegmentMaxSize property. Opnum: 29
SerialNumber (Get)	Retrieves the SerialNumber property. Opnum: 30
SerialNumber (Put)	Sets the SerialNumber property. Opnum: 31
Server (Get)	Retrieves the Server property. Opnum: 32
Status (Get)	Retrieves the Status property. Opnum: 33
Subdirectory (Get)	Retrieves the Subdirectory property. Opnum: 34
Subdirectory (Put)	Sets the Subdirectory property. Opnum: 35
SubdirectoryFormat (Get)	Retrieves the SubdirectoryFormat property. Opnum: 36
SubdirectoryFormat (Put)	Sets the SubdirectoryFormat property. Opnum: 37
SubdirectoryFormatPattern (Get)	Retrieves the SubdirectoryFormatPattern property. Opnum: 38
SubdirectoryFormatPattern (Put)	Sets the SubdirectoryFormatPattern property. Opnum: 39
Task (Get)	Retrieves the Task property. Opnum: 40
Task (Put)	Sets the Task property. Opnum: 41
TaskRunAsSelf (Get)	Retrieves the TaskRunAsSelf property. Opnum: 42
TaskRunAsSelf (Put)	Sets the TaskRunAsSelf property. Opnum: 43
TaskArguments (Get)	Retrieves the TaskArguments property. Opnum: 44
TaskArguments (Put)	Sets the TaskArguments property. Opnum: 45
TaskUserTextArguments (Get)	Retrieves the TaskUserTextArguments property. Opnum: 46
TaskUserTextArguments (Put)	Sets the TaskUserTextArguments property. Opnum: 47
Schedules (Get)	Retrieves the Schedules property. Opnum: 48
SchedulesEnabled (Get)	Retrieves the SchedulesEnabled property. Opnum: 49
SchedulesEnabled (Put)	Sets the SchedulesEnabled property. Opnum: 50
UserAccount (Get)	Retrieves the UserAccount property. Opnum: 51
Xml (Get)	Retrieves the Xml property. Opnum: 52
Security (Get)	Retrieves the Security property. Opnum: 53
Security (Put)	Sets the Security property. Opnum: 54
StopOnCompletion (Get)	Retrieves the StopOnCompletion property. Opnum: 55
StopOnCompletion (Put)	Sets the StopOnCompletion property. Opnum: 56
DataManager (Get)	Retrieves the DataManager property. Opnum: 57
SetCredentials	Specifies the user account under which the data collector set runs. Opnum: 58
Query	Loads the properties of a data collector set from storage to memory. Opnum: 59
Commit	Updates, validates, or saves a data collector set or flushes the event trace data collectors of a data collector set. Opnum: 60
Delete	Removes the data collector set from storage if it is not running. Opnum: 61
Start	Manually starts the data collector set. Opnum: 62
Stop	Manually stops the data collector set. Opnum: 63
SetXml	Sets the property values of the data collector set based on an XML file. Opnum: 64
SetValue	Sets a user-defined value. Opnum: 65
GetValue	Retrieves a user-defined value. Opnum: 66

Opnums 0, 1, and 2 are reserved for the IUnknown interface. Opnums 3, 4, 5, and 6 are reserved for the IDispatch interface.

3.2.4.1 IDataCollectorSet

Additional resources