Telephony operations complete either synchronously or asynchronously. These two models differ as follows. Synchronous functions execute the entire request before the caller's thread is allowed to return from the function call. Asynchronous functions return from the function call before the request has executed in its entirety. When the asynchronous request later completes, the application is informed by a reply message/event.

Synchronous TAPI functions

A synchronous TAPI function performs all of its processing in the caller's execution thread, returning the final result when it returns. In hbTapi Components, if a synchronous function fails, the error is indicated by an EhbTapiError exception including the error code and message.

Asynchronous TAPI functions

An asynchronous function performs part of its processing in the function call and the remainder of its processing in an independent execution thread after the function call has returned. When the function returns, either an error is reported by an EhbTapiError exception or a RequestID is returned, held in the ThbTapiLine.LastRequestID. When the operation is completed at a later time, the result is reported to the application by the ThbTapiLine.OnTapiReply event. The parameters of this event are the RequestID of the operation and the related ReplyCode. The ReplyCode has a value of zero if the function succeeds or an error code that uses one of the LINEERR_ constants.

Synchronous usage of asynchronous TAPI functions

hbTapi Components allows you to work either completely in an synchronous manner, which makes programming much easier, or to work in a TAPI like synchronous and asynchrounous manner. Set the ThbTapiLine.Options.SyncMode resp. ThbTapiPhone.Options.SyncMode property to True, if you want to work synchronous (default) or to False, if you want to handle the reply events on your own.

The following sample shows what happens while using the synchronous mode. When the Button1Click event is fired and then hbTapiLine1.MakeCall method is called, ThbTapiLine is waiting within this method to get the reply from TAPI. If an error occurs, TAPI events like call states fire. Because Application.ProcessMessages is called, these events will be triggered and hbTapiLine1CallState is triggered before MakeCall returned.

procedure TForm1.Button1Click(Sender: TObject);
begin
  hbTapiLine1.Options.SyncMode := True;
  hbTapiLine1.MakeCall('1234'); // returns when reply from TAPI has received
end;

procedure TForm1.hbTapiLine1CallState(Sender: ThbTapiLine; Call: ThbTapiCall;CallState: Cardinal);
begin
  // triggered before MakeCall returned
end;

Should i use the synchronous mode or is it better to choose the asynchronous mode?

The synchronous handling of asynchronous TAPI functions makes programming very easy and is good to use in desktop applications using one line, one phone device and a small amount of current calls. Remember that hbTapi calls Application.ProcessMessages while waiting on a TAPI reply. Because of that, events could fire before an asynchronous function returns and you have to avoid calling another asynchronous TAPI function before the first one has returned.

If you want to build an application that has to handle many line or phone devices or has to handle many calls at the same time, the asynchronouss model is the best choice. Functions will return directly without blocking. That brings the best performance and avoids confusion. hbTapi helps you using the asynchronous model. See ThbTapiLine.SetRequestNote and ThbTapiLine.GetRequestNote or there counterpart of ThbTapiPhone to read how to store information within an asynchronous TAPI request.

Remarks

ThbTapiPhone is handling synchronous and asynchrounous the same way as ThbTapiLine owns the same events and properties.

See Also

ThbTapiLine.Options.SyncMode and ReplyTimeout, ThbTapiLine.OnTapiReply, ThbTapiLine.OnTapiTimeout, ThbTapiLine.GetRequestNote, ThbTapiLine.SetRequestNote