2.2.6.23 LINEDEVCAPS

This LINEDEVCAPS packet specifies the capabilities of a line device. LINEDEVCAPS is supplied by the server in the field VarData of the returned version of the GetDevCaps packet if the request is completed successfully.

dwTotalSize (4 bytes): An unsigned 32-bit integer. The total size, in bytes, that is allocated to this data packet.

dwNeededSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, for this data packet that is needed to hold all the returned data.

dwUsedSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the portion of this packet that contains useful data.

dwProviderInfoSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains service provider data.

dwProviderInfoOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. The dwProviderInfoSize and dwProviderInfoOffset fields are intended to provide data about the provider hardware 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 (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the variably sized device field that contains switch data.

dwSwitchInfoOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet.

The dwSwitchInfoSize and dwSwitchInfoOffset fields are 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 (4 bytes): An unsigned 32-bit integer. A permanent identifier by which the line device is known in the computing system configuration. It is a permanent name for the line device. This permanent name does not change as lines are added to, or removed from, the system and persists through operating system upgrades. Therefore, it can be used to link line-specific information in .ini files (or other files) in a way that is not affected by adding or removing other lines or by changing the operating system.

dwLineNameSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the variably sized device field that contains a user configurable name for this line device.

dwLineNameOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. This name can be configured by the user when configuring the service provider of the line device and is provided for user convenience.

dwStringFormat (4 bytes): An unsigned 32-bit integer. The value that specifies the string format that is used with this line device. This member MUST use one of the STRINGFORMAT_Constants.

dwAddressModes (4 bytes): An unsigned 32-bit integer. The value that specifies the mode by which the originating address is specified. This field MUST use one of the LINEADDRESSMODE_Constants.

dwNumAddresses (4 bytes): An unsigned 32-bit integer. The number of addresses that is associated with this line device. Individual addresses are referred to by address identifiers. Address identifiers range from zero to one less than the value that is indicated by dwNumAddresses.

dwBearerModes (4 bytes): An unsigned 32-bit integer. A flag array that indicates the different bearer modes that the address is able to support. This member MUST use LINEBEARERMODE_Constants.

dwMaxRate (4 bytes): An unsigned 32-bit integer. The maximum data rate, in bits per second, for data exchange over the call.

dwMediaModes (4 bytes): An unsigned 32-bit integer. The flag array that indicates the different media modes that the address is able to support. This member MUST use LINEMEDIAMODE_Constants.

dwGenerateToneModes (4 bytes): An unsigned 32-bit integer. The tones that can be generated on this line. This field uses one or more of the LINETONEMODE_Constants. A value of 0 means that tone generation is not supported on this device.

dwGenerateToneMaxFreq (4 bytes): An unsigned 32-bit integer. The maximum number of frequencies that can be specified in describing a general tone that uses the LINEGENERATETONE packet when generating a tone using lineGenerateTone. A value of 0 indicates that tone generation is not available.

dwGenerateDigitModes (4 bytes): An unsigned 32-bit integer. The digit modes that can be generated on this line. This member uses one or more of the LINEDIGITMODE_Constants. A value of 0 means that digit generation is not supported on this device.

dwMonitorToneMaxNumFreq (4 bytes): An unsigned 32-bit integer. The maximum number of frequencies that can be specified in describing a general tone that uses the LINEGENERATETONE packet when monitoring a general tone that uses lineMonitorTones. A value of 0 indicates that tone monitor is not available.

dwMonitorToneMaxNumEntries (4 bytes): An unsigned 32-bit integer. A maximum number of entries that can be specified in a tone list to lineMonitorTones.

dwMonitorDigitModes (4 bytes): An unsigned 32-bit integer. The digit modes that can be detected on this line. This member uses one or more of the LINEDIGITMODE_Constants. A value of 0 means that digit mode detection is not supported on this device.

dwGatherDigitsMinTimeout (4 bytes): An unsigned 32-bit integer. The minimum value, in milliseconds, that can be specified for both the first digit and interdigit time-out values that are used by lineGatherDigits. If both dwGatherDigitsMinTimeout and dwGatherDigitsMaxTimeout are zero, time-outs are not supported.

dwGatherDigitsMaxTimeout (4 bytes): An unsigned 32-bit integer. The maximum value, in milliseconds, that can be specified for both the first digit and interdigit time-out values that are used by lineGatherDigits. If both dwGatherDigitsMinTimeout and dwGatherDigitsMaxTimeout are zero, time-outs are not supported.

dwMedCtlDigitMaxListSize (4 bytes): An unsigned 32-bit integer. The maximum number of entries that can be specified in the digit list parameter of SetMediaControl.

dwMedCtlMediaMaxListSize (4 bytes): An unsigned 32-bit integer. The maximum number of entries that can be specified in the media list.

dwMedCtlToneMaxListSize (4 bytes): An unsigned 32-bit integer. The maximum number of entries that can be specified in the tone list parameter of SetMediaControl.

dwMedCtlCallStateMaxListSize (4 bytes): An unsigned 32-bit integer. The maximum number of entries that can be specified in the call state list.

dwDevCapFlags (4 bytes): An unsigned 32-bit integer. The value that specifies various Boolean device capabilities. This member MUST use LINEDEVCAPFLAGS_Constants.

dwMaxNumActiveCalls (4 bytes): An unsigned 32-bit integer. The maximum number of (minimum bandwidth) calls that can be active (connected) on the line at one time. The actual number of active calls can be lower if higher bandwidth calls have been established on the line.

dwAnswerMode (4 bytes): An unsigned 32-bit integer. A value that specifies the effect on the active call when answering another offering call on a line device. This member MUST use one or more of LINEANSWERMODE_Constants.

dwRingModes (4 bytes): An unsigned 32-bit integer. The number of different ring modes that can be reported in the LINE_LINEDEVSTATE packet with the ringing indication. Different ring modes range from one to dwRingModes. Zero indicates no ring.

dwLineStates (4 bytes): An unsigned 32-bit integer. Specifies the different line status components for which the application can be notified in a LINE_LINEDEVSTATE packet on this line. This member MUST use one or more of LINEDEVSTATE_Constants.

dwUUIAcceptSize (4 bytes): An unsigned 32-bit integer. The maximum size of user-user data that can be sent during a call accept.

dwUUIAnswerSize (4 bytes): An unsigned 32-bit integer. The maximum size of user-user data that can be sent during a call answer.

dwUUIMakeCallSize (4 bytes): An unsigned 32-bit integer. The maximum size of user-user data that can be sent during a make call.

dwUUIDropSize (4 bytes): An unsigned 32-bit integer. The maximum size of user-user data that can be sent during a call drop.

dwUUISendUserUserInfoSize (4 bytes): An unsigned 32-bit integer. The maximum size of user-user information, including the null terminator, that can be sent separately any time during a call with SendUserUserInfo.

dwUUICallInfoSize (4 bytes): An unsigned 32-bit integer. The maximum size of user-user data that can be received in the LINECALLINFO packet.

MinDialParams (16 bytes): A LINEDIALPARAMS packet. The minimum value, in milliseconds, for the dial parameters that can be set for calls on this line. Dialing parameters can be set to values in the range MinDialParams to MaxDialParams. The granularity of the actual settings is service provider–specific.

MaxDialParams (16 bytes): A LINEDIALPARAMS packet. The maximum value, in milliseconds, for the dial parameters that can be set for calls on this line. Dialing parameters can be set to values in the range MinDialParams to MaxDialParams. The granularity of the actual settings is service provider–specific.

DefaultDialParams (16 bytes): A LINEDIALPARAMS packet. The default dial parameters that are used for calls on this line. These parameter values can be overridden on a per-call basis.

dwNumTerminals (4 bytes): An unsigned 32-bit integer. The number of terminals that can be set for this line device, its addresses, or its calls. Individual terminals are referred to by terminal IDs and range from zero to one less than the value that is indicated by dwNumTerminals.

dwTerminalCapsSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the variably sized device field that contains an array with entries of type LINETERMCAPS.

dwTerminalCapsOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of this structure to the variably sized device field that contains an array with entries of type LINETERMCAPS. This array is indexed by terminal IDs, in the range from zero to dwNumTerminals minus one. Each entry in the array specifies the terminal device capabilities of the corresponding terminal. The size of the field is specified by dwTerminalCapsSize.

dwTerminalTextEntrySize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of each terminal text description, including the null terminator that is pointed to by dwTerminalTextSize and dwTerminalTextOffset.

dwTerminalTextSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the variably sized field that contains descriptive text about each of the line's available terminals, including the null terminator.

dwTerminalTextOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet to the descriptive text about each of the line's available terminals. Each packet is dwTerminalTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the device capabilities of the line. The size of the field is specified by dwTerminalTextSize.

dwDevSpecificSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the variably sized device-specific field.

dwDevSpecificOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this data packet.

dwLineFeatures (4 bytes): An unsigned 32-bit integer. A value that specifies the available features for this line that use one or more of 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 can 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 (4 bytes):  An unsigned 32-bit integer. LINEDEVSTATUSFLAGS_Constants that can be modified. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwDeviceClassesSize (4 bytes): An unsigned 32-bit integer. The length, in bytes, from the beginning of LINEDEVCAPS of a string that consists of the device class identifiers that are supported on one or more addresses on this line for use with the GetID packet, separated by null characters; the last identifier in the list is followed by two null characters. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwDeviceClassesOffset (4 bytes): An unsigned 32-bit integer. The offset of the string that is described in the dwDeviceClassesSize member. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

PermanentLineGuid (16 bytes): The GUID that is permanently associated with the line device. This member of the packet is available only if the negotiated TAPI version is 2.2 or higher.

dwAddressTypes (4 bytes): An unsigned 32-bit integer. The address type that is used for the call. This member of the packet is available only if the negotiated TAPI version is 3.0 or higher.

ProtocolGuid (16 bytes): A GUID that indicates the current TAPI protocol. This member of the packet is available only if the negotiated TAPI version is 3.0 or higher. This field MUST be one of the following values:

Value	Meaning
TAPIPROTOCOL_PSTN 831CE2D6-83B5-11d1-BB5C-00C04FB6809F	PSTN protocol
TAPIPROTOCOL_H323 831CE2D7-83B5-11d1-BB5C-00C04FB6809F	H.323 protocol
TAPIPROTOCOL_Multicast 831CE2D8-83B5-11d1-BB5C-00C04FB6809F	Multicast protocol

dwAvailableTracking (4 bytes): An unsigned 32-bit integer. The available tracking, as represented by a LINECALLHUBTRACKING_Constants. This member of the packet is available only if the negotiated TAPI version is 3.0 or higher.

VarData (variable): MUST contain:

• Service provider–specific information as specified by dwProviderInfoOffset.

• Data about the switch as specified by dwSwitchInfoOffset.

• The name of the line device as specified by dwLineNameOffset.

• An array that has entries of type LINETERMCAPS as specified by dwTerminalCapsOffset.

• Text about the available terminals for each line as specified by dwTerminalTextOffset.

• Device-specific information as specified by dwDevSpecificOffset.

• Device class identifiers that are supported on the device as specified by dwDeviceClassesOffset.

Device-specific extensions SHOULD use the dwDevSpecificSize and dwDevSpecificOffset members of this packet.

Applications that are negotiated with TAPI versions earlier than TAPI versions 2.0, 2.2, or 3.0 are not aware of the new members in the LINEDEVCAPS packet that are available only from the corresponding TAPI version and MUST use a SIZEOF LINEDEVCAPS that is smaller than the new size. The application passes in a dwAPIVersion parameter with the GetDevCaps packet, 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 packet, as defined in the specified dwAPIVersion, LINEERR_STRUCTURETOOSMALL is returned. If sufficient memory has been allocated by the application, before calling the GetDevCaps packet, TAPI sets the dwNeededSize and dwUsedSize members to the fixed size of the packet as it existed in the specified TAPI version.

New applications MUST be aware of the negotiated TAPI version and not examine the contents of members in the fixed portion beyond the original end of the fixed portion of the packet for the negotiated TAPI 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 packet can contain valid values even if the dwBearerModes member of the LINEDEVCAPS packet 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 fastest modulation speed of the modem is V.32bis at 14,400 bps, 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.