LINE_REMOVE (TSPI)

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This message notifies TAPI that an existing line device has been or is about to be removed from the system.

Syntax

LINE_REMOVE
    dwDevice = (DWORD) 0;
    dwCallbackInstance = (DWORD) 0;
    dwParam1 = (DWORD) dwDeviceID;
    dwParam2 = (DWORD) 0;
    dwParam3 = (DWORD) 0;

Parameters

• dwDevice
  Reserved; set to zero.

• dwCallbackInstance
  Reserved; set to zero.

• dwParam1
  Specifies the identifier of the line device that was removed.

• dwParam2
  Reserved; set to zero.

• dwParam3
  Reserved; set to zero.

Remarks

A service provider sends a LINE_REMOVE message to TAPI when it desires to disable an existing line device. This can occur when the removal of the device from the system (in a permanent way) is detected by Plug and Play or through a control panel or other user interface. It should not be used when a device is temporarily disconnected, such as if the device is a PCMCIA card that is extracted (use LINEDEVSTATE_DISCONNECTED or _OUTOFSERVICE in this situation).

When the message is received, TAPI closes the line device (if it is not already closed) by calling TSPI_lineClose, and sends LINE_CLOSE to all applications that have the line open; if any calls are active, TSPI_lineCloseCall is called on each of them prior to TSPI_lineClose. After processing the message, TAPI does not call the service provider referencing the removed device's dwDeviceID. TAPI returns LINEERR_NODEVICE to any application that attempts to reference the removed dwDeviceID.

After TSPI_providerShutdown has been called, the service provider can renumber its devices to remove any numbering gaps left by the device removal, so that when TSPI_providerEnumDevices is subsequently called, installed devices are contiguously numbered. The service provider should not reuse the dwPermanentLineID that had been assigned to the device, for as long as possible.

The LINE_REMOVE mechanism is intended to be used only if devices are removed while the service provider is active (for example, between TSPI_providerInit and TSPI_providerShutdown).

This message is sent to TAPI's LINEEVENT callback entry point. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_lineOpen function; the LINE_REMOVE message can be sent to the LINEEVENT callback function given to any open line or at startup.

Backward Compatibility

Older service providers are not expected to send this message. If they do, the message is treated in the same manner as described earlier for new service providers.

Requirements

See Also

Reference

LINEEVENT
TSPI_lineClose
TSPI_lineCloseCall
TSPI_lineOpen
TSPI_providerEnumDevices
TSPI_providerInit
TSPI_providerShutdown