Using CT Access directly

ActiveAG provides a way for your program to use the CT Access SDK directly. While ActiveAG is very flexible and powerful, it does not expose every feature of the CT Access SDK. The properties below were provided for those times when your program needs features available in CT Access which haven’t been exposed in ActiveAG.

IMPORTANT NOTES:

ActiveAG methods should not be called while the worker thread is suspended.

This intent of this feature is to give your application the means to run small sections of “in line” CT Access code. This feature is not intended for use in building large parts of your application. If you find that your program requires a great deal of code to be written to the CT Access SDK, you may want to consider using that SDK directly instead of using ActiveAG.

If you plan to use this feature, please read this section carefully. Here are the steps to follow:

1) Suspend the worker thread:

ActiveAG is a multi-threaded control. Each time a line is opened (see the OpenLine method), a worker thread is created. This thread continually monitors the CT Access event queue in order to notify your application of events that occur on the telephone line.

Since CT Access uses an event-driven architecture, your program must suspend the worker thread when the program is using CT Access directly. In order to prevent contention between your program and the worker thread – that is, to make sure that they’re not both taking events from the CT Access event queue at the same time – your program must suspend the worker thread. Setting the Suspend property to TRUE does this. If you program fails to do this, the worker thread will remain active and will “steal” events from the queue. As a general rule, this causes programs to behave in undesirable ways.

2) Obtain the CT Access context handle:

CT Access identifies open lines using a context handle. In order for your program to make calls to CT Access functions directly, it must have this handle. ActiveAG stores the CT Access handle in the CTAhandle property. Before calling CT Access functions, your program should obtain this handle value by reading the property.

If your program needs to monitor the CT Access event queue directly, it can obtain an event object handle for the CT Access event queue by using the following function:

CTAQUEUEHD hCTAQueue;

CtaGetQueueHandle (hCTA, &hCTAQueue); // ‘hCTA’ is value of CTAhandle property

The CT Access handle is not volatile, so long as the line it is attached to remains open. That is, the handle will be valid until the CloseLine method is called. NOTE: Do not use CT Access functions directly to close a line that was opened by ActiveAG. Doing this will cause memory and other resource leaks in ActiveAG, resulting in unpredictable program behavior.

3) Make the desired CT Access calls:

Now that your program has suspended ActiveAG’s worker thread and obtained the CT Access handle, it is ready to make calls directly to CT Access functions. The CT Access SDK is documented in the CT Access Developer’s Manual (P.N. 6304-10B) and the CT Access Function Reference Manual (P.N. 6305-10). Both of these are available from Natural MicroSystems Corporation. (See Where to get support.)

Do not invoke ActiveAG methods while the worker thread is suspended.

4) Resume the worker thread:

This step is very important.. When your program has completed making calls, it should “resume” the worker thread by setting the Suspend property to FALSE. This causes the worker to resume monitoring the CT Access event queue. Because the worker thread also handles all asynchronous methods, resuming it also enables ActiveAG to process asynchronous methods again.