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

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.