2.5.2.1 Hookswitch Devices
A phone device may have multiple hookswitch devices. The SPI defines three types of hookswitch devices for a phone: handset, speakerphone and headset. Each hookswitch device has a speaker and a mic component. Each hookswitch device is in one of four hookswitch modes:
- onhook - The hookswitch device is onhook, and both its mic and speaker are disabled.
- mic only - The hookswitch device is offhook, its mic is enabled and its speaker is mute.
- speaker only - The hookswitch device is offhook, its mic is mute and its speaker is enabled.
- mic and speaker - The hookswitch device is offhook, both mic and speaker are enabled.
The TAPI DLL can set and query hookswitch mode of an opened phone's hookswitch devices. To mute/unmute the mic or speaker component of a hookswitch device, the operation TSPI_phoneSetHookSwitch is used with the appropriate hookswitch mode.
TSPI_phoneSetHookSwitch
Sets the hookswitch mode of one or more of the hookswitch devices of an open phone device.
TSPI_phoneGetHookSwitch
Queries the hookswitch mode of a hookswitch device of an open phone device.
When the mode of a phone's hookswitch device is changed manually, for example by lifting the handset from its cradle, a PHONE_STATUS message is sent to the TAPI DLL's callback to notify the TAPI DLL about the state change. Parameters to this message provide an indication of the change.
The speaker component of a hookswitch device can be volume controlled. Note that volume setting is different from mute in that muting a speaker and later unmuting it will preserve the volume setting of the speaker.
TSPI_phoneSetVolume
Sets the volume of a hookswitch device's speaker of an open phone device.
TSPI_phoneGetVolume
Returns the volume setting of a hookswitch device's speaker of an open phone device.
The mic component of a hookswitch device can be gain controlled. Note that gain setting is different from mute in that muting a mic and later unmuting it will preserve the gain setting of the mic.
TSPI_phoneSetGain
Sets the gain of a hookswitch device's mic of an open phone device.
TSPI_phoneGetGain
Returns the gain setting of a hookswitch device's mic of an opened phone.
When the volume or gain of a phone's hookswitch device is changed, a PHONE_STATUS message is sent to the TAPI DLL's callback to notify the TAPI DLL about the state change. Parameters to this message provide an indication of the change.