Asynchronous Event Handling Functions

The asynchronous event module is designed to report events that occur on an adapter to an interested application. More...

Enumerations
enum	ASYNC_EVENT_SOURCES { HPI_ASYNC_EVENT_GPIO = 1, HPI_ASYNC_EVENT_SILENCE = 2, HPI_ASYNC_EVENT_TONE = 3 }
	Async Event sources. More...
Functions
HPI_ERR	HPI_AsyncEventOpen (const HPI_HSUBSYS *phSubSys, HW16 wAdapterIndex, HPI_HASYNC *phAsync)
	Open an ASync object.
HPI_ERR	HPI_AsyncEventClose (const HPI_HSUBSYS *phSubSys, HPI_HASYNC hAsync)
	Closes an ASync object.
HPI_ERR	HPI_AsyncEventWait (const HPI_HSUBSYS *phSubSys, HPI_HASYNC hAsync, HW16 wMaximumEvents, struct hpi_async_event *pEvents, HW16 *pwNumberReturned)
	Waits for a asynchronous events.
HPI_ERR	HPI_AsyncEventGetCount (const HPI_HSUBSYS *phSubSys, HPI_HASYNC hAsync, HW16 *pwCount)
	Returns the number of asynchronous events waiting.
HPI_ERR	HPI_AsyncEventGet (const HPI_HSUBSYS *phSubSys, HPI_HASYNC hAsync, HW16 wMaximumEvents, struct hpi_async_event *pEvents, HW16 *pwNumberReturned)
	Returns single or many asynchronous events.

---

Detailed Description

The asynchronous event module is designed to report events that occur on an adapter to an interested application.

An Async object can be used to reciev notifications for both GPIO and other signal detection events. A typical coding sequence would look something like:

// The below code represents the bits that would go in an application.

        ...
        // application startup section
        HPI_AsyncEventOpen(pSS,0,&hAsync);
        CreateThread(ThreadAsync);
        ...

        ...
        // application shutdown
        HPI_AsyncEventOpen(pSS,hAsync);
        ...

#define MAX_EVENTS 10
void ThreadAsync()
{
        int ExitSignalled=0;
        HW16 wError;
        tHPIAsyncEvent e[MAX_EVENTS]

        while(!ExitSignalled)
        {
                wError = HPI_ERR HPI_AsyncEventWait( pSS, hAsync,
                        MAX_EVENTS,
                        &e[0],
                        &wEvents);

                 if(wError==HPI_ASYNC_TERMINATE_WAIT)
                        ExitSignalled=1;
                 else
                 {
                         if(!wError)
                                for(i=0;i<wEvents;i++)
                                        CallCodeToProcessEvent(e[i]);
                 }

        }
}

---

Enumeration Type Documentation

enum ASYNC_EVENT_SOURCES

Async Event sources.

Enumerator:

HPI_ASYNC_EVENT_GPIO	GPIO event.
HPI_ASYNC_EVENT_SILENCE	Silence event detected.
HPI_ASYNC_EVENT_TONE	tone event detected.

---

Function Documentation

HPI_ERR HPI_AsyncEventOpen	(	const HPI_HSUBSYS *	phSubSys,
		HW16	wAdapterIndex,
		HPI_HASYNC *	phAsync
	)

Open an ASync object.

Opens a GPIO object and returns a handle to the same.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Subsystem handle.
wAdapterIndex	The adapter index to open the Async object.
phAsync	Returned handle of an ASync object.

HPI_ERR HPI_AsyncEventClose	(	const HPI_HSUBSYS *	phSubSys,
		HPI_HASYNC	hAsync
	)

Closes an ASync object.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Subsystem handle.
hAsync	Handle of the Async object to close.

HPI_ERR HPI_AsyncEventWait	(	const HPI_HSUBSYS *	phSubSys,
		HPI_HASYNC	hAsync,
		HW16	wMaximumEvents,
		struct hpi_async_event *	pEvents,
		HW16 *	pwNumberReturned
	)

Waits for a asynchronous events.

This call waits for any async event. The calling thread is suspended until an ASync event is detected. After the async event is detected the call completes and returns information about the event(s) that occured.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Subsystem handle.
hAsync	Handle of an Async object.
wMaximumEvents	Maximum number of events matches size of array passed in pEvents.
pEvents	Events are returned here.
pwNumberReturned	Number events returned.

HPI_ERR HPI_AsyncEventGetCount	(	const HPI_HSUBSYS *	phSubSys,
		HPI_HASYNC	hAsync,
		HW16 *	pwCount
	)

Returns the number of asynchronous events waiting.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Subsystem handle.
hAsync	Handle of an Async object.
pwCount	Returned number of events waiting.

HPI_ERR HPI_AsyncEventGet	(	const HPI_HSUBSYS *	phSubSys,
		HPI_HASYNC	hAsync,
		HW16	wMaximumEvents,
		struct hpi_async_event *	pEvents,
		HW16 *	pwNumberReturned
	)

Returns single or many asynchronous events.

This call will read any waiting events from the asynchronous event queue and return a description of the event. It is non-blocking.

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Parameters:

phSubSys	Subsystem handle.
hAsync	Handle of an Async object.
wMaximumEvents	Maximum number of events matches size of array passed in pEvents.
pEvents	Events are returned here.
pwNumberReturned	Number events returned.