<div class="content" name="EvtRpcPutChannelConfig" uuid="e02828fd-873d-4cc5-9b60-23ef31987275"><p>The EvtRpcPutChannelConfig (Opnum 21) method is used by a
client to update the configuration for a channel.</p><dl>
<dd>
<div><pre> 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
 );
</pre></div>
</dd></dl><p><b>binding: </b>An RPC binding handle as specified in
section <a href="1285c318-9f8c-4c6a-a963-7999557bf8d8" data-linktype="relative-path">2.2.21</a>.</p><p><b>channelPath: </b>A pointer to a string that
contains a channel name (this is not a file path as the parameter name might
suggest).</p><p><b>flags: </b>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.<a id="Appendix_A_Target_40"></a><a aria-label="Product behavior note 40" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_40" data-linktype="relative-path">&lt;40&gt;</a></p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Value</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0x00000000</td>
  <td>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.</td>
 </tr><tr>
  <td>0x00000001</td>
  <td>The server MUST open the existing channel entry in its channel table.</td>
 </tr><tr>
  <td>0x00000002</td>
  <td>Always create a new channel entry in the server&#39;s channel table and delete the existing entry.</td>
 </tr><tr>
  <td>0x00000003</td>
  <td>Only create a new channel entry in the server&#39;s channel table.</td>
 </tr></tbody></table>
</dd></dl><p><b>props: </b>A pointer to an <a href="14ba9fda-3402-44b2-b1cd-5318a6613a7f" data-linktype="relative-path">EvtRpcVariantList (section 2.2.9)</a>
structure containing channel properties, as defined in the following table.</p><dl>
<dd>
<table><thead>
  <tr>
   <th>
   <p>Index</p>
   </th>
   <th>
   <p>Type</p>
   </th>
   <th>
   <p>Meaning</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>0</td>
  <td>EvtRpcVarTypeBoolean</td>
  <td>Enabled. If true, the channel can accept new events. If false, any attempts to write events into this channel are automatically dropped.</td>
 </tr><tr>
  <td>1</td>
  <td>EvtRpcVarTypeUInt32</td>
  <td>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&#34;O:BAG:SYD:&#34;  L&#34;(A;;0xf0007;;;SY)&#34; // local system (read, write, clear)  L&#34;(A;;0x7;;;BA)&#34; // built-in admins (read, write, clear)  L&#34;(A;;0x7;;;SO)&#34; // server operators (read, write, clear)  L&#34;(A;;0x3;;;IU)&#34; // INTERACTIVE LOGON (read, write)  L&#34;(A;;0x3;;;SU)&#34; // SERVICES LOGON (read, write)  L&#34;(A;;0x3;;;S-1-5-3)&#34; // BATCH LOGON (read, write)  L&#34;(A;;0x3;;;S-1-5-33)&#34; // write restricted service (read,write)  L&#34;(A;;0x1;;;S-1-5-32-573)&#34;; // event log readers (read)  The default permissions for System are (shown using SDDL):  L&#34;O:BAG:SYD:&#34;  L&#34;(A;;0xf0007;;;SY)&#34; // local system (read, write, clear)  L&#34;(A;;0x7;;;BA)&#34; // built-in admins (read, write, clear)  L&#34;(A;;0x3;;;BO)&#34; // backup operators (read, write)  L&#34;(A;;0x5;;;SO)&#34; // server operators (read, clear)  L&#34;(A;;0x1;;;IU)&#34; // INTERACTIVE LOGON (read)  L&#34;(A;;0x3;;;SU)&#34; // SERVICES LOGON (read, write)  L&#34;(A;;0x1;;;S-1-5-3)&#34; // BATCH LOGON (read)  L&#34;(A;;0x2;;;S-1-5-33)&#34; // write restricted service (write)  L&#34;(A;;0x1;;;S-1-5-32-573)&#34;; // event log readers (read)  When the Custom value is used, the Access property will contain the defined SDDL.</td>
 </tr><tr>
  <td>2</td>
  <td>EvtRpcVarTypeUInt32</td>
  <td>Channel Type. One of four values:  0: Admin  1: Operational.  2: Analytic  3: Debug  For more information, see [MSDN-EVTLGCHWINEVTLG].</td>
 </tr><tr>
  <td>3</td>
  <td>EvtRpcVarTypeString</td>
  <td>OwningPublisher. The name of the publisher that defines and registers the channel with the system.</td>
 </tr><tr>
  <td>4</td>
  <td>EvtRpcVarTypeBoolean</td>
  <td>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).</td>
 </tr><tr>
  <td>5</td>
  <td>EvtRpcVarTypeString</td>
  <td>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.</td>
 </tr><tr>
  <td>6</td>
  <td>EvtRpcVarTypeBoolean</td>
  <td>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.</td>
 </tr><tr>
  <td>7</td>
  <td>EvtRpcVarTypeBoolean</td>
  <td>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.</td>
 </tr><tr>
  <td>8</td>
  <td>EvtRpcVarTypeUInt64</td>
  <td>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.</td>
 </tr><tr>
  <td>9</td>
  <td>EvtRpcVarTypeString</td>
  <td>LogFilePath. The server changes the file path to the event log file for the channel.</td>
 </tr><tr>
  <td>10</td>
  <td>EvtRpcVarTypeUInt32</td>
  <td>Level. Events with a level property less than or equal to this specified value are logged to the channel.</td>
 </tr><tr>
  <td>11</td>
  <td>EvtRpcVarTypeUInt64</td>
  <td>Keywords. Events with a keyword bit contained in the keywords bitmask set are logged to the channel.</td>
 </tr><tr>
  <td>12</td>
  <td>EvtRpcVarTypeGuid</td>
  <td>ControlGuid. A GUID value. The server SHOULD ignore this value.&lt;41&gt;</td>
 </tr><tr>
  <td>19</td>
  <td>EvtRpcVarTypeStringArray</td>
  <td>PublisherList. A list of publishers that can raise events into the channel.</td>
 </tr><tr>
  <td>20</td>
  <td>EvtRpcVarTypeUInt32</td>
  <td>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.</td>
 </tr></tbody></table>
