User`s guide
KwikNet Overview
K
A
DAK
21
KwikNet
Data Log Function
When message logging is enabled, the KwikNet message generation procedure
kn_dprintf() calls the data log function specified in your Network Parameter File. It is
the purpose of this function to record (and display or print) the message contained in the
KwikNet log buffer which it receives.
The Application OS Interface module KNSAMOS.C provided for use with KwikNet sample
programs includes a working example of a data log function called sam_record(). With
some modifications, this procedure may be suitable for use by your application. At the
very least, it will provide a good model for you to use.
The data log function must be declared as follows:
int sam_record(int attrib, char *bufp, int count);
The character buffer referenced by pointer bufp is a KwikNet log buffer. It contains a
'\0' terminated string. The length of the string in bytes is specified by parameter count.
Message strings are limited to the line length which you specified in your configuration.
The newline character '\n' is used as the end of line indication in all KwikNet messages.
Parameter attrib defines the message print attributes. This is the same parameter
presented to KwikNet's kn_dprintf() procedure. Your log function can decode the
message class to determine the device on which the message must be recorded or
displayed. It can also decide if any special action is required because of the message
severity or source.
Finally, your log function must assume responsibility for the KwikNet log buffer. If your
function accepts the log buffer, it must eventually release it by passing the pointer bufp
to KwikNet procedure kn_logbuffree(). In this case, your log function must return the
value 0 to KwikNet indicating your acceptance of the log buffer.
If your log function cannot accept the log buffer for some reason, it must return the value
-1 to KwikNet. In this case, KwikNet will free the log buffer.
In a multitasking system, the log function should add the log buffer to a message queue
for eventual recording (and printing or display) by a print task which services the
message queue. The examples provided for use with AMX and with the KwikNet Porting
Kit pass the log buffer to a print task which uses the
KwikNet message recording service
described in Chapter 1.7 to dispose of each message.
In a single threaded system, the log function should add the log buffer to a message
queue for eventual recording (and printing or display) by the App-Task. However, if
performance is not an issue, the log function can actually record the message and release
the log buffer itself. Care must be taken to ensure that such an action is not allowed to
occur while executing within the interrupt domain. The examples provided with the
KwikNet Porting Kit operate in the latter fashion, using the KwikNet message recording
service described in Chapter 1.7 to dispose of each message.