LINECALLPARAMS
The LINECALLPARAMS
structure describes parameters supplied when making calls using lineMakeCall. The LINECALLPARAMS
structure is also used as a parameter in other operations. The comments on the
right indicate the default values used when this structure is not provided to lineMakeCall.
typedef struct linecallparams_tag { // Defaults:
DWORD dwTotalSize; // ---------
DWORD dwBearerMode; // voice
DWORD dwMinRate; // (3.1kHz)
DWORD dwMaxRate; // (3.1kHz)
DWORD dwMediaMode; // interactiveVoice
DWORD dwCallParamFlags; // 0
DWORD dwAddressMode; // addressID
DWORD dwAddressID; // (any available)
LINEDIALPARAMS DialParams; // (0, 0, 0, 0)
DWORD dwOrigAddressSize; // 0
DWORD dwOrigAddressOffset;
DWORD dwDisplayableAddressSize; // 0
DWORD dwDisplayableAddressOffset;
DWORD dwCalledPartySize; // 0
DWORD dwCalledPartyOffset;
DWORD dwCommentSize; // 0
DWORD dwCommentOffset;
DWORD dwUserUserInfoSize; // 0
DWORD dwUserUserInfoOffset;
DWORD dwHighLevelCompSize; // 0
DWORD dwHighLevelCompOffset;
DWORD dwLowLevelCompSize; // 0
DWORD dwLowLevelCompOffset;
DWORD dwDevSpecificSize; // 0
DWORD dwDevSpecificOffset;
DWORD dwPredictiveAutoTransferStates;
DWORD dwTargetAddressSize;
DWORD dwTargetAddressOffset;
DWORD dwSendingFlowspecSize;
DWORD dwSendingFlowspecOffset;
DWORD dwReceivingFlowspecSize;
DWORD dwReceivingFlowspecOffset;
DWORD dwDeviceClassSize;
DWORD dwDeviceClassOffset;
DWORD dwDeviceConfigSize;
DWORD dwDeviceConfigOffset;
DWORD dwCallDataSize;
DWORD dwCallDataOffset;
DWORD dwNoAnswerTimeout;
DWORD dwCallingPartyIDSize;
DWORD dwCallingPartyIDOffset;
} LINECALLPARAMS, FAR *LPLINECALLPARAMS;
Members
dwTotalSize
The total
size in bytes allocated to this data structure. This size should be big enough
to hold all the fixed and variably sized portions of this data structure.
dwBearerMode
The bearer
mode for the call. This field 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 via the Win32 comm functions, for the purpose of
configuring or using special features not otherwise supported by the service
provider.
If dwBearerMode
is 0, default value is LINEBEARERMODE_VOICE.
dwMinRate
dwMaxRate
The data rate
range requested for the call's data stream in bps (bits per second). When
making a call, the service provider attempts to provide the highest available
rate in the requested range. If a specific data rate is required, both min and
max should be set to that value. If an application works best with one rate but
is able to degrade to lower rates, the application should specify these as the
max and min rates respectively. If dwMaxRate is 0, the default value is
as specified by the dwMaxRate member of the LINEDEVCAPS structure. This is the
maximum rate supported by device.
dwMediaMode
The expected
media mode of the call. This field uses the following LINEMEDIAMODE_ constants:
LINEMEDIAMODE_UNKNOWN
A media stream
exists but its mode is not known. This would correspond 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 has been 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
is being sent or received 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.
If dwMediaMode is 0, the default value is LINEMEDIAMODE_INTERACTIVEVOICE.
dwCallParamFlags
These flags
specify a collection of Boolean call-setup parameters. This field uses the
following LINECALLPARAMFLAGS_ constants:
LINECALLPARAMFLAGS_SECURE
The call
should be set up as secure.
LINECALLPARAMFLAGS_IDLE
The call
should get an idle call appearance.
LINECALLPARAMFLAGS_BLOCKID
The
originator identity should be concealed (block caller ID).
LINECALLPARAMFLAGS_ORIGOFFHOOK
The
originator's phone should be automatically taken offhook.
LINECALLPARAMFLAGS_DESTOFFHOOK
The called
party's phone should be automatically taken offhook.
dwAddressMode
The mode by
which the originating address is specified. The dwAddressMode field
cannot be LINEADDRESSMODE_ADDRESSID for the function call lineOpen. This field uses the
following LINEADDRESSMODE_ constants:
LINEADDRESSMODE_ADDRESSID
The address
is specified with a small integer in the range 0 to dwNumAddresses minus
one, where dwNumAddresses is the value in the line's LINEDEVCAPS structure. The selected
address is specified in the dwAddressID field.
LINEADDRESSMODE_DIALABLEADDR
The address
is specified with its dialable address. The address is contained in the dwOrigAddressSize dwOrigAddressOffset variably sized
field. If dwAddressMode is 0, the default value is
LINEADDRESSMODE_ADDRESSID.
dwAddressID
The address
ID of the originating address if dwAddressMode is set to
LINEADDRESSMODE_ADDRESSID.
DialParams
Dial
parameters to be used on this call, of type LINEDIALPARAMS. When a value of zero is
specified for this field, the default value for the field is used as indicated
in the DefaultDialParams member of the LINEDEVCAPS structure. If a non-zero
value is specified for a field which is outside the range specified by the
corresponding fields in MinDialParams and MaxDialParams in the LINEDEVCAPS
structure, the nearest value within the valid range is used instead.
dwOrigAddressSize
dwOrigAddressOffset
The size in
bytes of the variably sized field holding the originating address, and the
offset in bytes from the beginning of this data structure. The format of this
address is dependent on the dwAddressMode field.
dwDisplayableAddressSize
dwDisplayableAddressOffset
The displayable
string is used for logging purposes. The content of these fields is recorded in
the dwDisplayableAddressOffset and dwDisplayableAddressSize
fields of the call's LINECALLINFO message. The lineTranslateAddress function returns
appropriate information to be placed in this field in the dwDisplayableAddressSize
and dwDisplayableAddressOffset fields of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset
The size in
bytes of the variably sized field holding called-party information, and the
offset in bytes from the beginning of this data structure. This information can
be specified by the application that makes the call and is made available in
the call's information structure for logging purposes. The format of this field
is that of dwStringFormat, as specified in LINEDEVCAPS.
dwCommentSize
dwCommentOffset
The size in
bytes of the variably sized field holding comments about the call, and the
offset in bytes from the beginning of this data structure. This information can
be specified by the application that makes the call and is made available in
the call's information structure for logging purposes. The format of this field
is that of dwStringFormat, as specified in LINEDEVCAPS.
dwUserUserInfoSize
dwUserUserInfoOffset
The size in
bytes of the variably sized field holding user-to-user information, and the offset
in bytes from the beginning of this data structure. The protocol discriminator
field for the user-user information, if required, should appear as the first
byte of the data pointed to by dwUserUserInfoOffset, and must be
accounted for in dwUserUserInfoSize.
dwHighLevelCompSize
dwHighLevelCompOffset
The size in
bytes of the variably sized field holding high-level compatibility information,
and the offset in bytes from the beginning of this data structure
dwLowLevelCompSize
dwLowLevelCompOffset
The size in
bytes of the variably sized field holding low-level compatibility information,
and the offset in bytes from the beginning of this data structure.
dwDevSpecificSize
dwDevSpecificOffset
The size in
bytes of the variably sized field holding device-specific information, and the
offset in bytes from the beginning of this data structure
dwPredictiveAutoTransferStates
The
LINECALLSTATE_ values, entry into which cause the call to be blind-transferred
to the specified target address. Set to 0 if automatic transfer is not desired.
dwTargetAddressSize
dwTargetAddressOffset
The size in
bytes and offset from the beginning of LINECALLPARAMS of a string
specifying the target dialable address (not dwAddressID); used in
the case of certain automatic actions. In the case of predictive dialing,
specifies the address to which the call should be automatically transferred.
This is essentially the same string that would be passed to lineBlindTransfer if automatic transfer were
not being used. Set to 0 if automatic transfer is not desired. In the case of a
No Hold Conference, specifies the address that should be conferenced to the
call. In the case of a One Step Transfer, specifies the address to dial on the
consultation call.
dwSendingFlowspecSize
dwSendingFlowspecOffset
The total
size in bytes and offset from the beginning of LINECALLPARAMS of a
WinSock2 FLOWSPEC structure followed by WinSock2 provider-specific data,
equivalent to what would have been stored in SendingFlowspec.len in a WinSock2 QOS
structure. Specifies the quality of service desired in the sending direction on
the call. The provider-specific portion following the FLOWSPEC structure
must not contain pointers to other blocks of memory, because TAPI will not know
how to marshal the data pointed to by the private pointer(s) and convey it
through interprocess communication to the application.
dwReceivingFlowspecSize
dwReceivingFlowspecOffset
The total
size in bytes and offset from the beginning of LINECALLPARAMS of a WinSock2
FLOWSPEC structure followed by WinSock2 provider-specific data,
equivalent to what would have been stored in ReceivingFlowspec.len in a
WinSock2 QOS structure. Specifies the quality of service desired in the
receiving direction on the call. The provider-specific portion following the FLOWSPEC
structure must not contain pointers to other blocks of memory, because TAPI
will not know how to marshal the data pointed to by the private pointer(s) and
convey it through interprocess communication to the application.
dwDeviceClassSize
dwDeviceClassOffset
The size in
bytes and offset from the beginning of LINECALLPARAMS of a
NULL-terminated ASCII string (the size includes the null) that indicates the
device class of the device whose configuration is specified in DeviceConfig.
Valid device class strings are the same as those specified for the lineGetID
function.
dwDeviceConfigSize
dwDeviceConfigOffset
The number of
bytes and offset from the beginning of LINECALLPARAMS of the opaque
configuration data structure pointed to by dwDevConfigOffset. This value
will have been returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig. If the size is 0, the
default device configuration is used. This allows the application to set the
device configuration before the call is initiated.
dwCallDataSize
dwCallDataOffset
The size in
bytes and offset from the beginning of LINECALLPARAMS of the
application-settable call data to be initially attached to the call.
dwNoAnswerTimeout
The number of
seconds, after the completion of dialing, that the call should be allowed to
wait in the PROCEEDING or RINGBACK states, before it is automatically abandoned
by the service provider with a LINECALLSTATE_DISCONNECTED and
LINEDISCONNECTMODE_NOANSWER. A value of 0 indicates that the application does
not desire automatic call abandonment.
dwCallingPartyIDSize
dwCallingPartyIDOffset
The size in
bytes and offset from the beginning of LINECALLPARAMS of a
NULL-terminated ASCII string (the size includes the null) that specifies the
identity of the party placing the call. The service provider will, if the
content of the ID is acceptable and a path is available, pass the ID along to
the called party to indicate the identity of the calling party.
Remarks
Device-specific
extensions should use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset)
variably sized area of this data structure.
This
structure is used as a parameter to lineMakeCall when setting up a call.
Its fields allow the application to specify the quality of service requested
from the network as well as a variety of ISDN call-setup parameters. If no LINECALLPARAMS
structure is supplied to lineMakeCall, a default POTS voice-grade call
is requested with the default values listed above.
Note The fields DialParams
through dwDevSpecificOffset are ignored when an lpCallParams
parameter is specified with the function lineOpen.
The members dwPredictiveAutoTransferStates
though dwCallingPartyIDOffset are available only to applications that
open the line device with an API version of 0x00020000 or greater.
See Also