A phone device may have multiple hookswitch devices. The API 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.
An application 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 phoneSetHookSwitch is used with the appropriate hookswitch mode.
phoneSetHookSwitch
Sets the hookswitch mode of one or more of the hookswitch devices of an open phone device.
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 application's callback to notify the application 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.
phoneSetVolume
Sets the volume of a hookswitch device's speaker of an open phone device.
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.
phoneSetGain
Sets the gain of a hookswitch device's mic of an open phone device.
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 application's callback to notify the application about the state change. Parameters to this message provide an indication of the change.
The API provides access to a phone's display. The display is modeled as an alphanumeric area with rows and columns. A phone's device capabilities indicate the size of a phone's display as number of rows and number of columns. Both these number are zero if the phone device does not have a display.
phoneSetDisplay
Writes information to the display of an open phone device.
phoneGetDisplay
Returns the current contents of a phone's display.
When the display of a phone device is changed, a PHONE_STATUS message is sent to the application's callback to notify the application about the state change. Parameters to this message provide an indication of the change.
A single phone may be able to ring with different ring modes. Given the wide variety of ring modes available, ring modes are identified via their ring mode number. A ring mode number ranges from zero to the number of available ring modes minus one.
phoneSetRing
Rings an open phone device according to a given ring mode.
phoneGetRing
Returns the current ring mode of an opened phone device.
When the ring mode of a phone device is changed, a PHONE_STATUS message is sent to the application's callback to notify the application about the state change. Parameters to this message provide an indication of the change.
The API models a phone's buttons and lamps as button/lamp pairs. A button with no lamp next to it, or a lamp with no button is specified using a "dummy" indicator for the lamp, resp. button. A button with multiple lamps is modeled by using multiple button/lamp pairs.
Information associated with a phone button can be set and retrieved. When a button is pressed, a PHONE_BUTTON message is sent to the application's callback. Parameters of this message are a handle to the phone device and the button/lamp ID of the button that was pressed. The keypad button '0' through '9', '*', and '#" are assigned fixed button/lamp IDs 0 through 11.
phoneSetButtonInfo
Sets the information associated with a button on a phone device.
phoneGetButtonInfo
Returns information associated with a button on a phone device.
PHONE_BUTTON
This message is sent to an app's callback when a button on the phone is pressed.
The information associated with a button does not carry any semantic meaning as far as the API is concerned. It is useful for (device specific) apps that understand the meaning of this information for a given phone device, or for display to the user (e.g., online help).
The lamps on a phone device can be lit in a variety of different lighting modes. Unlike ringing patterns, lamp modes are more uniform across phone sets of different vendors. A common set of lamp modes is defined by the API. A lamp identified by its lamp/button ID can be lit in a given lamp mode. A lamp can also be queried for its current lamp mode.
phoneSetLamp
Lights a lamp on a specified open phone device in a given lamp lighting mode
phoneGetLamp
Returns the current lamp mode of the specified lamp.
When a lamp of a phone device is changed, a PHONE_STATUS message is sent to the application's callback to notify the application about the state change. Parameters to this message provide an indication of the change.
Some phone sets support the notion of downloading or uploading data to or from the phone device. This may allow the phone set to be programmed in a variety of ways. The API models these phone sets as having one or more download and/or upload areas. Each area is identified by a number that ranges from zero to the number of data areas available on the phone minus one. Sizes of each area may vary. The format of the data itself is device specific.
phoneSetData
Downloads a buffer of data to a given data area in the phone device.
phoneGetData
Uploads the contents of a given data area in the phone device to a buffer.
When a data area of a phone device is changed, a PHONE_STATUS message is sent to the application's callback to notify the application about the state change. Parameters to this message provide an indication of the change.
Most of the Get and Set operations described earlier deal with one component of information only. The operation phoneGetStatus allow an application to obtain complete status information about a phone device. As mentioned, whenever a status item changes on the phone device, a PHONE_STATUS message is sent to the application's callback. The message parameters include a handle to the phone device and an indication of the status item that changed. An application can use phoneSetStatusMessages to select status changes for which it wants to be notified via the callback.
PHONE_STATUS
Is sent to the app's callback when a status item changes on a phone device.
phoneSetStatusMessages
Specifies the status changes for which the application wants to be notified.
phoneGetStatusMessages
Returns the status changes for which the application wants to be notified.
phoneGetStatus
Returns the complete status of an open phone device.