int InstallComCallback (int COMPort, int eventMask, int notifyCount, int eventCharacter, ComCallbackPtr callbackPtr, void *callbackData);
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.
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");
}
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.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||
notifyCount | integer | Minimum number of bytes the input queue must contain before sending the LWRS_RECEIVE event to the callback function.
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. |
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. |