78 Global Call API for HMP on Windows Programming Guide — August 2006
Application Development Guidelines
threads. Asynchronous programming uses system resources more efficiently because it
handles multiple channels in a single thread. Asynchronous models let you program complex
applications easily, and achieve a high level of resource management in your application by
combining multiple voice channels in a single thread. This streamlined code reduces the
system overhead required for inter process communication and simplifies the coordination of
events from many devices.
•In Windows environments, when calling the gc_GetMetaEventEx() function from multiple
threads, ensure that your application uses unique thread-related METAEVENT data structures
or ensure that the METAEVENT data structure is not written to simultaneously.
5.2 Tips for Programming Drop and Insert Applications
Note: This section applies to E1, T1 and ISDN technologies only.
To the Global Call application, signaling is made available to the application as follows:
•Signaling information is passed to the Global Call application in the form of call control
events; for example, line answer is passed as a GCEV_ANSWERED event.
•Signaling, such as line busy, is available to the application as an EGC_BUSY error code or a
GCRV_BUSY result value; line no answer is available as an EGC_NOANSWER error code or
GCRV_NOANSWER result value.
•Signaling such as a protocol error, an alerting event, a fast busy, an undefined telephone
number, or network congestion are all returned to the application as an EGC_BUSY error code
or a GCRV_BUSY result value.
•Protocols without acknowledgement, for example, non-backward CAS signaling protocols,
generate a GCEV_DISCONNECTED event with an EGC_BUSY error code or a
GCRV_BUSY result value when timeout or protocol errors occur during dialing.
For a drop and insert application in which the calling party needs to be notified of the exact status
of the called party’s line, the following approach may be used:
•Upon receipt of an incoming call from a calling party, issue a gc_MakeCall() function on the
outbound line to the called party.
•After dialing completes on the outbound line, the application should drop the dialing resource,
turn off call progress, and connect the inbound line to the outbound line so that the calling
party can hear the tones returned on the outbound line. These tones provide positive feedback
to the calling party as to the status of the called party’s line.
•If the status of the called party’s line is such that the call cannot be completed, the calling party
hangs up and the application can then drop the call and release the resources used. Otherwise,
when the call is answered, a GCEV_CONNECTED event will be received.
When call progress is being used, after dialing completes, the call progress software looks for
ringback or voice on the outbound line. When ringback is detected, a GCEV_ALERTING event is
generated. When voice is detected, a GCEV_ANSWERED event is generated. An unacceptable
amount of time may lapse before either of these events is generated while the calling party is
waiting for a response that indicates the status of the call. Thus, for drop and insert applications,
call progress should be disabled as soon as dialing completes and the inbound and outbound lines