3.1.4.21 EvtRpcGetChannelConfig (Opnum 20)

The EvtRpcGetChannelConfig (opnum 20) method is used by a client to get the configuration for a channel.

 error_status_t EvtRpcGetChannelConfig(
   /* [in] RPC_BINDING_HANDLE binding, {the binding handle will be generated by MIDL} */
   [in, range(1, MAX_RPC_CHANNEL_NAME_LENGTH), string] 
     LPCWSTR channelPath,
   [in] DWORD flags,
   [out] EvtRpcVariantList* props
 );

binding: An RPC binding handle as specified in section 2.2.21.

channelPath: A pointer to a string that contains the name of a channel for which the information is needed.

flags: A 32-bit unsigned integer that MUST be set to zero when sent and MAY be ignored on receipt.<38>

props: A pointer to an EvtRpcVariantList structure to be filled with channel properties, as defined in the following table.

Note The index column in the following table is the array index, not the actual field of the EvtRpcVariantList structure. The returned data is an array of EvtRpcVariantList for which the index value is used to identify the elements in the array. For example, index 0 means the first element of the returned array.

Index	Type	Meaning
0	EvtRpcVarTypeBoolean	Enabled. If true, the channel can accept new events. If false, any attempts to write events into this channel are automatically dropped.
1	EvtRpcVarTypeUInt32	Channel Isolation. It defines the default access permissions for the channel. Three values are allowed: 0: Application. 1: System. 2: Custom. The default isolation is Application. The default permissions for Application are (shown using SDDL): L"O:BAG:SYD:" L"(A;;0xf0007;;;SY)" // local system (read, write, clear) L"(A;;0x7;;;BA)" // built-in admins (read, write, clear) L"(A;;0x7;;;SO)" // server operators (read, write, clear) L"(A;;0x3;;;IU)" // INTERACTIVE LOGON (read, write) L"(A;;0x3;;;SU)" // SERVICES LOGON (read, write) L"(A;;0x3;;;S-1-5-3)" // BATCH LOGON (read, write) L"(A;;0x3;;;S-1-5-33)" // write restricted service (read,write) L"(A;;0x1;;;S-1-5-32-573)"; // event log readers (read) The default permissions for System are (shown using SDDL): L"O:BAG:SYD:" L"(A;;0xf0007;;;SY)" // local system (read, write, clear) L"(A;;0x7;;;BA)" // built-in admins (read, write, clear) L"(A;;0x3;;;BO)" // backup operators (read, write) L"(A;;0x5;;;SO)" // server operators (read, clear) L"(A;;0x1;;;IU)" // INTERACTIVE LOGON (read) L"(A;;0x3;;;SU)" // SERVICES LOGON (read, write) L"(A;;0x1;;;S-1-5-3)" // BATCH LOGON (read) L"(A;;0x2;;;S-1-5-33)" // write restricted service (write) L"(A;;0x1;;;S-1-5-32-573)"; // event log readers (read) When the Custom value is used, the Access property will contain the defined SDDL.
2	EvtRpcVarTypeUInt32	Channel type. One of four values: 0: Admin 1: Operational 2: Analytic 3: Debug For more information, see [MSDN-EVTLGCHWINEVTLG].
3	EvtRpcVarTypeString	OwningPublisher. Name of the publisher that defines and registers the channel with the system. For more information on how the server reacts to changes of this property, see section 3.1.4.22.
4	EvtRpcVarTypeBoolean	ClassicEventlog. If true, the channel represents an event log created according to the EventLog Remoting Protocol, not this protocol (EventLog Remoting Protocol Version 6.0). The server maintains two channel tables: one for the EventLog Remoting Protocol Version 6.0 and one for the legacy EventLog Remoting Protocol. The table for the legacy EventLog Remoting Protocol is called "log table". For more information on the legacy "log table", see [MS-EVEN]. Any channel coming from the new "channel table" gets the value as false, any channel name that is in the legacy "log table" gets the value as true.
5	EvtRpcVarTypeString	Access. A Security Descriptor Description Language (SDDL) string, as specified in [MS-DTYP], that represents access permissions to the channels. If the isolation attribute is set to Application or System, the access descriptor controls read access to the file (the write permissions are ignored). If the isolation attribute is set to Custom, the access descriptor controls write access to the channel and read access to the file.
6	EvtRpcVarTypeBoolean	Retention. If set to true, events can never be overwritten unless explicitly cleared. If set to false, events are overwritten as needed when the event log is full.
7	EvtRpcVarTypeBoolean	AutoBackup. When set to true, the event log file associated with the channel is closed as soon as it reaches the maximum size specified by the MaxSize property, and a new file is opened to accept new events. If the new file reaches maximum size, another new file will be generated and the previous new file will be backed up. The events in backed up files cannot be queried from this channel in the server unless the client specifies the backup log file names in a separate query.
8	EvtRpcVarTypeUInt64	MaxSize. The value that indicates at which point the size (in bytes) of the event log file stops increasing. When the size is greater than or equal to this value, the file growth stops.
9	EvtRpcVarTypeString	LogFilePath. File path to the event log file for the channel. The path is saved in the channel config and read out by the server when client requests it.
10	EvtRpcVarTypeUInt32	Level. Events with a level property less than or equal to this specified value are logged to the channel.
11	EvtRpcVarTypeUInt64	Keywords. Events with a keyword bit contained in the Keywords bitmask set are logged to the channel.
12	EvtRpcVarTypeGuid	ControlGuid. A GUID value. The client SHOULD ignore this value.
13	EvtRpcVarTypeUInt64	BufferSize. Size of the events buffer (in kilobytes) used for asynchronous event delivery. This property is for providing events. Typically the events generated by a publisher are first written to memory buffers on the server. Once the buffer used is full, that buffer is written to a disk file. The BufferSize is used to specify the size of the buffer. The server allocates buffers according to the BufferSize value. The number of buffers the server can allocate is controlled by the MinBuffers and MaxBuffers properties. The server's specific implementation can allocate any number of buffers between MinBuffers and MaxBuffers.
14	EvtRpcVarTypeUInt32	MinBuffers. The minimum number of buffers used for asynchronous event delivery. For more information, see the preceding BufferSize information.
15	EvtRpcVarTypeUInt32	MaxBuffers. The maximum number of buffers used for asynchronous event delivery. For more information, see the preceding BufferSize information.
16	EvtRpcVarTypeUInt32	Latency. The number of seconds of inactivity (if events are delivered asynchronously and no new events are arriving) after which the event buffers MUST be flushed to the server. As specified in the description for BufferSize property, the server keeps a number of buffers when writing events. If the buffers are full, the server writes the buffers to disk file. However, if a certain amount of time elapses and the buffers are still not full, the server SHOULD write the buffers to disk. That certain amount of time is the latency property.
17	EvtRpcVarTypeUInt32	ClockType. One of two values: 0: SystemTime. Use the system time. When set to this value, the server uses the system time type (which is low-resolution on most platforms) for a time stamp field of any event it writes into this channel. 1: Query Performance Counter. The server uses a high-resolution time type for the time stamp field of any event it writes into this channel. Note The timestamp is simply written into the event without any special handling. Which is to say, the server behavior does not change if a channel's Clock type is SystemTime or Query Performance Counter.
18	EvtRpcVarTypeUInt32	SIDType. One of two values: 0: The events written by the server to this channel will not include the publisher's SID. 1: The events written by the server to this channel will include the publisher's SID.
19	EvtRpcVarTypeStringArray	PublisherList. List of publishers that can raise events into the channel. This returns the same list as is returned by the EvtRpcGetPublisherList method, as specified in section 3.1.4.24.
20	EvtRpcVarTypeUint32	FileMax. Maximum number of log files associated with an analytic or debug channel. When the number of logs reaches the specified maximum, the system begins to overwrite the logs, beginning with the oldest. A FileMax value of 0 or 1 indicates that only one file is associated with this channel. A FileMax of 0 is default.<39>

