Processing Assisted Telephony Requests

The process with which requests are delivered and serviced is as follows:

  1. When TAPI receives an Assisted Telephony request, it checks for a request recipient, that is, an application currently registered to process that type of request. If there is a request recipient, the request is queued, and the highest-priority application that has registered for that request's service is sent a LINE_REQUEST message. The message notifies the request recipient that a new request has arrived, and it carries an indication of the request's mode.
  2. If TAPI cannot find a currently running application to process such a request, it tries to launch an application that has been registered as capable of doing so. This registration information is recorded in HandoffPriorities in the registry. TAPI tries to launch applications in the order in which they are listed in the HandoffPriorities section. (See the following step.)

    If no application is currently registered, TAPI examines the list of request-processing applications on the associated entry in HandoffPriorities. If the associated line is missing from the file, if there are no applications listed on it, or if none of the applications in the list can be launched, the request is rejected with the error TAPIERR_NOREQUESTRECIPIENT.

    When a request recipient is launched (whether or not it has been launched by TAPI) it is its duty to call lineRegisterRequestRecipient during the startup process and register itself as a request recipient.

  3. If one or more applications are listed in the entry, TAPI begins with the first listed application (highest priority), and attempts to launch it using the CreateProcess function. If the attempt to launch the application fails, TAPI attempts to launch the next application in the list. When any application launches successfully, TAPI simply queues the request and returns a success indication to the application even though the request hasn't yet been signaled to the request recipient.

    After the request recipient application is launched, it calls lineRegisterRequestRecipient, which causes a LINE_REQUEST message to be sent, signaling that the request is queued. If for some reason the launched application never registers, the request remains queued and remains in the queue indefinitely until an application registers for that type of request.

  4. If TAPI finds such a registered application already running or successfully launches one, it queues the request, sending a LINE_REQUEST message to the server application, and returns a success indication for the function call to the Assisted Telephony application. This success message states only that the request has been accepted and queued, not that it has been successfully executed.

When the server application is ready to process a request, it calls the lineGetRequest function. This lets it receive any information it needs, such as an address to dial. It then processes the request, using the TAPI functions (such as lineMakeCall and lineDrop) that would otherwise be used to place the call. Invoking lineGetRequest removes the request from TAPI, and the request parameters are copied in an application-allocated request buffer. The size and interpretation of the contents of the buffer depend on the request mode.

The server must ensure that it uses the correct parameters when executing requests. When doing so, these steps are followed:

  1. The request recipient first receives a LINE_REQUEST message informing it that requests can exist for it in the request queue. This tells the application to call lineGetRequest and keep calling it until the queue is drained (if the request is for making a new call), or to drop an existing call. This message does not contain the parameters for the request, except in the case of a request to drop an existing call.
  2. If the request is to make a new call, the Assisted Telephony server uses the lineGetRequest function to retrieve the full request, which includes the request's parameters. The server now has all the information it needs, such as the number to dial or the identification of the maker of the request. First, however, the server must allocate the memory needed to store this information.
  3. Finally, the server executes the request by invoking the appropriate TAPI function or set of functions.

If TAPI cannot launch an application capable of serving as a request recipient, the Assisted Telephony call fails and returns the error TAPIERR_NOREQUESTRECIPIENT.