MgslPutTraceEvent

Prototype
`ULONG MgslPutTraceEvent( HANDLE hDevice, PMGSL_TRACE_EVENT pTraceEvent );`
Parameters
`hDevice`	handle to open port
`pTraceEvent`	pointer to trace event structure
Return Value
`ERROR_SUCCESS (0)`	trace event added to trace buffers
`ERROR_INVALID_HANDLE`	hDevice is invalid
`ERROR_INVALID_PARAMETER`	pTraceEvent is invalid.

Add a trace event to the API trace buffers. This allows an HDLC application to generate trace events to aid debugging. These events are retreived with MgslGetTraceEvent in the same way as API generated events.

The EventType, DataLength, and EventData members must be filled in by the application. The API supplys the TimeStamp field. The maximum EventData length is defined by the HDLC_MAX_FRAME_SIZE constant.

Use the API defined EventType_UserMessage to have the API trace utility output the data as a printable string.

Use the API defined EventType_FormatRaw to have the API trace utility output the data as a block of hexadecimal bytes.

Application defined event types must not conflict with the API defined event types. Formatting of application defined event types must be added to the trace utility by the application supplier.

The application must decide when to add trace events using this API call. One approach is for the application to monitor the trace level using MgslGetTraceLevel(). For example, an application might conditionally generate EventType_UserMessage events to indicate error conditions when TraceLevel_Error is enabled.