LINECALLPARAMS structure (tapi.h)

The LINECALLPARAMS structure describes parameters supplied when making calls using the lineMakeCall and TSPI_lineMakeCall functions. The LINECALLPARAMS structure is also used as a parameter in other operations, such as the lineOpen function.

The comments to the right of the syntax block indicate the default values used when this structure is not provided to lineMakeCall.

Syntax

typedef struct linecallparams_tag {
  DWORD          dwTotalSize;
  DWORD          dwBearerMode;
  DWORD          dwMinRate;
  DWORD          dwMaxRate;
  DWORD          dwMediaMode;
  DWORD          dwCallParamFlags;
  DWORD          dwAddressMode;
  DWORD          dwAddressID;
  LINEDIALPARAMS DialParams;
  DWORD          dwOrigAddressSize;
  DWORD          dwOrigAddressOffset;
  DWORD          dwDisplayableAddressSize;
  DWORD          dwDisplayableAddressOffset;
  DWORD          dwCalledPartySize;
  DWORD          dwCalledPartyOffset;
  DWORD          dwCommentSize;
  DWORD          dwCommentOffset;
  DWORD          dwUserUserInfoSize;
  DWORD          dwUserUserInfoOffset;
  DWORD          dwHighLevelCompSize;
  DWORD          dwHighLevelCompOffset;
  DWORD          dwLowLevelCompSize;
  DWORD          dwLowLevelCompOffset;
  DWORD          dwDevSpecificSize;
  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;
  DWORD          dwAddressType;
} LINECALLPARAMS, *LPLINECALLPARAMS;

Members

dwTotalSize

Total size allocated to this data structure, in bytes. This size should be big enough to hold all the fixed and variably sized portions of this data structure.

dwBearerMode

Bearer mode for the call. This member uses one of the LINEBEARERMODE_ constants.

If dwBearerMode is zero, the default value is LINEBEARERMODE_VOICE.

dwMinRate

Minimum data rate requested for the call's data stream, in bps (bits per second).

dwMaxRate

Maximum data rate 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 (dwMinRate to dwMaxRate). If a specific data rate is required, both dwMinRate and dwMaxRate 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 maximum and minimum rates, respectively. If dwMaxRate is zero, the default value is as specified by the dwMaxRate member of the LINEDEVCAPS structure. This is the maximum rate supported by the device.

dwMediaMode

Expected media type of the call. This member uses one of the LINEMEDIAMODE_ constants.

If dwMediaMode is zero, the default value is LINEMEDIAMODE_INTERACTIVEVOICE.

dwCallParamFlags

Collection of Boolean call-setup parameters. This member uses one or more of the LINECALLPARAMFLAGS_ constants.

dwAddressMode

Mode by which the originating address is specified. This member uses one of the LINEADDRESSMODE_ constants.

Note  The dwAddressMode member cannot be LINEADDRESSMODE_ADDRESSID for the lineOpen function call. However, this restriction does not apply to lineMakeCall.
 

dwAddressID

Address identifier of the originating address if dwAddressMode is set to LINEADDRESSMODE_ADDRESSID. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.

DialParams

Dial parameters to be used on this call, of type LINEDIALPARAMS. When a value of 0 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 nonzero value is specified for a field that 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

Size of the originating address field, in bytes.

dwOrigAddressOffset

Offset from the beginning of the structure to the variably sized field holding the originating address. The format of this address is dependent on the dwAddressMode member. The size of the field is specified by dwOrigAddressSize.

dwDisplayableAddressSize

Size of the displayable string including the null terminator, in bytes.

dwDisplayableAddressOffset

Displayable string used for logging purposes. The content of these members is recorded in the dwDisplayableAddressOffset and dwDisplayableAddressSize members of the call's LINECALLINFO message. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure. The size of the field is specified by dwDisplayableAddressSize.

dwCalledPartySize

Size of the called-party information, in bytes.

dwCalledPartyOffset

Offset from the beginning of the structure to to the variably sized field holding called-party information. 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. The size of the field is specified by dwCalledPartySize.

dwCommentSize

