Technical Reference > CtAPI Functions > Function Reference > ctListEvent


Returns the elements in the list which have changed state since they were last read using the ctListRead() function. You need to have created the list with CT_LIST_EVENT mode in the ctListNew() function.


ctListEvent(hCTAPI, dwMode)


Type: Handle
Input/output: Input
Description: The handle to the CTAPI as returned from ctListNew().


Type: Dword
Input/output: Input
Description: The mode of the list event. You need to use the same mode for each call to ctListEvent() until NULL is returned before changing mode. The following modes are supported:

CT_LIST_EVENT_NEW - Gets notifications when tags are added to the list. When this mode is used, you will get an event message when new tags added to the list.

CT_LIST_EVENT_STATUS - Gets notifications for status changes. Tags will change status when the I/O Device goes offline. When this mode is used, you will get a notification when the tag goes into #COM and another one when it goes out of #COM. You can verify that the tag is in #COM when an error is returned from ctListData() for that tag.

Return Value

If the function succeeds, the return value specifies a handle to a tag which has changed state since the last time ctListRead was called. If the function does not succeed or there are no changes, the return value is NULL. To get extended error information, call GetLastError().

Related Functions

ctListAdd, ctListDelete, ctListRead, ctListWrite, ctListData, ctListItem


HANDLE	 hList; HANDLE	 hTag[100];
hList = ctListNew(hCTAPI, CT_LIST_EVENT);
hTagArray[0] = ctListAdd(hList, "TagOne");
hTagArry[1] = ctListAdd(hList, "TagTwo");
and so on...
while (TRUE) {
ctListRead(hList, NULL);
hTag = ctListEvent(hList, 0);
while (hTag != NULL) {
// hTag has changed state, do whatever you need
hTag = ctListEvent(hList, 0);