</dd></dl><p><b>error: </b>A pointer to an <a href="94a5d4d1-0f80-4af3-b7c6-d61a6aa60b7b" data-linktype="relative-path">RpcInfo (section 2.2.1)</a>
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.</p><p><b>Return Values: </b>The method MUST return ERROR_SUCCESS
(0x00000000) on success; otherwise, it MUST return an implementation-specific
nonzero value as specified in <a href="../ms-erref/1bc92ddf-b79e-413c-bbaa-99a5281a6c90" data-linktype="relative-path">[MS-ERREF]</a>.<a id="Appendix_A_Target_42"></a><a aria-label="Product behavior note 42" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_42" data-linktype="relative-path">&lt;42&gt;</a></p><p>In response to this request from the client, the server MUST
verify that the <i>channelPath</i> 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.</p><p>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 <a href="../ms-rpce/290c38b1-92fe-4229-91e6-4fc376610c15" data-linktype="relative-path">[MS-RPCE]</a>
section <a href="../ms-rpce/326c9de1-4602-4d78-848d-8b4e11e6ed80" data-linktype="relative-path">3.2.3.4.2</a>.
Then, if the client specifies a channel, the server SHOULD read the channel&#39;s
access property (as specified in section <a href="f5ae9a61-6f5e-4751-965e-394349c7d950" data-linktype="relative-path">3.1.4.21</a>) 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 <a href="../ms-dtyp/4f1bbcbb-814a-4c70-a11e-2a5b8779a6f9" data-linktype="relative-path">2.5.3.2</a>).
</p><p>If the client specifies 0x00000000 for the <i>flags</i>
value, the server MUST try to find the channel entry specified by the <i>channelPath</i>
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 <i>channelPath</i> 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.</p><table><thead>
  <tr>
   <th>
   <p>Property</p>
   </th>
   <th>
   <p>Default Value</p>
   </th>
  </tr>
 </thead><tbody><tr>
  <td>Enabled</td>
  <td>true</td>
 </tr><tr>
  <td>Isolation</td>
  <td>0</td>
 </tr><tr>
  <td>ChannelType</td>
  <td>0</td>
 </tr><tr>
  <td>OwningPublisher</td>
  <td>null</td>
 </tr><tr>
  <td>Classic</td>
  <td>false</td>
 </tr><tr>
  <td>Access</td>
  <td>&#34;O:BAG:SYD:(A;;0xf0007;;;SY)(A;;0x7;;;BA)(A;;0x7;;;SO)&#34;(A;;0x3;;;IU)(A;;0x3;;;SU)(A;;0x3;;;S-1-5-3)(A;;0x3;;;S-1-5-33)(A;;0x1;;;S-1-5-32-573)&#34;</td>
 </tr><tr>
  <td>Retention</td>
  <td>false</td>
 </tr><tr>
  <td>Autobackup</td>
  <td>false</td>
 </tr><tr>
  <td>maxSize</td>
  <td>20 * 1024 * 1024</td>
 </tr><tr>
  <td>LogFilePath</td>
  <td>%systemfolder%\winevt\&lt;channelname&gt;.evtx</td>
 </tr><tr>
  <td>Level</td>
  <td>0</td>
 </tr><tr>
  <td>Keywords</td>
  <td>0xFFFFFFFFFFFFFFFF</td>
 </tr><tr>
  <td>ControlGuid</td>
  <td>{00000000-0000-0000-0000-000000000000}</td>
 </tr><tr>
  <td>BufferSize</td>
  <td>64K</td>
 </tr><tr>
  <td>MinBuffers</td>
  <td>2 * Number of the CPUs.</td>
 </tr><tr>
  <td>MaxBuffers</td>
  <td>22 + MinBuffers</td>
 </tr><tr>
  <td>Latency</td>
  <td>1</td>
 </tr><tr>
  <td>ClockType</td>
  <td>0</td>
 </tr><tr>
  <td>SidType</td>
  <td>1</td>
 </tr><tr>
  <td>PublisherList</td>
  <td>null</td>
 </tr><tr>
  <td>FileMax</td>
  <td>0</td>
 </tr></tbody></table><p>If the client specifies 0x00000001 for the <i>flags</i>
