Using the Callback Function

Article
06/30/2006

To receive status notices, the application can implement the lineCallbackFunc function to establish a way to communicate with TAPI 2.0. The callback function processes messages or notifications that TAPI sends to the application. TAPI uses the callback function to notify the application of changes in the status of calls, lines, and telephone devices.

The LINE_CALLSTATE message dispatches various pieces of information to the application, such as that the call is receiving a dial tone from the hookswitch or the call is receiving a busy signal, as well as other data that is sent by the network. A telephone call passes through different stages during a session, and the application can display the result from the LINE_CALLSTATE message in a dialog box.

The following code example shows how to process LINE_CALLSTATE messages in the lineCallbackFunc function. With minor modifications, you can use the same code with the lineGetMessage function, because the fields in the LINEMESSAGE structure are the same as the callback function parameters. Calling lineGetMessage is more efficient than using a callback function, because the thread that is waiting in lineGetMessage gets notified immediately when a new message is available.

LPTSTR lpszStatus;

case LINE_CALLSTATE:

  // If the CALLSTATE does not apply to the call in progress, return.
  if (g_hCall != (HCALL) hDevice)
    return;

  // dwParam1 is the specific CALLSTATE change occurring
  switch (dwParam1) 
  {
    case LINECALLSTATE_DIALTONE:
      lpszStatus = TEXT("Dial tone");
      break;

    case LINECALLSTATE_DIALING:
      lpszStatus = TEXT("Dialing");
      break;

    case LINECALLSTATE_PROCEEDING:
      lpszStatus = TEXT("Dialing has completed and the call ")
                   TEXT("is proceeding");
      break;

    case LINECALLSTATE_RINGBACK:
      lpszStatus = TEXT("Ring back");
      break;

    case LINECALLSTATE_CONNECTED:
      lpszStatus = TEXT("Connected");
      break;
    .
    .
    .

    case LINECALLSTATE_DISCONNECTED:
    {
      LPTSTR lpszDisconnected;

      switch (dwParam2)
      {
        case LINEDISCONNECTMODE_NORMAL:
          lpszDisconnected = TEXT("Remote party disconnected");
          break;

        case LINEDISCONNECTMODE_UNKNOWN:
          lpszDisconnected = TEXT("Disconnected: Unknown reason");
          break;

        case LINEDISCONNECTMODE_REJECT:
          lpszDisconnected = TEXT("Remote party rejected call");
          break;
        .
        .
        .

        default:
          lpszDisconnected = TEXT("Disconnected: Unknown reason");
          break;
      }

      ErrorBox (lpszDisconnected);
      // Insert code here to close the current open line device.
      // ...
      break;
    } 
  }
  break;

A more efficient notification mechanism is available through the lineInitializeEx and lineGetMessage functions. When the LINEINITIALIZEEXOPTION_USEEVENT constant is specified in lineInitializeEx, TAPI creates an event that gets signaled whenever a message is available. The application can call lineGetMessage to retrieve the next message. The application can wait for the event to be signaled, or it can specify a time-out and have lineGetMessage wait for the next message.

Share via

Using the Callback Function

See Also

Additional resources