3.2.4.11 ITraceDataProvider

DisplayName

RW

The name of the provider. The name is provided by the user and can be read by the user but is otherwise ignored by the PLA protocol. The field exists so that the user can attach a semantically meaningful name to the ITraceDataProvider if he or she so chooses rather than having to differentiate providers based on the Guid property, defined below. The Guid in this context refers to the COM interface property, which is used as a PLA-UID and does not comply with the semantics of GUID specified in [C706].

Guid

RW

The PLA-UID of the provider. On collection, this PLA-UID uniquely identifies the provider to be enabled. The value 0000-0000-0000-0000-0000-0000-0000-0000 is never a valid provider PLA-UID, and therefore the Guid property is set to 0000-0000-0000-0000-0000-0000-0000-0000 when no provider is specified. The Guid in this context refers to the COM interface property, which is used as a PLA-UID and does not comply with the semantics of GUID specified in [C706].

The valid range for this property is from 0000-0000-0000-0000-0000-0000-0000-0001 to FFFF-FFFF-FFFF-FFFF-FFFF-FFFF-FFFF-FFFF.

Level

R

The list of levels for the provider. On collection, events from this provider are collected only if their levels are less than or equal to the value of the enabled level; this property is used in conjunction with the KeywordsAny and KeywordsAll properties to control which events are collected from a provider. The enabled level is stored in the Value property of the Level property. The level denotes the severity of event (as defined by the event provider). There are predefined trace levels that can be used to control tracing; there can be more trace levels that are defined in addition to these predefined levels. The maximum value of a level is 0x000000FF. The possible pre-defined levels are:

1. Log Always

2. Critical

3. Error

4. Warning

5. Informational

If the enabled level has the value of 3, all events with level 3, 2, or 1 will be collected. These levels semantically represent Warning, Error, and Critical events. If the enabled level has the value of 0, then events with any level will be collected. Setting the enabled level to 0 is equivalent to setting the enabled level to 0x000000FF.

KeywordsAny

R

The list of keywords of the provider. The keywords determine the category of events for the provider to write; this property is used in conjunction with the Level and KeywordsAll properties. On collection, events from this provider are collected only if their keywords include at least one of the keywords in KeywordsAny and all of the keywords in KeywordsAll. If KeywordsAny is zero, then the provider will successfully write all events assuming that the event's keywords pass the KeywordsAll check. The Value property of the KeywordsAny property stores the bitwise-or of the keywords in the KeywordsAny property.

KeywordsAll

R

The list of keywords of the provider. The keywords determine the category of events for the provider to write; this is used in conjunction with the KeywordsAny and Level properties. On collection, events from this provider are collected only if their keywords include all of the keywords in KeywordsAll. The Value property of the KeywordsAll property stores the bitwise-or of the keywords in the KeywordsAll property. If KeywordsAll is zero, then the provider will successfully write all events assuming that the event's keywords pass the KeywordsAny check.

Properties

R

The list of extra information that can be collected when events from this provider are collected. The possible properties are the user's security identifier, as specified in [MS-DTYP] section 2.4.2.3, (value 1), or the session identifier that is assigned by either the Remote Desktop Session Host server, Remote Desktop Virtualization Host server, or virtual machine (value 2).

FilterEnabled

RW

Determines whether provider-side filtering MUST be enabled. If the FilterEnabled property is set to VARIANT_TRUE, the filter stored in the FilterData property (as specified in section 3.2.4.11.10) will be used to filter the provider. Otherwise, the FilterData property will be ignored.

FilterType

RW

Not used. Because the value is currently not used, any ULONG is a valid value, so validation will always succeed for the property.

FilterData

RW

When the client enables tracing for a provider on the server, it has the option of passing back data to that provider. This data is provider-specific, and the client MUST know how the provider expects the FilterData to be formatted. The FilterData property can contain any arbitrary type that is understood by the trace provider but MUST NOT exceed 1 KB in total size. The PLA protocol has no knowledge of how this FilterData is constructed and what are its possible values. This data is opaque to the protocol. It serves as the transport for this data between the client and the server, and the PLA protocol only restriction on this property is that this data MUST NOT exceed 1 KB in size.

The FilterData that is specified by the client will be sent back to the server trace provider being enabled if the FilterEnabled property is set to VARIANT_TRUE. Upon receiving this FilterData, the provider MUST use it to control which events are logged; this property serves as a filter on the events that are logged by the provider. The PLA protocol has no knowledge of whether or not the provider did use the FilterData to control which events it logs.

For example, the client can specify an IP address as the value of the FilterData. When the trace provider receives this FilterData, it can only log events that have a matching IP address.

DisplayName (Get)

Retrieves the DisplayName property.

Opnum: 7

DisplayName (Put)

Sets the DisplayName property.

Opnum: 8

Guid (Get)

Retrieves the Guid property.

Opnum: 9

Guid (Put)

Sets the Guid property.

Opnum: 10

Level (Get)

Retrieves the Level property.

Opnum: 11

KeywordsAny (Get)

Retrieves the KeywordsAny property.

Opnum: 12

KeywordsAll (Get)

Retrieves the KeywordsAll property.

Opnum: 13

Properties (Get)

Retrieves the Properties property.

Opnum: 14

FilterEnabled (Get)

Retrieves the FilterEnabled property.

Opnum: 15

FilterEnabled (Put)

Sets the FilterEnabled property.

Opnum: 16

FilterType (Get)

Retrieves the FilterType property.

Opnum: 17

FilterType (Put)

Sets the FilterType property.

Opnum: 18

FilterData (Get)

Retrieves the FilterData property.

Opnum: 19

FilterData (Put)

Sets the FilterData property.

Opnum: 20

Query

Populates the other properties based on the local repository of providers.

Opnum: 21

Resolve

Used to resolve the properties.

Opnum: 22

SetSecurity

Updates the system-wide security descriptor of the provider.

Opnum: 23

GetSecurity

Retrieves the system-wide security descriptor of the provider.

Opnum: 24

GetRegisteredProcesses

Retrieves a list of processes that have registered as an event trace data provider.

Opnum: 25