value and the specified channel entry is not found in the channel table, the
server MUST return ERROR_NOT_FOUND (0x00000490).</p><p>If the client specifies 0x00000002 for the <i>flags</i>
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.</p><p>If the client specifies the 0x00000003 for the <i>flags</i>
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).</p><p>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).<a id="Appendix_A_Target_43"></a><a aria-label="Product behavior note 43" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_43" data-linktype="relative-path">&lt;43&gt;</a></p><p><b>Note</b>  The configuration properties for <i>BufferSize</i>,
<i>MinBuffers</i>, <i>MaxBuffers</i>, <i>Latency</i>, <i>ClockType</i>, and <i>SIDType</i>
can&#39;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.<a id="Appendix_A_Target_44"></a><a aria-label="Product behavior note 44" href="65f22d62-5f0f-4306-85c4-50fb9e77075b#Appendix_A_44" data-linktype="relative-path">&lt;44&gt;</a> 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.</p><p>If the previous checks succeed, the server MUST attempt to
update the channel&#39;s properties using the value specified in the <i>props</i>
parameter. The server SHOULD proceed in the following manner to update the data
for each channel property:</p><p>The server SHOULD allocate a memory block with the same size
as the EvtRpcVariantList (section 2.2.9) pointed to by the <i>props</i>
parameter. If the memory allocation fails, the server SHOULD return
ERROR_OUTOFMEMORY (0x0000000E). The server then copies all the data in the <i>props</i>
parameter into the new allocated memory block. Before copying the data, the
server SHOULD validate the data as follows:</p><ul><li><p><span><span> 
</span></span>The Isolation property SHOULD be either 0, 1, or 2, if the client
has specified that property.</p>
</li><li><p><span><span> 
</span></span>The Channel type property SHOULD be either 0, 1, 2, or 3, if the
client has specified that property.</p>
</li><li><p><span><span> 
</span></span>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.</p>
</li><li><p><span><span> 
</span></span>The LogFilePath property MUST be a valid file path string for the
server&#39;s file system, if the client specifies that property.</p>
</li><li><p><span><span> 
</span></span>The server SHOULD verify that the publishers specified in the
PublisherList property exist in the server&#39;s publisher table. If so, the server
SHOULD add the current channel to the publisher entries in the server&#39;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.</p>
</li></ul><p>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 <a href="79e81642-5ef1-4963-9e77-798d2a6c2b1a" data-linktype="relative-path">EvtRpcAssertConfig</a>
is called or the server restarts. <b>EvtRpcAssertConfig</b> 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 <a href="8f10cb24-8c8d-4dca-b5dc-ee28706c5b78" data-linktype="relative-path">3.1.1.5</a>.
Before applying the properties, all the server&#39;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 <b>EvtRpcAssertConfig</b> method, see the
processing rules in EvtRpcAssertConfig (section 3.1.4.29). 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.</p><p>The server MUST return a value indicating success or failure
for this operation.</p></div>