InstallComCallback

int InstallComCallback (int COMPort, int eventMask, int notifyCount, int eventCharacter, ComCallbackPtr callbackPtr, void *callbackData);

Purpose

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

Linux This function is not supported on Linux.

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 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.

Because LabWindows/CVI uses a Windows message internally to call the callback, 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.

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

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

.
.
.
/* Callback Function */
void ComCallback(int COMport, 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
COMPort integer A number that indicates the COM port on which to operate.

This number is paired with deviceName, which represents the COM port, during the OpenComConfig function call.

Default Value: 1—COM1
Valid Range: 1—1,000
eventMask integer 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 Received certain character. LWRS_RXFLAG Set when the event character is 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 integer 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 integer The character or byte value that triggers the LWRS_RXFLAG event.

Default Value: 0
Valid Range: 0 to 255
callbackPtr ComCallbackPtr Name of the user function that processes the COM port event callback.

This function (type CommCallbackPtr) takes the following form:

void CVICALLBACK CallbackFunctionName (int COMPort, int eventMask, void *callbackData);

The eventMask and callbackData parameters are values passed to InstallCommCallback. If you pass 0 for the callbackFunction or the eventMask parameter, the callback (if any) for the COM port is uninstalled.
callbackData void * A 4-byte 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

Name Type Description
result integer The result of this function call. This code is a negative value that specifies the type of error that occurred.