4 Protocol Examples
In the following example, a client requests to receive critical events from two providers on a given remote machine that queues a maximum of 10 events per session.
According to the provider manifests, the provider GUIDs are 080197d0-d2c7-4b03-a559-aa63191c21a0 and f4fc081a-13f7-4979-b79f-9e9ce7873b18.
The client specifies a Session Name of "Example Session" and calls the MSFT_NetEventSession CreateInstance (section 3.1.4.1.1) intrinsic method on the server.
The server verifies that the name "Example Session" is not already in use, and if it is not, allocates a new GUID (120d3b52-1607-49cb-9d3f-5080002d0eaf) for the Session ID, creates an event session entry with the Session ID and the client’s Session Name, and returns the object reference to the client.
The client calls the MSFT_NetEventProvider CreateInstance (section 3.1.4.1.5) intrinsic method on the server, passing the GUID of the first provider (080197d0-d2c7-4b03-a559-aa63191c21a0) and the Session ID allocated in step 2.
The server locates the event session object in its Session Table, verifies that the provider GUID matches a provider ID in a provider manifest, and adds an Event Provider entry to its Associated Provider List for the first event provider.
The client calls the MSFT_NetEventProvider CreateInstance intrinsic method on the server, passing the GUID of the second provider (f4fc081a-13f7-4979-b79f-9e9ce7873b18) and the Session ID allocated in step 2.
The server locates the event session object in its Session Table, verifies that the provider GUID matches a provider ID in a provider manifest, and adds an Event Provider entry to its Associated Provider List for the second event provider.
The client calls the MSFT_NetEventSession Start (section 3.1.4.1.2) method.
The server verifies that the Associated Provider List is not empty, starts an RPC endpoint, and changes the Session State to Running.
The client calls the RpcNetEventOpenSession (section 3.1.4.2.1) method, passing the name from Session Name from step 1, "Example Session".
The server searches its Session Table for a session with a matching name, and when one is located, allocates a Session Handle and stores it in the session entry. The server then begins collecting events from the associated event providers into the event session entry’s Queued Event List and returns the Session Handle to the client.
In this example, the server collects more events than the maximum amount specified for storage in the Queued Event List. Therefore, after the Queued Event List is full, the server starts incrementing the event session entry’s Lost Event Count.
The client calls the RpcNetEventReceiveData (section 3.1.4.2.2) method to retrieve the events, passing in the Session Handle acquired in step 10.
The server locates the event session entry corresponding to the specified Session Handle and determines that the Queued Event List is full. The server immediately completes the call to RpcNetEventReceiveData with an EVENT_BUFFER (section 2.2.2.1) containing 11 structures. The first ten structures are EventRecord structures (section 2.3.2.1) holding the 10 queued events, and the last is a NET_EVENT_LOST structure (section 2.3.2.3) containing the number of lost events. The events are removed from the Queued Event List, allowing more events to start being queued for delivery in the next call from the client.
The client determines that the call to RpcNetEventReceiveData has completed and then calls the MSFT_NetEventSession Stop (section 3.1.4.1.3) method.
The server stops the RPC endpoint, removes all state for the event session, including any queued events, and completes the call to RpcNetEventReceiveData as successful.
In the example above, the client could have called the RpcNetEventCloseSession (section 3.1.4.2.3) method. However, calling this method was not necessary because the call to MSFT_NetEventSession Stop removed all of the resources that this method would have removed.