NMS_GR303SetTrace

Configures NMS GR303 library tracing.

Prototype

NMS_GR303_RESULT_T NMS_GR303SetTrace ( NMS_GR303_TRACEMASK_T trace_mask, NMS_GR303_TRACE_CALLBACK_T user_trace_callback, void *user_trace_buffer, DWORD user_trace_buffersize, char *user_file_name)

Argument	Description
trace_mask	Trace mask controlling the information level reported to the application. Refer to the Details section for a list of trace masks that applications can specify.
user_trace_callback	Pointer to an application-defined callback function. Set this value to NULL if the library is saving tracing information to a file. The library uses this callback function when it has a trace buffer to pass to the application. The callback function is defined in the following way: typedef void (NMS_GR303_TRACE_CALLBACK_T) (char tracebuffer, DWORD datasize); See the Details section for field descriptions.
user_trace_buffer	Pointer to the application-allocated memory that the NMS GR303 library uses to pass trace data to the application.
user_trace_buffersize	Size of the application-allocated buffer specified by user_trace_buffer. The minimum requirement for the user_trace_buffersize is set by NMS_GR303_MIN_TRACE_BUF_SIZE.
user_file_name	Pointer to the name of the log file if the NMS GR3030 library is logging trace information in a file. This value specifies the size of the trace blocks that the library uses to write to the file.

Return values

Return value	Description
NMSGR303_SUCCESS
NMSGR303_INTERNAL_FAILURE	Failed to set up tracing.
NMSGR303_INVALID_PARMS	Invalid function arguments.
NMSGR303_NOT_INITIALIZED	NMS GR303 library was not initialized with NMS_GR303Initialize.

Details

Applications can use NMS_GR303SetTrace to configure the NMS GR303 library to return trace information through a defined callback function, or to log trace information into a specified file.

Applications can specify the following trace masks:

Trace mask	Description
NMSGR303_TRACEMASK_NONE	No tracing.
NMSGR303_TRACEMASK_FUNCTIONS	Log function calls and returns.
NMSGR303_TRACEMASK_ERRORS	Log HDLC transmit/receive errors.
NMSGR303_TRACEMASK_RX_BUF	Log received HDLC frames.
NMSGR303_TRACEMASK_TX_BUF	Log transmitted HDLC frames.
NMSGR303_TRACEMASK_HDLCERR	Log HDLC transmit/receive errors.

When defining a callback function, the application specifies the following information:

Field	Description
tracebuffer	A pointer to the beginning of the trace information inside the application-allocated memory.
datasize	The size of the data returned in the tracebuffer.

To initiate the callback mode, the application must pass a callback function pointer user_trace_callback, allocate a buffer, and specify the buffer address (tracebuffer) and size (user_trace_buffersize) as NMS_GR303SetTrace arguments.

If the GR303 library receives a user_trace_callback value (and this value is not NULL), the library sets up the callback tracing mode and ignores the user_file_name value.

Note: After the user_trace_callback function returns, the library assumes that the application is finished using the data inside the tracebuffer, and that the library can reuse the memory. For this reason, applications must release user_trace_callback buffers as quickly as possible.

If the application decides to log trace information into a file, the application must set user_trace_callback and tracebuffer to NULL. If the application wants the library to perform internal buffering before logging tracing information in the file, the application must set the user_trace_buffersize to the trace block size. user_trace_buffersize specifies the size of an application-allocated buffer reserved for trace messages returned to the application. The size of user_trace_buffersize must either be greater than the value specified by the NMS_GR303_MIN_TRACE_BUFFER_SIZE parameter, equal to NMS_GR303_MIN_TRACE_BUFFER_SIZE, or zero.

If the application sets user_trace_buffersize to zero, the NMS GR303 library sends each trace message to the application immediately. However, even when the NMS GR303 library sends individual trace messages, the application must still reserve an amount of memory greater than or equal to the size of NMS_GR303_MIN_TRACE_BUFFER_SIZE.

The NMS GR303 library can return the following tracing messages with the NMSGR303_INTERNAL_FAILURE error:

Message	Hex	Description
PHYERR_INVALID_DEVICE	0x01	Board failed to define the HDLC or framer device type.
PHYERR_DEVICE_USED	0x02	Specified HDLC channel already exists in the NMS GR303 library.
PHYERR_INVALID_HANDLE	0x03	Invalid HDLC or framer handle passed. The board does not have an HDLC device configured with this handle.
PHYERR_BOARD_MESSAGE_FAILED	0x04	Failed to send a message to the board. Internal communication problem.
PHYERR_BOARD_RESPONSE_TIMEOUT	0x05	The board failed to respond to a message within a specified time interval.
PHYERR_INTERNAL_FAILURE	0x06	Failed to initialize or exit the NMS GR303 library.
PHYERR_INVALID_PARMS	0x07	Invalid input parameters.
PHYERR_NO_MEMORY	0x08	Failed to allocate memory.
PHYERR_ALREADY_INITIALIZED	0x09	NMS GR303 library has already been initialized.
PHYERR_NO_BUFFER_DEFINED	0x0A	No buffer provided for requested data.
PHYERR_OUTOFRESOURCE	0x0B	Cannot create more HDLC instances on the board.

Example

void  SetTrace( void )
{
    NMS_GR303_RESULT_T     NmsResult;
    NMS_GR303_TRACEMASK_T TraceMask;
    BYTE                   FileName[64];
    char                   Selection;

    printf("NMS_GR303SetTrace:\n");

    prompthex("Enter TraceMask", &TraceMask);

    TraceBufferSize = NMS_GR303_MIN_TRACE_BUF_SIZE;

    /* Allocate buffer size not less than required minimum */
    g_pTraceBuffer = calloc(

    TraceBufferSize, 1);
    /* Set trace to a file */
    strcpy( FileName, "nms_gr303.log" );

    NmsResult =  NMS_GR303SetTrace(  TraceMask,
                                     NULL,
                                     NULL,
                                     TraceBufferSize,
                                     FileName);
    printf ("NMS_GR303SetTrace: Result=%s\n",PRINT_RESULT(NmsResult));
}