Completion and Error handling

While completion handling in ActiveAG generally follows a pretty standard approach, it has features that are somewhat specific to telephony development. Telephony events are often regarded differently in different applications. For example, one application might consider a hang-up while collecting touch-tones as a fatal error but this might simply be a matter of interest in a different application. In short, what should be called an error in ActiveAG isn’t as clear-cut as the “no more items in the listbox” type of error seen in other ActiveX controls.

Because of this uncertainty, ActiveAG exposes the CompletionCode property. This property allows your application to make its own decisions about how to respond to different telephony conditions. The CompletionCode property contains values that are valid after:

a synchronous method completes and no exception was thrown or

an asynchronous method completes and no error event was fired.

The values that can be contained in the CompletionCode property are described in the ActiveAG constants topic. Also, see the CompletionCode property topic.

ActiveAG has two other ways of communicating completion status to your program. One of these is the Error event. This event will be fired to your program when an error occurs during an asynchronous method. The Error event sends your program a status constant and some descriptive text.

The second way for ActiveAG to communicate completion status is by throwing an exception. Exceptions are thrown if an error occurs during a synchronous method. For example, if your program calls the PlayVoice method before calling the OpenLine method, an exception will be thrown with the code AagErrLineNotOpen.

The values that can be thrown as exceptions, or that can be contained in the Error event, are described in the ActiveAG Status codes topic.

You should note, though, that there are some conditions that ActiveAG always considers errors:

Calling any method (other than OpenLine) when the line isn’t open. If your application attempts this, an exception will be thrown – or an error event fired – with the code AagErrLineNotOpen.

Calling any method before an earlier method call completes. While this problem is typically encountered when using asynchronous methods, it is also an error if you call a synchronous method while an asynchronous method is active. If your application calls a method while a previous method is still active, an exception will be thrown – or an error event fired – with the code AagErrFunctionActive.

Any method that requires a connected call (PlayVoice for example) will regard it as an error if there is no call connected. Conversely, any method that requires that a call not be connected (e.g., PlaceCall) will report an error if a call is connected when the method is invoked.

Invoking methods that are not supported by the version of ActiveAG installed on your system will cause an error to be thrown or fired. This will be the case, for example, when your program calls any of the FAX methods but NaturalFax wasn’t installed on your system when ActiveAG was installed. (See the Installation Notes topic.) This condition will cause an exception will be thrown – or an error event fired – with the code AagErrMethodNotAvail.

It is crucial that your programs be prepared to handle the many different types of error and completion condittions that can occur. This is particularly important when you need help with using ActiveAG. The more information you have about an error – and the circumstances it occurred under – the faster and simpler it will be to resolve your problems.