Share via

PHONE_REMOVE (TSPI) (Compact 2013)

  • Article

3/26/2014

This message notifies TAPI that a phone device has been or is about to be removed from the system.

Syntax

PHONE_REMOVE
    hDevice = (DWORD) 0;
    dwCallbackInstance = (DWORD) 0;
    dwParam1 = (DWORD) hDeviceID;
    dwParam2 = (DWORD) 0;
    dwParam3 = (DWORD) 0;

Parameters

  • hDevice
    Reserved. Set to zero.
  • dwCallbackInstance
    Reserved. Set to zero.
  • dwParam1
    Identifier of the phone device that was removed.
  • dwParam2
    Reserved. Set to zero.
  • dwParam3
    Reserved. Set to zero.

Remarks

A service provider sends a PHONE_REMOVE message to TAPI to disable an existing phone 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 (use PHONESTATE_DISCONNECTED in this situation).

When the message is received, TAPI closes the phone device (if it is not already closed) by calling TSPI_phoneClose, and sends PHONE_CLOSE to all applications that have the phone open. After processing the message, TAPI does not call the service provider referencing the removed device's dwDeviceID. TAPI returns PHONEERR_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 dwPermanentPhoneID that had been assigned to the device, for as long as possible.

The PHONE_REMOVE mechanism is 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 the PHONEEVENT callback entry point in TAPI. The service provider receives a pointer to this callback in the TSPI_providerEnumDevices function and in each TSPI_phoneOpen function; the PHONE_REMOVE message can be sent to the PHONEEVENT callback function given to any open phone 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 above for new service providers.

Requirements

Header

tspi.h

See Also

Reference

TSPI Messages
PHONEEVENT
TSPI_phoneClose
TSPI_phoneOpen
TSPI_providerEnumDevices
TSPI_providerInit
TSPI_providerShutdown