LINEDEVCAPS
The LINEDEVCAPS structure describes the capabilities of a line device.
typedef struct linedevcaps_tag {
DWORD dwTotalSize;
DWORD dwNeededSize;
DWORD dwUsedSize;
DWORD dwProviderInfoSize;
DWORD dwProviderInfoOffset;
DWORD dwSwitchInfoSize;
DWORD dwSwitchInfoOffset;
DWORD dwPermanentLineID;
DWORD dwLineNameSize;
DWORD dwLineNameOffset;
DWORD dwStringFormat;
DWORD dwAddressModes;
DWORD dwNumAddresses;
DWORD dwBearerModes;
DWORD dwMaxRate;
DWORD dwMediaModes;
DWORD dwGenerateToneModes;
DWORD dwGenerateToneMaxNumFreq;
DWORD dwGenerateDigitModes;
DWORD dwMonitorToneMaxNumFreq;
DWORD dwMonitorToneMaxNumEntries;
DWORD dwMonitorDigitModes;
DWORD dwGatherDigitsMinTimeout;
DWORD dwGatherDigitsMaxTimeout;
DWORD dwMedCtlDigitMaxListSize;
DWORD dwMedCtlMediaMaxListSize;
DWORD dwMedCtlToneMaxListSize;
DWORD dwMedCtlCallStateMaxListSize;
DWORD dwDevCapFlags;
DWORD dwMaxNumActiveCalls;
DWORD dwAnswerMode;
DWORD dwRingModes;
DWORD dwLineStates;
DWORD dwUUIAcceptSize;
DWORD dwUUIAnswerSize;
DWORD dwUUIMakeCallSize;
DWORD dwUUIDropSize;
DWORD dwUUISendUserUserInfoSize;
DWORD dwUUICallInfoSize;
LINEDIALPARAMS MinDialParams;
LINEDIALPARAMS MaxDialParams;
LINEDIALPARAMS DefaultDialParams;
DWORD dwNumTerminals;
DWORD dwTerminalCapsSize;
DWORD dwTerminalCapsOffset;
DWORD dwTerminalTextEntrySize;
DWORD dwTerminalTextSize;
DWORD dwTerminalTextOffset;
DWORD dwDevSpecificSize;
DWORD dwDevSpecificOffset;
} LINEDEVCAPS, FAR *LPLINEDEVCAPS;
Members
-
dwTotalSize
-
The total size in bytes allocated to this data structure.
-
dwNeededSize
-
The size in bytes for this data structure that is needed to hold the returned information.
-
dwUsedSize
-
The size in bytes of the portion of this data structure that contains useful information.
-
dwProviderInfoSize
-
dwProviderInfoOffset
-
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized field containing service provider information.
The dwProviderInfoSize/Offset member provides information about the provider hardware or software, such as the vendor name and version numbers of hardware or software. This information can be useful when a user needs to call customer service with problems regarding the provider.
-
dwSwitchInfoSize
-
dwSwitchInfoOffset
-
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing switch information.
The dwSwitchInfoSize/Offset member is intended to provide information about the switch to which the line device is connected, such as the switch manufacturer, the model name, the software version, and so on. This information can be useful when a user needs to call customer service with problems regarding the switch.
-
dwPermanentLineID
-
The permanent DWORD identifier by which the line device is known in the system's configuration. It is a permanent name for the line device. This permanent name (as opposed to dwDevice ID) does not change as lines are added and removed from the system. It can therefore be used to link line-specific information in the registry (or other files) in a way that is not affected by adding or removing other lines.
-
dwLineNameSize
-
dwLineNameOffset
-
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing a user-configurable name for this line device. This name can be configured by the user when configuring the line device's service provider and is provided for the user's convenience.
-
dwStringFormat
-
The string format used with this line device, of type STRINGFORMAT_. Values are:
-
STRINGFORMAT_ASCII
-
ASCII string format using one byte per character.
-
STRINGFORMAT_DBCS
-
DBCS string format using two bytes per character.
-
STRINGFORMAT_UNICODE
-
Unicode string format using two bytes per character.
-
dwAddressModes
-
The mode by which the originating address is specified, of type LINEADDRESSMODE_. Values are:
-
LINEADDRESSMODE_ADDRESSID
-
The address is specified using a small integer in the range from 0 through dwNumAddresses minus one, where dwNumAddresses is the value in the line's device capabilities.
-
LINEADDRESSMODE_DIALABLEADDR
-
The address is specified through its phone number.
-
dwNumAddresses
-
The number of addresses associated with this line device. Individual addresses are referred to by address identifiers. Address identifiers range from zero to one less than the value indicated by dwNumAddresses.
-
dwBearerModes
-
Flag array that indicates the different bearer modes the address is able to support. This member uses the following LINEBEARERMODE_ constants:
-
LINEBEARERMODE_VOICE
-
A regular 3.1 kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
-
LINEBEARERMODE_SPEECH
-
Corresponds to G.711 speech transmission on the call. The network can use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
-
LINEBEARERMODE_MULTIUSE
-
The multiuse mode defined by ISDN.
-
LINEBEARERMODE_DATA
-
The unrestricted data transfer on the call. The data rate is specified separately. In particular, when LINEBEARERMODE_DATA is set, dwMaxRate indicates the maximum rate of digital transmission on the bearer channel.
-
LINEBEARERMODE_ALTSPEECHDATA
-
The alternate transfer of speech or unrestricted data on the same call (ISDN).
-
LINEBEARERMODE_NONCALLSIGNALING
-
Corresponds to a non-call-associated signaling connection from the application to the service provider or switch (treated as a "media stream" by the Telephony API).
-
LINEBEARERMODE_PASSTHROUGH
-
When a call is active in LINEBEARERMODE_PASSTHROUGH, the service provider gives direct access to the attached hardware for control by the application. This mode is used primarily by applications desiring temporary direct control over asynchronous modems, accessed through the Win32 comm functions, for the purpose of configuring or using special features not otherwise supported by the service provider.
-
dwMaxRate
-
Contains the maximum data rate in bits per second for information exchange over the call. If LINEBEARERMODE_DATA is set in dwBearerModes, then dwMaxRate is set to the maximum rate of digital transmission on the bearer channel. If LINEBEARERMODE_DATA is not set, but LINEBEARERMODE_VOICE is set and dwMediaModes includes LINEMEDIAMODE_DATAMODEM, then dwMaxRate is set to the maximum synchronous bit rate of the modulated data signal, not including gains from error control or data compression, and not considering the impact of adaption to channel characteristics (e.g., a V.34 modem would say 28800, a V 32bis modem 14400, a V.32 modem 9600). The application must be careful to check to see that LINEBEARERMODE_DATA is not set, in order to avoid misinterpreting the dwMaxRate member (it is likely to be 64000 or higher if LINEBEARERMODE_DATA is set).
-
dwMediaModes
-
Flag array that indicates the different media modes the address is able to support, of type LINEMEDIAMODE_.
-
LINEMEDIAMODE_UNKNOWN
-
A media stream exists but its mode is unknown. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an inbound call's media mode may be unknown until after the call is answered and the media stream is filtered to make a determination.
-
LINEMEDIAMODE_INTERACTIVEVOICE
-
The presence of voice energy on the call and the call is treated as an interactive call with humans on both ends.
-
LINEMEDIAMODE_AUTOMATEDVOICE
-
The presence of voice energy on the call and the voice is locally handled by an automated application.
-
LINEMEDIAMODE_DATAMODEM
-
A data modem session on the call.
-
LINEMEDIAMODE_G3FAX
-
A group 3 fax is being sent or received over the call.
-
LINEMEDIAMODE_TDD
-
A TDD (Telephony Devices for the Deaf) session on the call.
-
LINEMEDIAMODE_G4FAX
-
A group 4 fax is being sent or received over the call.
-
LINEMEDIAMODE_DIGITALDATA
-
Digital data being transmitted over the call.
-
LINEMEDIAMODE_TELETEX
-
A teletex session on the call. Teletex is one of the telematic services.
-
LINEMEDIAMODE_VIDEOTEX
-
A videotex session on the call. Videotex is one the telematic services.
-
LINEMEDIAMODE_TELEX
-
A telex session on the call. Telex is one the telematic services.
-
LINEMEDIAMODE_MIXED
-
A mixed session on the call. Mixed is one the ISDN telematic services.
-
LINEMEDIAMODE_ADSI
-
An ADSI (Analog Display Services Interface) session on the call.
-
LINEMEDIAMODE_VOICEVIEW
-
The media mode of the call is VoiceView.
-
dwGenerateToneModes
-
Specifies the different kinds of tones that can be generated on this line, of type LINETONEMODE_. Values are:
-
LINETONEMODE_CUSTOM
-
The tone is a custom tone, defined by the specified frequencies.
-
LINETONEMODE_RINGBACK
-
The tone to be generated is ringback tone.
-
LINETONEMODE_BUSY
-
The tone is a standard (station) busy tone.
-
LINETONEMODE_BEEP
-
The tone is a beep, as used to announce the beginning of a recording.
-
LINETONEMODE_BILLING
-
The tone is a billing information tone such as a credit card prompt tone.
-
dwGenerateToneMaxNumFreq
-
Contains the maximum number of frequencies that can be specified in describing a general tone using the LINEGENERATETONE data structure when generating a tone using TSPI_lineGenerateTone. A value of zero indicates that tone generation is not available.
-
dwGenerateDigitModes
-
The digit modes than can be generated on this line, of type LINEDIGITMODE_. Values are:
-
LINEDIGITMODE_PULSE
-
Generate digits as pulse/rotary pulse sequences.
-
LINEDIGITMODE_DTMF
-
Generate digits as DTMF tones.
-
dwMonitorToneMaxNumFreq
-
Contains the maximum number of frequencies that can be specified in describing a general tone using the LINEMONITORTONE data structure when monitoring a general tone using TSPI_lineMonitorTones. A value of zero indicates that tone monitor is not available.
-
dwMonitorToneMaxNumEntries
-
Contains the maximum number of entries that can be specified in a tone list to TSPI_lineMonitorTones.
-
dwMonitorDigitModes
-
The digit modes than can be detected on this line, of type LINEDIGITMODE_. Values are:
-
LINEDIGITMODE_PULSE
-
Detect digits as audible clicks that are the result of rotary pulse sequences.
-
LINEDIGITMODE_DTMF
-
Detect digits as DTMF tones.
-
LINEDIGITMODE_DTMFEND
-
Detect down edges of digits detected as DTMF tones.
-
dwGatherDigitsMinTimeout
-
dwGatherDigitsMaxTimeout
-
Contain the minimum and maximum values in milliseconds that can be specified for both the first digit and interdigit timeout values used by TSPI_lineGatherDigits. If both these members are zero, timeouts are not supported.
-
dwMedCtlDigitMaxListSize
-
dwMedCtlMediaMaxListSize
-
dwMedCtlToneMaxListSize
-
dwMedCtlCallStateMaxListSize
-
Contain the maximum number of entries that can be specified in the digit list, the media list, the tone list, and the call state list parameters of TSPI_lineSetMediaControl, respectively.
-
dwDevCapFlags
-
Specifies various boolean device capabilities, of type LINEDEVCAPFLAGS_. Values are:
-
LINEDEVCAPFLAGS_CROSSADDRCONF
-
Specify whether calls on different addresses on this line can be conferenced.
-
LINEDEVCAPFLAGS_HIGHLEVCOMP
-
Specify whether high-level compatibility information elements are supported on this line.
-
LINEDEVCAPFLAGS_LOWLEVCOMP
-
Specify whether low-level compatibility information elements are supported on this line.
-
LINEDEVCAPFLAGS_MEDIACONTROL
-
Specify whether media control operations are available for calls at this line.
-
LINEDEVCAPFLAGS_MULTIPLEADDR
-
Specify whether TSPI_lineMakeCall or TSPI_lineDial are able to deal with multiple addresses at once (as for inverse multiplexing).
-
LINEDEVCAPFLAGS_CLOSEDROP
-
Specify whether the service provider drops (clears) active calls when all applications have closed the open line. If TRUE, the service provider drops all calls on the line when all applications have closed the line. If FALSE, the service provider keeps calls active. The service provider typically sets this to FALSE if some other device can keep the call alive, for example, if an analog line connects directly to the computer and phoneset in a party-line configuration, the offhook phone automatically keeps the call active even after the computer powers down.
-
LINEDEVCAPFLAGS_DIALBILLING
-
-
LINEDEVCAPFLAGS_DIALQUIET
-
-
LINEDEVCAPFLAGS_DIALDIALTONE
-
These flags indicate whether the "$", "@", or "W" dialable string modifier is supported for a given line device. If the modifier is supported, it is TRUE ; otherwise, FALSE. The "?" (prompt user to continue dialing) is never supported by a line device. These flags allow an application to determine "up front" which modifiers can result in the generation of a LINEERR. The application can pre-scan dialable strings for unsupported characters, or pass the raw string from lineTranslateAddress directly to the provider as part of lineMakeCall (or lineDial) and let the function generate an error to tell it which unsupported modifier occurs first in the string.
-
dwMaxNumActiveCalls
-
The maximum number of (minimum bandwidth) calls that can be active (connected) on the line at any one time. The actual number of active calls can be lower if higher bandwidth calls are established on the line.
-
dwAnswerMode
-
The effect on the active call when answering another offering call on a line device, of type LINEANSWERMODE_. Values are:
-
LINEANSWERMODE_NONE
-
Answering another call on the same has no effect on the existing active call(s) on the line.
-
LINEANSWERMODE_DROP
-
The currently active call is automatically dropped.
-
LINEANSWERMODE_HOLD
-
The currently active call is automatically placed on hold.
-
dwRingModes
-
Contains the number of different ring modes that can be reported in the LINE_LINEDEVSTATE message with the ringing indication. Different ring modes range from one to dwRingModes. Zero indicates no ring.
-
dwLineStates
-
Specifies the different line status components for which the application can be notified in a LINE_LINEDEVSTATE message on this line, of type LINEDEVSTATE_. Values are:
-
LINEDEVSTATE_OTHER
-
Device-status items other than those listed below have changed.
-
LINEDEVSTATE_RINGING
-
The switch tells the line to alert the user. This should be sent repeatedly in a LINE_LINEDEVSTATE message, once for each ring cycle. On a POTS device, the service provider can send the message whenever the central office sends ring voltage. On digital devices such as ISDN, the service provider may need to synthesize the repetition of the message if the switch generates only one ring request. Each repetition of the message should show the ring count increasing, so that toll save functions work properly.
-
LINEDEVSTATE_CONNECTED
-
The line was previously disconnected and is now connected to TAPI.
-
LINEDEVSTATE_DISCONNECTED
-
This line was previously connected and is now disconnected from TAPI.
-
LINEDEVSTATE_MSGWAITON
-
The "message waiting" indicator is turned on.
-
LINEDEVSTATE_MSGWAITOFF
-
The "message waiting" indicator is turned off.
-
LINEDEVSTATE_INSERVICE
-
The line is connected to TAPI. This happens when TAPI is first activated, or when the line wire is physically plugged in and in service at the switch while TAPI is active.
-
LINEDEVSTATE_OUTOFSERVICE
-
The line is out of service at the switch or is physically disconnected. TAPI cannot be used to operate on the line device.
-
LINEDEVSTATE_MAINTENANCE
-
Maintenance is being performed on the line at the switch. TAPI cannot be used to operate on the line device.
-
LINEDEVSTATE_OPEN
-
The line has been opened.
-
LINEDEVSTATE_CLOSE
-
The line has been closed.
-
LINEDEVSTATE_NUMCALLS
-
The number of calls on the line device has changed.
-
LINEDEVSTATE_NUMCOMPLETIONS
-
The number of outstanding call completions on the line device has changed.
-
LINEDEVSTATE_TERMINALS
-
The terminal settings have changed.
-
LINEDEVSTATE_ROAMMODE
-
The roam mode of the line device has changed.
-
LINEDEVSTATE_BATTERY
-
The battery level has changed significantly (cellular).
-
LINEDEVSTATE_SIGNAL
-
The signal level has changed significantly (cellular).
-
LINEDEVSTATE_DEVSPECIFIC
-
The line's device-specific information has changed.
-
LINEDEVSTATE_REINIT
-
Items have changed in the configuration of line devices. To become aware of these changes (such as for the appearance of new line devices) the application reinitializes its use of TAPI. The hDevice parameter is left NULL for this state change as it applies to any of the lines in the system.
-
LINEDEVSTATE_LOCK
-
The locked status of the line device has changed.
-
LINEDEVSTATE_REMOVED
-
The device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). A LINE_LINEDEVSTATE message with this value is normally immediately followed by a LINE_CLOSE message on the device. Subsequent attempts to access the device prior to TAPI being reinitialized result in LINEERR_NODEVICE being returned to the application. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it to applications that have negotiated this or a subsequent API version; applications negotiating a previous API version do not receive any notification.
-
dwUUIAcceptSize
-
The maximum size of user-user information that can be sent during a call accept.
-
dwUUIAnswerSize
-
The maximum size of user-user information that can be sent during a call answer.
-
dwUUIMakeCallSize
-
The maximum size of user-user information that can be sent during a make call.
-
dwUUIDropSize
-
The maximum size of user-user information that can be sent during a call drop.
-
dwUUISendUserUserInfoSize
-
The maximum size of user-user information that can be sent separately at any time during a call with TSPI_lineSendUserUserInfo.
-
dwUUICallInfoSize
-
The maximum size of user-user information that can be received in the LINECALLINFO structure.
-
MinDialParams
-
MaxDialParams
-
Contain the minimum and maximum values for the dial parameters in milliseconds that can be set for calls on this line. Dialing parameters can be set to values in this range. The granularity of the actual settings are service-provider specific.
-
DefaultDialParams
-
Contains the default dial parameters used for calls on this line. These parameter values can be overridden on a per-call basis.
-
dwNumTerminals
-
The number of terminals that can be set for this line device, its addresses, or its calls. Individual terminals are referred to by terminal identifiers, and range from zero to one less than the value indicated by dwNumTerminals.
-
dwTerminalCapsSize
-
dwTerminalCapsOffset
-
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device field containing an array with entries of type LINETERMCAPS. This array is indexed by terminal identifiers, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the terminal device capabilities of the corresponding terminal.
-
dwTerminalTextEntrySize
-
The size in bytes of each of the terminal text descriptions pointed at by dwTerminalTextSize/Offset.
-
dwTerminalTextSize
-
dwTerminalTextOffset
-
The size in bytes and the offset from the beginning of this data structure in bytes of the variably sized field containing descriptive text about each of the line's available terminals. Each message is dwTerminalTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities.
-
dwDevSpecificSize
-
dwDevSpecificOffset
-
The size in bytes and the offset in bytes from the beginning of this data structure of the variably sized device-specific field.
Remarks
Device-specific extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this data structure.
See Also
LINEADDRESSSHARING_ Constants, LINEBEARERMODE_ Constants, LINEDIGITMODE_ Constants, LINETERMMODE_ Constants, LINEGENERATETONE, LINE_CLOSE, LINE_LINEDEVSTATE, TSPI_lineGetDevCaps