API Events

API events record calls to the HDLC API. Each API call will generate at lease two trace events, one on entry to the API which records the arguments, and one on return from the API which records the return code and any returned data. Both the call and return events include the caller process and thread ID. API calls which involve asynchronous notification may record a completion event if the API call returns ERROR_IO_PENDING. Completion events do not contain the process and thread ID of the caller, but may be matched to the last API call of the specified type that returned ERROR_IO_PENDING because only one call of each type may be pending.

The purpose of splitting each API call into an entry and return event is to allow observation of other events that may occur as a result of processing the API call, but before the API call returns. The split event logging maintains synchronization of such events with the API events.

The following API calls are NOT traced:

MgslOpen

MgslClose

MgslGetTraceEvent

MgslSetPortConfig

MgslGetPortConfig

The contents of the EventData member of the MGSL_TRACE_EVENT structure will be specific to each API EventType. Most API event types have event data structures defined to allow easier access to the event data. Some API event types return only a simple data type, such as an unsigned long, in which case there is no associated event data structure. The reference below lists the API event types and the associated event data types.

ApiEvent_CancelReceiveCall

MgslCancelReceive call.

EventData

typedef struct _API_TRACE_CANCEL_RECEIVE_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
} API_TRACE_CANCEL_RECEIVE_CALL, *PAPI_TRACE_CANCEL_RECEIVE_CALL;

ApiEvent_CancelReceiveReturn

MgslCancelReceive return.

EventData

typedef struct _API_TRACE_CANCEL_RECEIVE_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_CANCEL_RECEIVE_RETURN, *PAPI_TRACE_CANCEL_RECEIVE_RETURN;

ApiEvent_CancelTransmitCall

MgslCancelTransmit call.

EventData

typedef struct _API_TRACE_CANCEL_TRANSMIT_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
} API_TRACE_CANCEL_TRANSMIT_CALL, *PAPI_TRACE_CANCEL_TRANSMIT_CALL;

ApiEvent_CancelTransmitReturn

MgslCancelTransmit return.

EventData

typedef struct _API_TRACE_CANCEL_TRANSMIT_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_CANCEL_TRANSMIT_RETURN, *PAPI_TRACE_CANCEL_TRANSMIT_RETURN;

ApiEvent_CancelWaitEventCall

MgslCancelWaitEvent call.

EventData

typedef struct _API_TRACE_CANCEL_WAIT_EVENT_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
} API_TRACE_CANCEL_WAIT_EVENT_CALL, *PAPI_TRACE_CANCEL_WAIT_EVENT_CALL;

ApiEvent_CancelWaitEventReturn

MgslCancelWaitEvent return.

EventData

typedef struct _API_TRACE_CANCEL_WAIT_EVENT_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_CANCEL_WAIT_EVENT_RETURN, *PAPI_TRACE_CANCEL_WAIT_EVENT_RETURN;

ApiEvent_EnableReceiverCall

MgslEnableReceiver call.

EventData

typedef struct _API_TRACE_ENABLE_RECEIVER_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    BOOL EnableFlag;
} API_TRACE_ENABLE_RECEIVER_CALL, *PAPI_TRACE_ENABLE_RECEIVER_CALL;

ApiEvent_EnableReceiverReturn

MgslEnableReceiver return.

EventData

typedef struct _API_TRACE_ENABLE_RECEIVER_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_ENABLE_RECEIVER_RETURN, *PAPI_TRACE_ENABLE_RECEIVER_RETURN;

ApiEvent_EnableTransmitterCall

MgslEnableTransmitter call.

EventData

typedef struct _API_TRACE_ENABLE_TRANSMITTER_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    BOOL EnableFlag;
} API_TRACE_ENABLE_TRANSMITTER_CALL, *PAPI_TRACE_ENABLE_TRANSMITTER_CALL;

ApiEvent_EnableTransmitterReturn

MgslEnableTransmitter return.

EventData

typedef struct _API_TRACE_ENABLE_TRANSMITTER_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_ENABLE_TRANSMITTER_RETURN, *PAPI_TRACE_ENABLE_TRANSMITTER_RETURN;

ApiEvent_GetAssignedResourcesCall

MgslGetAssignedResources call

EventData

typedef struct API_TRACE_GET_ASSIGNED_RESOURCES_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    PMGSL_ASSIGNED_RESOURCES pResources;
} API_TRACE_GET_ASSIGNED_RESOURCES_CALL, *PAPI_TRACE_GET_ASSIGNED_RESOURCES_CALL;

ApiEvent_GetAssignedResourcesReturn

MgslGetAssignedResources return

EventData

