Real-Time Connect

When given 0x0B as its FunctionCode argument, the NtTraceControl function connects a real-time consumer to a logger. Microsoft’s name for this function code is not known. This note deals only with the function’s behaviour that is specific to this function code. The function’s general behaviour is here taken as assumed knowledge.

A fixed-size context is expected as both input and output. Microsoft’s name for this real-time connection context is not known (though an insufficiently substantial hint is that another structure’s pointer to this structure is named RealtimeConnectContext). It is the same in both 32-bit and 64-bit Windows but has changed between versions, notably to be reworked significantly for Windows 7. The following changes of size are known.

In version 6.1 and higher, most of the structure provides input for creation of an EtwConsumer object. Internally this is an ETW_REALTIME_CONSUMER structure. Type information for this is available in public symbol files and it seems highly likely that Microsoft uses the same names and types in both structures for members that correspond closely. Where pointers are padded to 64 bits so that the kernel deals with one format for both 32-bit and 64-bit callers, type information that Microsoft has disclosed for other structures that are involved with NtTraceControl, e.g., WMI_LOGGER_INFORMATION, suggests a convention that Microsoft perhaps uses for this structure too.

ULONG LoggerId;

ULONG ReservedBufferSpaceSize;

union {
    UCHAR *ReservedBufferSpace;
    ULONG64 ReservedBufferSpace64;
};

union {
    HANDLE DisconnectEvent;
    ULONG64 DisconnectEvent64;
};

union {
    HANDLE DataAvailableEvent;
    ULONG64 DataAvailableEvent64;
};

union {
    SINGLE_LIST_ENTRY *UserBufferListHead;
    ULONG64 UserBufferListHead64;
};

union {
    ULONG *UserBufferCount;
    ULONG64 UserBufferCount64;
};

union {
    ULONG *EventsLostCount;
    ULONG64 EventsLostCount64;
};

union {
    ULONG *BuffersLostCount;
    ULONG64 BuffersLostCount;
};

Version 6.0 defines no object type for real-time event consumers and therefore has a very different implementation. Each connection of a real-time consumer to a logger is represented not by a handle but by a sequence number. When tracing events, the kernel does not have direct access to the user-mode memory supplied by the consumer but instead writes through a pipe.

If the input and output buffers are not both exactly the expected size, the function returns STATUS_INVALID_PARAMETER.

TO BE DONE?