InstallComCallback

int InstallComCallback (int portNumber, int eventMask, int notifyCount, int eventCharacter, ComCallbackPtr callbackFunction, void *callbackData);

Purpose

Allows you to install a synchronous callback function for a particular COM port.

(Linux)  This function is not supported.

The callback function is called whenever any of the events specified in eventMask occur on the COM port and you allow the system to process events. The system can process events in the following situations:

• You call RunUserInterface and none of your callback functions is currently executing.
• You call GetUserEvent.
• You call ProcessSystemEvents.

You can install only one callback function for each COM port. Each call to this function for the same COM port supersedes the previous call.

To disable callbacks for a port, pass 0 for the eventMask and/or callbackFunction parameters.

The callback can get called when there are no bytes in the input queue, even though there were bytes at the time the message was posted. For example, calling ComRd multiple times in the callback can lead to this situation. For this reason, NI recommends that you always check the input queue size before performing any operation in the callback.

Note   The callback function can receive more than one event at once. The LWRS_RXCHAR event does not cause a separate callback for every byte received in the input queue. NI recommends using LWRS_RXFLAG or LWRS_RECEIVE events for input instead. Once the LWRS_RECEIVE event occurs, it does not occur again until the input queue falls below and then rises back above notifyCount bytes. The LWRS_RXFLAG event may not occur for each instance of the event character received in the input queue. One event may represent multiple instances, so the callback may need to read all available data. This is more likely at higher transmission rates and/or higher densities of event characters.

Calling CloseCom after a call to InstallComCallback automatically uninstalls the callback function. If you then call OpenCom and want to use the callback function, you must call InstallComCallback again.

Example Code

notifyCount = 50; /* Wait for at least 50 bytes in queue. */
eventChar = 10; /* Wait for LF. */
eventMask = LWRS_RXFLAG | LWRS_TXEMPTY | LWRS_RECEIVE;
InstallComCallback (portNumber, eventMask, notifyCount, eventChar, ComCallback, NULL);

.
.
.
/* Callback Function */
void ComCallback(int portNumber, int eventMask, void *callbackdata)
{

if (eventMask & LWRS_RXFLAG)

printf("Received specified character\n");

if (eventMask & LWRS_TXEMPTY)

printf("Transmit queue now empty\n");

if (eventMask & LWRS_RECEIVE)

printf("50 or more bytes in input queue\n");

}

Parameters

Input
Name	Type	Description
portNumber	int	A number that indicates the COM port on which to operate. This number maps to the COM port specified by deviceName in the call to OpenCom or OpenComConfig. The portNumber 1, for example, may not necessarily map to COM1. (Linux) The portNumber 1, for example, may not necessarily map to /dev/ttyS0. Valid Range: 1—1,000
eventMask	int	Events upon which the callback function is called. If you want to disable callbacks, pass 0. Specify the events using bits in eventMask, and you can specify multiple event bits. If any one of the events occur, the callback is called. The following table lists valid event bits. Bit Hex Value COM Port Event Constant Name Description 0 0x0001 Any character received. LWRS_RXCHAR Set when a character is received and placed in the input queue. 1 0x0002 Certain character in input queue. LWRS_RXFLAG Set when one or more instances of the event character are received and placed in the input queue. The event character is specified in eventCharacter. 2 0x0004 Transmit queue empty. LWRS_TXEMPTY Set when the last character in the output queue is sent. 3 0x0008 CTS changed state. LWRS_CTS Set when the CTS (clear-to-send) line changes state. 4 0x0010 DSR changed state. LWRS_DSR Set when the DSR (data-set-ready) line changes state. 5 0x0020 RLSD changed state. LWRS_RLSD Set when the RLSD (receive-line-signal-detect) line changes state. 6 0x0040 BREAK received. LWRS_BREAK Set when a break is detected on input. 7 0x0080 Line status error occurred. LWRS_ERR Set when a line-status error occurs. Line-status errors are CE_FRAME, CE_OVERRUN, and CE_RXPARITY. 8 0x0100 Ring signal detected. LWRS_RING Set to indicate that a ring indicator was detected. 15 0x8000 notifyCount bytes in input queue. LWRS_RECEIVE Set to detect when at least notifyCount bytes are in the input queue. Once this event has occurred, it does not trigger again until the input queue falls below and then rises back above notifyCount bytes.
notifyCount	int	Minimum number of bytes the input queue must contain before sending the LWRS_RECEIVE event to the callback function. Note   The LWRS_RECEIVE event does not trigger again until the input queue falls below and then rises back above notifyCount bytes. Default Value: 0 Valid Range: 0 to size of input queue
eventCharacter	int	The character or byte value that triggers the LWRS_RXFLAG event. Default Value: 0 Valid Range: 0 to 255
callbackFunction	ComCallbackPtr	Name of the user function that processes the COM port event callback. This function (type ComCallbackPtr) takes the following form: void CVICALLBACK CallbackFunctionName (int portNumber, int eventMask, void *callbackData); The eventMask and callbackData parameters are values passed to InstallComCallback. If you pass 0 for the callbackFunction or the eventMask parameter, the callback (if any) for the COM port is uninstalled.
callbackData	void *	A pointer-width value the library passes to the callback function. You can use callbackData as an integer value or as a pointer to a data object you want to access in the callback function. In this way, you do not have to declare the data object as a global variable.

Return Value

Additional Information

Library: RS-232 Library

Include file: rs232.h

LabWindows/CVI compatibility: LabWindows/CVI 4.0 and later