3.1.4.29 EvtRpcAssertConfig (Opnum 15)

  • Article

The EvtRpcAssertConfig (Opnum 15) method indicates to the server that the publisher or channel configuration has been updated. 

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

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

path: A pointer to a string that contains a channel or publisher name to be updated.

flags: The client MUST specify exactly one of the following.

Value

Meaning

EvtRpcChannelPath

0x00000000

Path specifies a channel name.

EvtRpcPublisherName

0x00000001

Path specifies a publisher name.

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 SHOULD first validate the path parameter. The server MUST interpret the path parameter as a channel name if the flags parameter is equal to 0x00000000. The server SHOULD try to determine if the specified channel name has been already registered in its channel table (as specified in section 3.1.1.5). If the flags value is 0x00000001, the server MUST interpret path as a publisher name. The server SHOULD then check if the publisher has been registered in its publisher table (as specified in section 3.1.1.3). The server SHOULD fail the operation if the validation of path fails. The server MAY<59> return the error ERROR_INVALID_PARAMETER (0x00000057) to indicate such failure.

Next, the server MUST verify that the caller has write access to the information and MUST fail the method if the caller does not have write 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 access property is not present for the channel, the channel gets a default SDDL which is "O:BAG:SYD:(A;;0xf0005;;;SY)(A;;0x5;;;BA)(A;;0x1;;;S-1-5-32-573)".

The server assumes that something has changed some properties of a publisher or channel before processing this call. Such changes can be made by the EvtRpcPutChannelConfig method (as specified in section 3.1.4.22). The changes made by EvtRpcPutChannelConfig only create an in-memory copy of the new properties of the publisher or channel, but do not impact the server's immediate behavior. EvtRpcAssertConfig puts the in-memory copy created by EvtRpcPutChannelConfig into effect. When applying the changes from the in-memory copy, the server SHOULD check the potential conflicts of the new settings with existing settings. The following is a list of checks the server SHOULD make before accepting the changes:

  1. If the channel type is set, the server SHOULD check whether the new value is one of the four allowed values which are specified in section 3.1.4.22.

  2. If the owning publisher is set, the server SHOULD check whether the publisher exists and also check whether the channel is owned by another publisher. The server SHOULD go through its channel table and make sure the OwningPublisher field points to a different publisher's name and no two channels have the same publisher name.

After that, the server activates the new properties of the channel or the publisher based on the latest settings and frees the memory associated with the in-memory copy of the new channel or publisher properties allocated during the call to EvtRpcPutChannelConfig.

In the interval between the calls to EvtRpcPutChannelConfig and EvtRpcAssertConfig, there are effectively two copies of the channel or publisher properties. One copy is the encapsulated but inactive set of properties created by EvtRpcPutChannelConfig, waiting to be made active. The other copy is the unencapsulated set of active property values that are stored in individual run-time variables within the implementation. It is an implementation-specific detail whether these variables exist in a form that resembles the encapsulated representation in terms of memory layout or other matters not germane to the semantics of the properties. The encapsulated property set is by definition ephemeral, serving only as a temporary holding vessel for the updated channel or publisher properties until the EvtRpcAssertConfig method is called.

When this method is called, the server activates the new properties of the channel or publisher in a two-stage process.  First, the server stores the values in the encapsulated property set into whatever persistent storage the server uses to store channel and publisher properties between invocations of the server itself.  Second, the server loads the new property values from persistent storage, using them to update the unencapsulated, active variables that implement the properties at run time. In this way, the server simultaneously puts the new values into effect and ensures that those values will remain in effect if the server is restarted.

When this two-stage process is complete, the encapsulated property set serves no further purpose and the server frees the memory associated with it.

Note that this protocol does not include a method for changing publisher configuration data. The client SHOULD provide this functionality if it wants to call this function specifying the publisher. For more information, see section 3.2.7.

The configuration properties of the channels and publishers SHOULD include the following:

  • Physical location of the publisher's event definition binaries

  • Channel security settings

  • Channel and publisher names

  • Enabled/disabled state or any other implementation-dependent configurable settings

The server MUST NOT change those states until this method is called.

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