Size of the call comment field, in bytes.

dwCommentOffset

Offset from the beginning of the structure to the variably sized field holding comments about the call. 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. The size of the field is specified by dwCommentSize.

dwUserUserInfoSize

Size of the user-user information including the null terminator, in bytes.

dwUserUserInfoOffset

Offset from the beginning of the structure to the variably sized field holding user-user information. 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

Size of the high-level compatibility information, in bytes.

dwHighLevelCompOffset

Offset from the beginning of the structure to the variably sized field holding high-level compatibility information. The size of the field is specified by dwHighLevelCompSize.

dwLowLevelCompSize

Size of the low-level compatibility information, in bytes.

dwLowLevelCompOffset

Offset from the beginning of the structure to the variably sized field holding low-level compatibility information. The size of the field is specified by dwLowLevelCompSize.

dwDevSpecificSize

Size of the device-specific information, in bytes.

dwDevSpecificOffset

Offset from the beginning of the structure to the variably sized field holding device-specific information. The size of the field is specified by dwDevSpecificSize.

dwPredictiveAutoTransferStates

LINECALLSTATE_ constants, entry into which causes the call to be blind-transferred to the specified target address. Set to zero if automatic transfer is not desired.

dwTargetAddressSize

Size of the target dialable address string including the null terminator, in bytes.

dwTargetAddressOffset

Offset from the beginning of the structure to 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. The size of the string is specified by dwTargetAddressSize.

This is essentially the same string that would be passed to lineBlindTransfer if automatic transfer were not being used. Set to zero 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

Size of the quality of service information, in bytes.

dwSendingFlowspecOffset

Offset from the beginning of the structure to a FLOWSPEC structure followed by WinSock provider-specific data, equivalent to what would have been stored in SendingFlowspec in a 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 does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application. The size of the field is specified by dwSendingFlowspecSize.

dwReceivingFlowspecSize

Size of the quality of service information, in bytes.

dwReceivingFlowspecOffset

Offset from the beginning of the structure to a FLOWSPEC structure followed by WinSock provider-specific data, equivalent to what would have been stored in ReceivingFlowspec in a 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 does not know how to marshal the data pointed to by the private pointer(s) and convey it through interprocess communication to the application. The size of the field is specified by dwReceivingFlowspecSize.

dwDeviceClassSize

Size of the device class string including the null terminator, in bytes.

dwDeviceClassOffset

Offset from the beginning of the structure to a null-terminated string 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. The size of the string is specified by dwDeviceClassSize.

dwDeviceConfigSize

Size of the device configuration data, in bytes.

dwDeviceConfigOffset

Offset from the beginning of the structure to the opaque configuration data structure. This value is returned in the dwStringSize member in the VARSTRING structure returned by lineGetDevConfig. If the size is zero, the default device configuration is used. This allows the application to set the device configuration before the call is initiated. The size of the field is specified by dwDeviceConfigSize.

dwCallDataSize

Size of the application-settable call data, in bytes.

dwCallDataOffset

Offset from the beginning of the structure to the application-settable call data to be initially attached to the call. The size of the field is specified by dwCallDataSize.

dwNoAnswerTimeout

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

Size of the calling-party ID string including the null terminator, in bytes, including the null-terminating character.

dwCallingPartyIDOffset

Offset from the beginning of the structure to a null-terminated string that specifies the identity of the party placing the call. If the content of the identifier is acceptable and a path is available, the service provider passes the identifier along to the called party to indicate the identity of the calling party. The size of the field is specified by dwCallingPartyIDSize.

dwAddressType

Address type used for the call. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.

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 lineOpen function.
 
The members dwPredictiveAutoTransferStates through dwCallingPartyIDOffset are available only to applications that open the line device with an API version of 2.0 or later.

Requirements

   
Header tapi.h

See also

LINEDEVCAPS

LINEDIALPARAMS

LINETRANSLATEOUTPUT

TSPI_lineMakeCall

VARSTRING

lineBlindTransfer

lineGetDevConfig

lineGetID

lineMakeCall

lineOpen

lineTranslateAddress