Return Values: The method MUST return ERROR_SUCCESS (0x00000000) on success; otherwise, it MUST return an implementation-specific nonzero value as specified in [MS-ERREF].

In response to this request from the client, the server MUST verify that the channelPath parameter specifies a valid channel name. The server MUST fail the method if the parameter is invalid with the error ERROR_INVALID_PARAMETER (0x00000057). The server checks if a channel name is valid by searching the given name in its channel table.

Next, the server MUST verify that the caller has read access to the information and MUST fail the method if the caller does not have read access with the error ERROR_ACCESS_DENIED (0x00000005). To perform the access check, the server SHOULD first determine the identity of the caller. Information determining the identity of the caller for the purpose of performing an access check is specified in [MS-RPCE] section 3.2.3.4.2. Then, if the client specifies a channel, the server SHOULD read the channel's access property (as specified in section 3.1.4.21) as the security descriptor string. Next, the server SHOULD be able to perform the write and clear access check using the Access Check algorithm (as specified in [MS-DTYP] section 2.5.3.2).

If the previous checks succeed, the server MUST attempt to return the list of a channel's properties. The server MUST fill the output parameter props with all the properties for the channel (which are specified in the preceding props properties table) into an EvtRpcVariant list. The server SHOULD only fail the method if the system memory is inadequate with the error ERROR_OUTOFMEMORY (0x0000000E). The client MUST NOT interpret the values in this list. They MUST be passed uninterpreted to the higher-layer protocol or client application. For more information, see [MSDN-EVENTS].

Note that in the interval between a client calling the EvtRpcPutChannelConfig and EvtRpcAssertConfig methods, the server holds two copies of the channel properties. One copy is held in the channel table. The other copy is an encapsulated but inactive set of properties created by EvtRpcPutChannelConfig that is held in temporary storage. The server MUST return the properties held in the channel table. It MUST NOT return the encapsulated but inactive set of properties created by EvtRpcPutChannelConfig. See EvtRpcAssertConfig (section 3.1.4.29) for more information.

The server MUST NOT update its state as a result of this method, nor SHOULD the server apply any channel properties. The server SHOULD always return ERROR_SUCCESS (0x00000000) if the inputs are valid, because reading the channel properties SHOULD never fail.

The server MUST return a value indicating success or failure for this operation.