This structure describes the capabilities of a line device.
At a Glance
| Header file: | Tapi.h |
| Windows CE versions: | 1.0 and later |
Syntax
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
DWORD dwLineFeatures;
DWORD dwSettableDevStatus;
DWORD dwDeviceClassesSize;
DWORD dwDeviceClassesOffset;
} LINEDEVCAPS, *LPLINEDEVCAPS;
Members
dwTotalSize
Specifies the total size, in bytes, allocated to this data structure.
dwNeededSize
Specifies the size, in bytes, for this data structure that is needed to hold all the returned data.
dwUsedSize
Specifies the size, in bytes, of the portion of this data structure that contains useful data.
dwProviderInfoSize
dwProviderInfoOffset
Specify the size, in bytes, of the field that contains service provider data, and the offset, in bytes, from the beginning of this data structure. The dwProviderInfoSize/Offset member is intended to provide data about the provider hardware and/or software, such as the vendor name and version numbers of hardware and software. This data can be useful when a user needs to call customer service with problems regarding the provider.
dwSwitchInfoSize
dwSwitchInfoOffset
Specify the size, in bytes, of the variably sized device field that contains switch data, and the offset, in bytes, from the beginning of this data structure. The dwSwitchInfoSize/Offset member is intended to provide data 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 data can be useful when a user needs to call customer service with problems regarding the switch.
dwPermanentLineID
Unsupported; set to zero.
dwLineNameSize
dwLineNameOffset
Specify the size, in bytes, of the variably sized device field that contains a user configurable name for this line device, and the offset, in bytes, from the beginning of this data structure. 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
Specifies the string format used with this line device. This member uses the following STRINGFORMAT_ constants:
| Value | Description |
| STRINGFORMAT_ASCII | The ASCII string format using one byte per character. |
| STRINGFORMAT_DBCS | The DBCS string format using one or two bytes per character. |
| STRINGFORMAT_UNICODE | The Unicode string format using two bytes per character. |
dwAddressModes
Specifies the mode by which the originating address is specified. This member uses the LINEADDRESSMODE_ constants.
dwNumAddresses
Specifies 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 that the address is able to support. This member uses the following LINEBEARERMODE_ constants:
| Value | Description |
| 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 may 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. |
| 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 communications 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 data exchange over the call.
dwMediaModes
Flag array that indicates the different media modes the address is able to support. This member uses the following LINEMEDIAMODE_ constants:
| Value | Description |
| LINEMEDIAMODE_UNKNOWN | A media stream exists, but its mode is not known. This corresponds to a call with an unclassified media type. In typical analog telephony environments, an incoming call’s media mode may be unknown until after the call has been answered and the media stream filtered to make a determination. |
| LINEMEDIAMODE_INTERACTIVEVOICE | The presence of speech on the call and the call is treated as an interactive call with humans on both ends. |
| LINEMEDIAMODE_AUTOMATEDVOICE | The presence of speech 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_G4FAX | A group 4 fax is being sent or received over the call. |
| LINEMEDIAMODE_TDD | A TDD (Telephony Devices for the Deaf) session on 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 of the telematic services. |
| LINEMEDIAMODE_TELEX | A telex session on the call. Telex is one of the telematic services. |
| LINEMEDIAMODE_MIXED | A mixed session on the call. Mixed is one of 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;
dwGenerateToneMaxNumFreq;
dwGenerateDigitModes;
dwMonitorToneMaxNumFreq;
dwMonitorToneMaxNumEntries;
dwMonitorDigitModes;
dwGatherDigitsMinTimeout;
dwGatherDigitsMaxTimeout;
Unsupported; set to zero.
dwMedCtlDigitMaxListSize
Unsupported; set to zero.
dwMedCtlMediaMaxListSize
Contains the maximum number of entries that can be specified in the media list.
dwMedCtlToneMaxListSize
Unsupported; set to zero.
dwMedCtlCallStateMaxListSize
Contains the maximum number of entries that can be specified in the call state list.
dwDevCapFlags
Specifies various Boolean device capabilities. This member uses the following LINEDEVCAPFLAGS_ constants:
| Value | Description |
| LINEDEVCAPFLAGS_CROSSADDRCONF | Specifies if calls on different addresses on this line can be conferenced. |
| LINEDEVCAPFLAGS_HIGHLEVCOMP | Specifies if high-level compatibility data elements are supported on this line. |
| LINEDEVCAPFLAGS_LOWLEVCOMP | Specifies if low-level compatibility data elements are supported on this line. |
| LINEDEVCAPFLAGS_MEDIACONTROL | Specifies if media control operations are available for calls at this line. |
| LINEDEVCAPFLAGS_MULTIPLEADDR | Specifies if lineMakeCall is able to deal with multiple addresses at once (such as for inverse multiplexing). |
| LINEDEVCAPFLAGS_CLOSEDROP | Specifies what happens when an open line is closed while the application has calls active on the line. If TRUE, the service provider drops (clears) all active calls on the line when the last application that has opened the line closes it with lineClose. If FALSE, the service provider does not drop active calls in such cases. Instead, the calls remain active and under control of external device(s). A service provider typically sets this bit to FALSE if there is some other device that can keep the call alive. For example, if an analog line has the computer and phone set both connect directly to them in a party-line configuration, the offhook phone automatically keeps the call active even after the computer powers down. |
| Applications should check this flag to determine if to warn the user (with an OK/Cancel dialog box) that active calls will be lost. | |
| LINEDEVCAPFLAGS_DIALBILLING LINEDEVCAPFLAGS_DIALQUIET LINEDEVCAPFLAGS_DIALDIALTONE |
These flags indicate if the “$”, “@”, or “W” dialable string modifier is supported for a given line device. It is TRUE if the modifier is supported; otherwise, FALSE. The “?” (prompt user to continue dialing) is never supported by a line device. These flags enable an application to determine “up front” which modifiers would result in the generation of a LINEERR. The application has the choice of pre-scanning dialable strings for unsupported characters, or passing the “raw” string from lineTranslateAddress directly to the provider as part of lineMakeCall and letting the function generate an error to tell it which unsupported modifier occurs first in the string. |
dwMaxNumActiveCalls
Provides 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 may be lower if higher bandwidth calls have been established on the line.
dwAnswerMode
Specifies the effect on the active call when answering another offering call on a line device. This member uses the following LINEANSWERMODE_ constants:
| Value | Description |
| LINEANSWERMODE_NONE | Answering another call on the same line 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 may be notified in a LINE_LINEDEVSTATE message on this line. This member uses the following LINEDEVSTATE_ constants:
| Value | Description |
| LINEDEVSTATE_OTHER | Device-status items other than those listed below have changed. The application should check the current device status to determine which items have changed. |
| LINEDEVSTATE_RINGING | The switch tells the line to alert the user. Service providers notify applications on each ring cycle by sending LINE_LINEDEVSTATE messages containing this constant. For example, in the United States, service providers send a message with this constant every six seconds. |
| 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_NUMCOMPLETIONS | The number of outstanding call completions on the line device has changed. |
| 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 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_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 data 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 should reinitialize 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_CAPSCHANGE | Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the LINEDEVCAPS structure for the address have changed. The application should use lineGetDevCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated data. |
| LINEDEVSTATE_CONFIGCHANGE | Indicates that configuration changes have been made to one or more of the media devices associated with the line device. The application, if it desires, may use lineGetDevConfig to read the updated data. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification. |
| LINEDEVSTATE_TRANSLATECHANGE | Indicates that due to configuration changes made by the user or other circumstances one or more of the members in the LINETRANSLATECAPS structure have changed. The application should use lineGetTranslateCaps to read the updated structure. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize their connection to TAPI in order to obtain the updated data. |
| LINEDEVSTATE_COMPLCANCEL | Indicates that the call completion identified by the completion identifier contained in the dwParam2 parameter of the LINE_LINEDEVSTATE message has been externally canceled and is no longer considered valid. If a service provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI passes it along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification. |
| LINEDEVSTATE_REMOVED | Indicates that the device is being removed from the system by the service provider (most likely through user action, through a control panel or similar utility). Normally, a LINE_LINEDEVSTATE message with this value is 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 along to applications that have negotiated TAPI version 1.4 or later; applications negotiating a previous API version do not receive any notification. |
dwUUIAcceptSize
Specifies the maximum size of user-user data that can be sent during a call accept.
dwUUIAnswerSize
Specifies the maximum size of user-user data that can be sent during a call answer.
dwUUIMakeCallSize
Specifies the maximum size of user-user data that can be sent during a make call.
dwUUIDropSize
Specifies the maximum size of user-user data that can be sent during a call drop.
dwUUISendUserUserInfoSize
Unsupported; set to zero.
dwUUICallInfoSize
Specifies the maximum size of user-user data that can be received in the LINECALLINFO structure.
MinDialParams
MaxDialParams
Unsupported; set to zero
DefaultDialParams
Unsupported; set to zero.
dwNumTerminals
dwTerminalCapsSize
dwTerminalCapsOffset
dwTerminalTextEntrySize
dwTerminalTextSize
dwTerminalTextOffset
Unsupported; set to zero.
dwDevSpecificSize
dwDevSpecificOffset
Specify the size, in bytes, of the variably sized device-specific field, and the offset, in bytes, from the beginning of this data structure.
dwLineFeatures
Specifies the features available for this line using the LINEFEATURE_ constants. Invoking a supported feature requires the line to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature may be available if the line is in the appropriate state for the operation to be meaningful. This member enables an application to discover which line features can be (and which can never be) supported by the device.
dwSettableDevStatus
The LINEDEVSTATUS_ values that can be modified using the lineSetLineDevStatus function.
dwDeviceClassesSize
dwDeviceClassesOffset
Length in bytes and offset from the beginning of LINEDEVCAPS of a string consisting of the device class identifiers supported on one or more addresses on this line for use with lineGetID, separated by NULL characters; the last identifier in the list is followed by two NULL characters.
Remarks
Device-specific extensions should use the dwDevSpecificSize and dwDevSpecificOffset members of this structure.
Older applications are compiled without new members in the LINEDEVCAPS structure, and using a SIZEOF LINEDEVCAPS smaller than the new size. The application passes in a dwAPIVersion parameter with the lineGetDevCaps function, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize member less than the size of the fixed portion of the structure as defined in the specified dwAPIVersion, LINEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling TSPI_lineGetDevCaps, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the structure as it existed in the specified API version.
New applications must be cognizant of the API version negotiated, and not examine the contents of members in the fixed portion beyond the original end of the fixed portion of the structure for the negotiated API version.
If the LINEBEARERMODE_DATA bit is set in the dwBearerModes member, the dwMaxRate member indicates the maximum rate of digital transmission on the bearer channel. The dwMaxRate member of the LINEDEVCAPS structure can contain valid values even if the dwBearerModes member of the LINEDEVCAPS structure is not set to LINEBEARERMODE_DATA.
If LINEBEARERMODE_DATA is not set in dwBearerModes, but the LINEBEARERMODE_VOICE value is set and the LINEMEDIAMODE_DATAMODEM value is set in the dwMediaModes member, the dwMaxRate member indicates the maximum SYNCHRONOUS (DCE) bit rate on the phone line for the attached modem or functional equivalent. For example, if the modem’s fastest modulation speed is V.32bis at 14,400bps, dwMaxRate equals 14400. This is not the fastest DTE port rate (which would most likely be 38400, 57600, or 115200), but the fastest bit rate the modem supports on the phone line.
The application must be careful to check to see that LINEBEARERMODE_DATA is not set, to avoid misinterpreting the dwMaxRate member. It is likely to be 64000 or higher if LINEBEARERMODE_DATA is set.
It should also be noted that if the modem has not been specifically identified (for example, it is a “generic” modem), the figure indicated is a “best guess” based on examination of the modem.