An event can contain a buffer of data or a scalar. If it contains a buffer, you must allocate memory to store the contents of the buffer. Memory management is typically done in one of the following ways:
The application has pre-allocated the memory and ctaWaitEvent fills in that memory with the data. In this case, the application is responsible for both allocating and freeing its memory. An example is the use of adiCollectDigits.
The application has not pre-allocated the memory. Natural Access or one of the Natural Access services allocated the memory on behalf of the application. The CTA_INTERNAL_BUFFER bit is set in the size field. In this case, the application is responsible for freeing the memory that it did not allocate.
Complete the following steps to process events and release allocated memory:
|
Step |
Action |
|
1 |
Call ctaWaitEvent. |
|
2 |
On successful return, check to see if the CTA_INTERNAL_BUFFER bit is set. |
|
3 |
If this bit is set, clear the bit before processing the event (so that the size field specifies the size of the buffer). |
|
4 |
Upon the completion of the event processing, call ctaFreeBuffer if the CTA_INTERNAL_BUFFER bit was originally set. |
Note: Applications must call ctaWaitEvent in a timely manner to ensure prompt processing of time-critical events. Refer to Using wait objects.
To share a context, each client application must create at least one event queue. Applications specify the event queue handle (ctaqueuehd) when attaching to an existing context.
Any application that attaches to the context immediately receives events for all of the services available on the context (whether or not the application uses functions from these services).
The following illustration shows two applications sharing a context that includes VCE, NFX, and ADI service instances. Each application uses a separate event queue for the events it receives. The illustration shows that, even though Application 2 invokes commands only from the NFX service, it receives events for all services available on the context.
Note: When an application attaches to a context created in declared access mode, the application receives events only for services that it explicitly opens.
ctaSetEventSources specifies the services from which applications receive events. Applications attached to contexts created in common access mode can invoke ctaSetEventSources to limit the types of events they receive.
The following illustration shows a fax application attaching to a shared context where the VCE, NFX, and ADI services are open. Initially, the fax application receives events from all three open services. However, by invoking ctaSetEventSources (with the appropriate ctahd) and specifying the NFX service, the application effectively screens out all events except those for the NFX service.
The following illustration shows an example of three applications screening events for a context that they all share (a context created in common access mode). The call control application receives events for the ADI service, as well as events for any other services opened by the two other applications. A voice play and record application uses ctaSetEventSources to screen NFX events so that it receives only ADI and VCE service events. A fax application uses ctaSetEventSources to screen all events except those from the NFX service.
This example illustrates that applications can receive any of the following types of events:
All events from opened services, even from services that it did not explicitly open
Only those events from inherited services and services that it explicitly opened
Only those events that it explicitly opened
Use ctaGetEventSources to retrieve a list of services from which a specified context receives events.
Note: In common access mode, you can receive events from unexpected services between the time you invoke ctaAttachContext and ctaSetEventSources. Code your event handler to deal with these unwanted events.