EvtRpcPutChannelConfig (Opnum 21)

The EvtRpcPutChannelConfig (Opnum 21) method is used by a client to update the configuration for a channel.

 error_status_t EvtRpcPutChannelConfig(
   /* [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,
   [in] EvtRpcVariantList* props,
   [out] RpcInfo* error

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

channelPath: A pointer to a string that contains a channel name (this is not a file path as the parameter name might suggest).

flags: A 32-bit unsigned integer that indicates what to do depending on the existence of the channel. This MUST be set to one of the following, and the server SHOULD return ERROR_INVALID_PARAMETER (0x00000057) if the flag is not one of the following values.<38>




The server MUST open the existing channel entry in its channel table or create a new entry if the specified channel is not in the table.


The server MUST open the existing channel entry in its channel table.


Always create a new channel entry in the server's channel table and delete the existing entry.


Only create a new channel entry in the server's channel table.

props: A pointer to an EvtRpcVariantList (section 2.2.9) structure containing channel properties, as defined in the following table.






Enabled. If true, the channel can accept new events. If false, any attempts to write events into this channel are automatically dropped.



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.



Channel Type. One of four values:

  • 0: Admin

  • 1: Operational.

  • 2: Analytic

  • 3: Debug

For more information, see [MSDN-EVTLGCHWINEVTLG].



OwningPublisher. The name of the publisher that defines and registers the channel with the system.



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).



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.



Retention. If set to true, events can never be overwritten unless explicitly cleared. This is the way to configure the logs to be circular. If set to false, events are overwritten as needed when the event log is full.



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.



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.



LogFilePath. The server changes the file path to the event log file for the channel.



Level. Events with a level property less than or equal to this specified value are logged to the channel.



Keywords. Events with a keyword bit contained in the keywords bitmask set are logged to the channel.



ControlGuid. A GUID value. The server SHOULD ignore this value.<39>



PublisherList. A list of publishers that can raise events into the channel.



FileMax. The 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 MaxFile of 0 is the default.

error: A pointer to an RpcInfo (section 2.2.1) structure in which to place error information in the case of a failure. The RpcInfo (section 2.2.1) structure fields MUST be set to nonzero values if the error is related to a particular property. All nonzero values MUST be treated the same. If the method succeeds, the server MUST set all of the values in the structure to 0.

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].<40>

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 write access to the information and MUST fail the method with the error ERROR_ACCESS_DENIED (0x00000005) if the caller does not have write access. 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 Then, if the client specifies a channel, the server SHOULD read the channel's access property (as specified in section 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

If the client specifies 0x00000000 for the flags value, the server MUST try to find the channel entry specified by the channelPath parameter in its channel table. If the server does not find the channel entry in the table, it creates a new entry with the parameter channelPath as the new channel name. The creation of a new channel table entry SHOULD only fail when there is inadequate memory. The server SHOULD return ERROR_OUTOFMEMORY (0x0000000E) in that case. When a new channel is created, the server SHOULD assign the default property values to the channel as in the following table.


Default Value


















20 * 1024 * 1024












2 * Number of the CPUs.


22 + MinBuffers











If the client specifies 0x00000001 for the flags value and the specified channel entry is not found in the channel table, the server MUST return ERROR_NOT_FOUND (0x00000490).

If the client specifies 0x00000002 for the flags value, the processing rule is similar to processing rule 1 except that when the server finds the exiting channel entry, it SHOULD delete it first before creating a new one. Delete an existing entry SHOULD never fail.

If the client specifies the 0x00000003 for the flags value, the server MUST fail the method if the specified channel is already in the channel table with the error code ERROR_ALREADY_EXISTS (0x000000B7).

The server SHOULD check if the publisher specified has already registered in its publisher table when the client tries to update the owning publisher property. If not, the server SHOULD fail the method with ERROR_INVALID_PARAMETER (0x00000057).<41>

Note The configuration properties for BufferSize, MinBuffers, MaxBuffers, Latency, ClockType, and SIDType can't be updated by the client. These properties are maintained by the server administrator on the physical machine only and cannot be updated through the remote protocol methods. The server administrator can specify these properties with any allowable values.<42> The server SHOULD make sure the client does not update these properties. The server SHOULD fail the method with the error ERROR_INVALID_OPERATION (0x000010DD) in this case.

If the previous checks succeed, the server MUST attempt to update the channel's properties using the value specified in the props parameter. The server SHOULD proceed in the following manner to update the data for each channel property:

The server SHOULD allocate a memory block with the same size as the EvtRpcVariantList (section 2.2.9) pointed to by the props parameter. If the memory allocation fails, the server SHOULD return ERROR_OUTOFMEMORY (0x0000000E). The server then copies all the data in the props parameter into the new allocated memory block. Before copying the data, the server SHOULD validate the data as follows:

  • The Isolation property SHOULD be either 0, 1, or 2, if the client has specified that property.

  • The Channel type property SHOULD be either 0, 1, 2, or 3, if the client has specified that property.

  • The Access property string SHOULD be a valid security descriptor as specified in section [MS-DTYP], if the client specifies that property. Note that the only access permissions defined for channels are read, write, and clear; if a client attempts to specify any other access permissions in the security descriptor, the server SHOULD ignore them.

  • The LogFilePath property MUST be a valid file path string for the server's file system, if the client specifies that property.

  • The server SHOULD verify that the publishers specified in the PublisherList property exist in the server's publisher table. If so, the server SHOULD add the current channel to the publisher entries in the server's publisher table for every publisher specified by the PublisherList property so that as soon as the new settings are applied, the server is prepared for those publishers to publish events to this channel.

If any of the validation checks fail, the server SHOULD return ERROR_INVALID_DATA. After copying the data, the server SHOULD return to the client with ERROR_SUCCESS (0x00000000), but SHOULD NOT apply the new channel properties until EvtRpcAssertConfig is called or the server restarts. EvtRpcAssertConfig causes the server to apply an in-memory copy of the channel configuration, whereas when the server restarts, it loads channel configuration data from persistent storage as specified in section Before applying the properties, all the server's behaviors are still the same as they were originally, even after the method has successfully returned to the client. For information on the server saving the configuration and then applying the changes with the EvtRpcAssertConfig method, see the processing rules in EvtRpcAssertConfig (section The server SHOULD check if the value passed by the client is within the allowed range. If not, the server SHOULD return ERROR_INVALID_PARAMETER (0x00000057). The server will not fail the method if all the previous checks are passed.

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