Events

The Aspen library provides a means for applications to receive notification of various events. Some events originate in the Server, while others are generated locally by the Aspen library.

Event notifications are obtained by calling the AspenEvent() function. If an event notice is pending, the AspenEvent() function will return the type of the event notice and a pointer to a structure that contains notice-specific information.

On single-threaded platforms, Aspen applications should periodically check for received events using the AspenEvent() function.

Note that in a single-threaded application, the Aspen Event Notification System is driven by repeated calls to the AspenPoll() function.

On multi-threaded platforms, Aspen supports the usage of an event semaphore that is signaled whenever an event notice is pending. The semaphore itself must be allocated by the application using the operating system's native method and then passed to the Aspen library when AspenInit() is called. Usage of an event semaphore allows Aspen applications to dedicate a thread to servicing asynchronous event notifications.

AspenInit() is not the only way to initiate the event notification system. You can also start receiving events by calling AspenEnableEvents().

Of course, the semaphore method does not need to be used; passing a NULL argument to AspenInit() in place of a semaphore handle will disable semaphore signaling of events. The application can then use the single-threaded platform approach of polling for events with the AspenEvent() function.

On Windows 95, Windows NT, and Windows 2000 (Win32), the application must create the event semaphore with theWin32 CreateSemaphore() or the Win32 OpenSemaphore() function. Event-handling threads can block waiting for the semaphore to be signaled with the Win32 WaitForSingleObject() function.

The event notification structures received from the AspenEvent() function are dynamically allocated by the event system and must be freed by the application after they have been used by calling AspenFreeMemory().

Memory Management

Frequently, when the Aspen Server provides information to your application, the information is contained in a structure for which the memory resources were dynamically allocated. When your application has finished with the structure and the information it contains, the application must free the associated memory resource. Structures that fall under this category are identified throughout this document using the “recycle” symbol: . Memory is freed by the application calling the AspenFreeMemory().

Note: free()memory may not be used because the memory was allocated by an Aspen memory allocation function. A memory leak will occur if AspenFreeMemory() is not used.