4.1 Query Example
In this example, the client wants to obtain events from a channel log file and render the resultant events as XML text.
This involves the following steps:
The client registers with RPC to obtain an RPC binding handle to the service based on the endpoint information specified in section 2.1. For information on how to get the RPC binding handle, see [MSDN-BNDHNDLS].
The client calls the EvtRpcRegisterLogQuery (section 3.1.4.12) method to establish a query over the log file and to obtain a query result and operation control handles.
error_status_t EvtRpcRegisterLogQuery( [in] RPC_BINDING_HANDLE binding = {binding handle from step 1.}, [in, unique, range(0, MAX_RPC_CHANNEL_PATH_LENGTH)] LPCWSTR path = "Application", [in, range(1, MAX_RPC_QUERY_LENGTH)] LPCWSTR query = "*", [in] DWORD flags = 0x00000101 [out, context_handle] PCONTEXT_HANDLE_LOG_QUERY* handle, [out, context_handle] PCONTEXT_HANDLE_OPERATION_CONTROL* opControl, [out] DWORD* queryChannelInfoSize, [out, size_is(,*queryChannelInfoSize), range(0,MAX_RPC_QUERY_CHANNEL_SIZE)] EvtRpcQueryChannelInfo** queryChannelInfo, [out] RpcInfo *error );When the server processes this call, it opens the Application channel, saves the * as the query expression, and creates two handles.
Note This example uses * as the query; see sections 4.5 and 4.6 for examples of structured queries.
The call returns successfully, and the client is given two handles: a query result handle and an operation control handle. The former is used to enumerate the results, and the latter is used to cancel a currently executing control handle.
As noted in section 3.1.4.12, the query result handle is a query object from the server side. It contains the channel path, the query filter XPath expression, and the result cursor value. For this example, the channel path is "Application", the XPath filter expression is "*" and the result cursor value is 0. The operation control handle is a control object that contains only one Boolean field which indicates whether the query operation has been canceled or not. In this example, the value is currently false which means the operation has not yet been canceled by the client.
The client enumerates events in the resultant list by calling the EvtRpcQueryNext (section 3.1.4.13) method by using the query handle obtained in the previous step.
error_status_t EvtRpcQueryNext( [in, context_handle] PCONTEXT_HANDLE_LOG_QUERY logQuery = { handle obtained by the call to EvtRpcRegisterLogQuery }, [in] DWORD numRequestedRecords = 5, [in] DWORD timeOutEnd = 3000, [in] DWORD flags = 0, [out] DWORD* numActualRecords, [out, size_is(,*numActualRecords), range(0, MAX_RPC_RECORD_COUNT)] DWORD** eventDataIndices, [out, size_is(,*numActualRecords), range(0, MAX_RPC_RECORD_COUNT)] DWORD** eventDataSizes, [out] DWORD* resultBufferSize, [out, size_is(,*resultBufferSize), range(0, MAX_RPC_BATCH_SIZE)] BYTE** resultBuffer );The server implements this call by returning the requested number of events (or as many events as it has) in BinXml form.
See section 4.8 for an example in BinXml form.
The client enumerates through the events, using multiple calls to the EvtRpcQueryNext (section 3.1.4.13) method, until it no longer responds to events, or it reaches the end of the log file.
If the client's query expression selects sparse events, and the log file contains a huge number of events, the EvtRpcQueryNext can take a long time to complete. In this case, the client has the option to cancel the EvtRpcQueryNext call by passing the query result handle to the EvtRpcCancel (section 3.1.4.34) method.
For each event, it is translated from BinXml encoding to the XML representation.
This is done according to the BinXml ABNF, as specified in section 3.1.4.7.
The server is not involved in this step.
If the event XML representation conforms to event.xsd (for more information, see section 2.2.13), standard attributes can be retrieved either directly from the BinXml representation or after translating to text XML.
The client optionally translates the event into text XML. See section 4.8 for an example of how to translate from BinXml form into XML event format.
When the client is done enumerating, it closes both the query and operation control handles using EvtRpcClose. In this call, the server frees all resources related to the query result.
error_status_t EvtRpcClose( [in, out, context_handle] void** handle = {query handle} ); error_status_t EvtRpcClose( [in, out, context_handle] void** handle = {operation control handle} );