typedef struct API_TRACE_GET_ASSIGNED_RESOURCES_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
    MGSL_ASSIGNED_RESOURCES Resources;
} API_TRACE_GET_ASSIGNED_RESOURCES_RETURN,  *PAPI_TRACE_GET_ASSIGNED_RESOURCES_RETURN;

ApiEvent_GetParamsCall

MgslGetParams call

EventData

typedef struct _API_TRACE_GET_PARAMS_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    PMGSL_PARAMS pParams;
} API_TRACE_GET_PARAMS_CALL, *PAPI_TRACE_GET_PARAMS_CALL;

ApiEvent_GetParamsReturn

MgslGetParams return

EventData

typedef struct _API_TRACE_GET_PARAMS_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
    MGSL_PARAMS Params;
} API_TRACE_GET_PARAMS_RETURN, *PAPI_TRACE_GET_PARAMS_RETURN;

ApiEvent_GetSerialSignalsCall

MgslGetSerialSignals call

EventData

typedef struct _API_TRACE_GET_SERIAL_SIGNALS_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    PUCHAR pSerialSignals;
} API_TRACE_GET_SERIAL_SIGNALS_CALL, *PAPI_TRACE_GET_SERIAL_SIGNALS_CALL;

ApiEvent_GetSerialSignalsReturn

MgslGetSerialSignals return

EventData

typedef struct _API_TRACE_GET_SERIAL_SIGNALS_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
    UCHAR SerialSignals;
} API_TRACE_GET_SERIAL_SIGNALS_RETURN, *PAPI_TRACE_GET_SERIAL_SIGNALS_RETURN;

ApiEvent_GetTraceLevelCall

MgslGetTraceLevel call

EventData

typedef struct API_TRACE_GET_TRACE_LEVEL_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    PULONG pTraceLevel;
} API_TRACE_GET_TRACE_LEVEL_CALL, *PAPI_TRACE_GET_TRACE_LEVEL_CALL;

ApiEvent_GetTraceLevelReturn

MgslGetTraceLevel return

EventData

typedef struct API_TRACE_GET_TRACE_LEVEL_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
    ULONG TraceLevel;
} API_TRACE_GET_TRACE_LEVEL_RETURN, *PAPI_TRACE_GET_TRACE_LEVEL_RETURN;

ApiEvent_LoopModeSendDoneCall

MgslLoopModeSendDone call.

EventData

typedef struct API_TRACE_LOOPMODE_SEND_DONE_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
} API_TRACE_LOOPMODE_SEND_DONE_CALL, *PAPI_TRACE_LOOPMODE_SEND_DONE_CALL;

ApiEvent_LoopModeSendDoneReturn

MgslLoopModeSendDone return.

EventData

typedef struct API_TRACE_LOOPMODE_SEND_DONE_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_LOOPMODE_SEND_DONE_RETURN, *PAPI_TRACE_LOOPMODE_SEND_DONE_RETURN;

ApiEvent_ReceiveCall

MgslReceive call. Note that this event records the pointer to the receive request, and if the receive request pointer is valid, the contents of the receive request header are recorded. If the pointer is invalid then the RcvReq member is undefined.

EventData

typedef struct _API_TRACE_RECEIVE_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    PMGSL_RECEIVE_REQUEST pRcvReq;
    MGSL_RECEIVE_REQUEST RcvReq;
    LPOVERLAPPED pOverlapped;
} API_TRACE_RECEIVE_CALL, *PAPI_TRACE_RECEIVE_CALL;

ApiEvent_ReceiveComplete

A pending call to MgslReceive has been completed. Note that only the receive request header is recorded (returned status and data count). The received data is recorded in the DataEvent_ReceiveData trace event if data tracing is enabled.

EventData

typedef struct _API_TRACE_RECEIVE_COMPLETE
{
    MGSL_RECEIVE_REQUEST RcvReq;
} API_TRACE_RECEIVE_COMPLETE, *PAPI_TRACE_RECEIVE_COMPLETE;

ApiEvent_ReceiveReturn

MgslReceive return. Note that only the receive request header is recorded (returned status and data count). The received data is recorded in the DataEvent_ReceiveData trace event if data tracing is enabled.

EventData

typedef struct _API_TRACE_RECEIVE_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
    MGSL_RECEIVE_REQUEST RcvReq;
} API_TRACE_RECEIVE_RETURN, *PAPI_TRACE_RECEIVE_RETURN;

ApiEvent_ResetTraceBuffersCall

MgslResetTraceBuffersCall.

EventData

typedef struct _API_TRACE_RESET_TRACE_BUFFERS_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
} API_TRACE_RESET_TRACE_BUFFERS_CALL, *PAPI_TRACE_RESET_TRACE_BUFFERS_CALL;

