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;
DWORD dwLineFeatures;
DWORD dwSettableDevStatus;
DWORD dwDeviceClassesSize;
DWORD dwDeviceClassesOffset;
} 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 all 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 of the variably sized field containing service provider information, and
the offset in bytes from the beginning of this data structure. The dwProviderInfoSize/Offset
field is intended to provide information about the provider hardware and/or
software, such as the vendor name and version numbers of hardware and 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 of the variably sized device field containing switch information, and the
offset in bytes from the beginning of this data structure. The dwSwitchInfoSize/Offset
field 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 or
removed from the system. It can therefore 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.
dwLineNameSize
dwLineNameOffset
The size in
bytes of the variably sized device field containing 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
The string
format used with this line device. This field uses the following STRINGFORMAT_
constants:
STRINGFORMAT_ASCII
The ASCII
string format using one byte per character.
STRINGFORMAT_DBCS
The DBCS
string format using two bytes per character.
STRINGFORMAT_UNICODE
The Unicode
string format using two bytes per character.
dwAddressModes
The mode by
which the originating address is specified. This field uses the
LINEADDRESSMODE_ constants.
dwNumAddresses
The number of
addresses associated with this line device. Individual addresses are referred
to by address IDs. Address IDs range from zero to one less than the value
indicated by dwNumAddresses.
dwBearerModes
This flag
array indicates the different bearer modes that the address is able to support.
It uses the following LINEBEARERMODE_ constants:
LINEBEARERMODE_VOICE
This is 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
This
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
This
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
This field
contains the maximum data rate in bits per second for information exchange over
the call.
dwMediaModes
This flag
array indicates the different media modes the address is able to support. It
uses the following LINEMEDIAMODE_ constants:
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 inbound
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 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_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 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
The different
kinds of tones that can be generated on this line. This field uses the
following LINETONEMODE_ constants:
LINETONEMODE_CUSTOM
The tone is a
custom tone defined by the specified frequencies.
LINETONEMODE_RINGBACK
The tone to
be generated is a 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
billing information tone such as a credit card prompt tone.
dwGenerateToneMaxNumFreq
This field
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 lineGenerateTone. A value of zero indicates
that tone generation is not available.
dwGenerateDigitModes
This field
specifies the digit modes than can be generated on this line. It uses the
following LINEDIGITMODE_ constants:
LINEDIGITMODE_PULSE
Generate digits
as pulse/rotary pulse sequences.
LINEDIGITMODE_DTMF
Generate
digits as DTMF tones.
dwMonitorToneMaxNumFreq
This field
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 lineMonitorTones.
A value of zero indicates that tone monitor is not available.
dwMonitorToneMaxNumEntries
This field
contains the maximum number of entries that can be specified in a tone list to lineMonitorTones.
dwMonitorDigitModes
This field
specifies the digit modes than can be detected on this line. It uses the
following LINEDIGITMODE_ constants:
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 the
down edges of digits detected as DTMF tones.
dwGatherDigitsMinTimeout
dwGatherDigitsMaxTimeout
These fields
contain the minimum and maximum values in milliseconds that can be specified
for both the first digit and inter-digit timeout values used by lineGatherDigits. If both these field are
zero, timeouts are not supported.
dwMedCtlDigitMaxListSize
dwMedCtlMediaMaxListSize
dwMedCtlToneMaxListSize
dwMedCtlCallStateMaxListSize
These fields
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 lineSetMediaControl respectively.
dwDevCapFlags
This field
specifies various Boolean device capabilities. It uses the following
LINEDEVCAPFLAGS_ constants:
LINEDEVCAPFLAGS_CROSSADDRCONF
Specifies
whether calls on different addresses on this line can be conferenced.
LINEDEVCAPFLAGS_HIGHLEVCOMP
Specifies
whether high-level compatibility information elements are supported on this
line.
LINEDEVCAPFLAGS_LOWLEVCOMP
Specifies
whether low-level compatibility information elements are supported on this
line.
LINEDEVCAPFLAGS_MEDIACONTROL
Specifies whether
media-control operations are available for calls at this line.
LINEDEVCAPFLAGS_MULTIPLEADDR
Specifies
whether lineMakeCall
or lineDial
are 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 phoneset both
connect directly to them in a party-line configuration, the offhook phone will
automatically keep the call active even after the computer powers down.
Applications
should check this flag to determine whether 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 whether 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 allow 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 (lineDial, and so on) and let the
function generate an error to tell it which unsupported modifier occurs first
in the string.
dwMaxNumActiveCalls
This field
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
This field
specifies the effect on the active call when answering another offering call on
a line device. This field uses the following LINEANSWERMODE_ constants:
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 will be automatically dropped.
LINEANSWERMODE_HOLD
The currently
active call will automatically be placed on hold.
dwRingModes
This field
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
This field
specifies the different line status components for which the application may be
notified in a LINE_LINEDEVSTATE message on this line. It uses the following
LINEDEVSTATE_ constants:
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 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 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 fields 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 will pass it along to applications which have negotiated TAPI
version 0x00010004 or above; applications negotiating a previous API version
will receive LINE_LINEDEVSTATE messages specifying LINEDEVSTATE_REINIT,
requiring them to shutdown and reinitialize their connection to TAPI in order
to obtain the updated information.
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
information. If a service provider sends a LINE_LINEDEVSTATE message containing this value
to TAPI, TAPI will pass it along to applications which have negotiated TAPI
version 0x00010004 or above; applications negotiating a previous API version
will not receive any notification.
LINEDEVSTATE_TRANSLATECHANGE
Indicates
that, due to configuration changes made by the user or other circumstances, one
or more of the fields in the LINETRANSLATECAPS5PWH.X 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 will pass it along to applications
which have negotiated TAPI version 0x00010004 or above; applications
negotiating a previous API version will receive LINE_LINEDEVSTATE messages
specifying LINEDEVSTATE_REINIT, requiring them to shutdown and reinitialize
their connection to TAPI in order to obtain the updated information.
LINEDEVSTATE_COMPLCANCEL
Indicates
that the call completion identified by the completion ID contained in parameter
dwParam2 of the LINE_LINEDEVSTATE message has been externally canceled and is no
longer considered valid (if that value were to be passed in a subsequent call
to lineUncompleteCall,
the function would fail with LINEERR_INVALCOMPLETIONID). If a service provider
sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI will pass
it along to applications which have negotiated TAPI version 0x00010004 or
above; applications negotiating a previous API version will 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). A LINE_LINEDEVSTATE message with this value will
normally be immediately followed by a LINE_CLOSE message on the device.
Subsequent attempts to access the device prior to TAPI being reinitialized will
result in LINEERR_NODEVICE being returned to the application. If a service
provider sends a LINE_LINEDEVSTATE message containing this value to TAPI, TAPI
will pass it along to applications which have negotiated TAPI version
0x00010004 or above; applications negotiating a previous API version will not
receive any notification.
dwUUIAcceptSize
This field
specifies the maximum size of user-to-user information that can be sent during
a call accept.
dwUUIAnswerSize
This field
specifies the maximum size of user-to-user information that can be sent during
a call answer.
dwUUIMakeCallSize
This field
specifies the maximum size of user-to-user information that can be sent during
a make call.
dwUUIDropSize
This field
specifies the maximum size of user-to-user information that can be sent during
a call drop.
dwUUISendUserUserInfoSize
This field
specifies the maximum size of user-to-user information that can be sent
separately any time during a call with lineSendUserUserInfo.
dwUUICallInfoSize
This field
specifies the maximum size of user-to-user information that can be received in
the LINECALLINFO
structure.
MinDialParams
MaxDialParams
These fields
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 is service
provider-specific.
DefaultDialParams
This field
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 IDs 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 IDs, 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 of the variably sized field containing descriptive text about each of the
line's available terminals, and the offset in bytes from the beginning of this
data structure. 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 of the variably sized device-specific field, and the offset in bytes from
the beginning of this data structure
dwLineFeatures
This field
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 field allows
an application to discover which line features can be (and which can never be)
supported by the device.
dwSettableDevStatus
The
LINEDEVSTATUS_ values which can be modified using lineSetLineDevStatus.
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 nulls; the last identifier in the list is followed by two nulls.
Remarks
Device-specific
extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset)
variably sized area of this data structure.
Older
applications will have been compiled without new fields 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 less than the size of the fixed portion of the structure as
defined in the dwAPIVersion specified, LINEERR_STRUCTURETOOSMALL will be
returned. If sufficient memory has been allocated by the application, before
calling TSPI_lineGetDevCaps, TAPI will set the dwNeededSize and dwUsedSize
fields 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 fields 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 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
will equal 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.
The members dwSettableDevStatus
through dwDeviceClassesOffset are available only to applications that
open the line device with an API version of 0x00020000 or greater.
See Also