ApiEvent_ResetTraceBuffersReturn

MgslResetTraceBuffers return.

EventData

typedef struct _API_TRACE_RESET_TRACE_BUFFERS_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_RESET_TRACE_BUFFERS_RETURN, *PAPI_TRACE_RESET_TRACE_BUFFERS_RETURN;

ApiEvent_SetIdleModeCall

MgslSetIdleMode call.

EventData

typedef struct _API_TRACE_SET_IDLE_MODE_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG IdleMode;
} API_TRACE_SET_IDLE_MODE_CALL, *PAPI_TRACE_SET_IDLE_MODE_CALL;

ApiEvent_SetIdleModeReturn

MgslSetIdleMode return.

EventData

typedef struct _API_TRACE_SET_IDLE_MODE_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_SET_IDLE_MODE_RETURN, *PAPI_TRACE_SET_IDLE_MODE_RETURN;

ApiEvent_SetParamsCall

MgslSetParameters call. If the pointer to the parameters structure is valid then the contents of the parameters structure is also logged, otherwise the Params member is undefined.

EventData

typedef struct _API_TRACE_SET_PARAMS_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    PMGSL_PARAMS pParams;
    MGSL_PARAMS Params;
} API_TRACE_SET_PARAMS_CALL, *PAPI_TRACE_SET_PARAMS_CALL;

ApiEvent_SetParamsReturn

MgslSetParameters return.

EventData

typedef struct _API_TRACE_SET_PARAMS_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_SET_PARAMS_RETURN, *PAPI_TRACE_SET_PARAMS_RETURN;

ApiEvent_SetSerialSignalsCall

MgslSetSerialSignals call.

EventData

typedef struct _API_TRACE_SET_SERIAL_SIGNALS_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    UCHAR SerialSignals;
} API_TRACE_SET_SERIAL_SIGNALS_CALL, *PAPI_TRACE_SET_SERIAL_SIGNALS_CALL;

ApiEvent_SetSerialSignalsReturn

MgslSetSerialSignals return.

EventData

typedef struct API_TRACE_SET_SERIAL_SIGNALS_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_SET_SERIAL_SIGNALS_RETURN, *PAPI_TRACE_SET_SERIAL_SIGNALS_RETURN;

ApiEvent_SetTraceLevelCall

MgslSetTraceLevel call.

EventData

typedef struct API_TRACE_SET_TRACE_LEVEL_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG TraceLevel;
} API_TRACE_SET_TRACE_LEVEL_CALL, *PAPI_TRACE_SET_TRACE_LEVEL_CALL;

ApiEvent_SetTraceLevelReturn

MgslSetTraceLevel return.

EventData

typedef struct API_TRACE_SET_TRACE_LEVEL_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
} API_TRACE_SET_TRACE_LEVEL_RETURN, *PAPI_TRACE_SET_TRACE_LEVEL_RETURN;

ApiEvent_TransmitCall

MgslTransmit call. The contents of the transmit buffer are not recorded in this event. The data will appear in a DataEvent_TransmitData event if data tracing is enabled.

EventData

typedef struct _API_TRACE_TRANSMIT_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    PUCHAR pBuffer;
    ULONG BufferSize;
    PULONG pStatus;
    LPOVERLAPPED pOverlapped;
} API_TRACE_TRANSMIT_CALL, *PAPI_TRACE_TRANSMIT_CALL;

ApiEvent_TransmitCompletion

A pending call to MgslTransmit has completed.

EventData

ULONG    Returned transmit status

ApiEvent_TransmitReturn

MgslTransmit return.

EventData

typedef struct _API_TRACE_TRANSMIT_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
    ULONG Status;
} API_TRACE_TRANSMIT_RETURN, *PAPI_TRACE_TRANSMIT_RETURN;

ApiEvent_WaitEventCall

MgslWaitEvent call.

EventData

typedef struct _API_TRACE_WAIT_EVENT_CALL
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG EventMask;
    PULONG pEvents;
    LPOVERLAPPED pOverlapped;
} API_TRACE_WAIT_EVENT_CALL, *PAPI_TRACE_WAIT_EVENT_CALL;

ApiEvent_WaitEventComplete

A pending call to MgslWaitEvent has completed.

EventData

ULONG    Returned Events

ApiEvent_WaitEventReturn

Wait for serial signal event return

EventData

typedef struct _API_TRACE_WAIT_EVENT_RETURN
{
    ULONG ProcessId;
    ULONG ThreadId;
    ULONG ReturnCode;
    ULONG Events;
} API_TRACE_WAIT_EVENT_RETURN, *PAPI_TRACE_WAIT_EVENT_RETURN;
Previous Contents Next