LINECALLPARAMS  IS2B8Y

The LINECALLPARAMS structure describes parameters supplied when making calls using lineMakeCallCSIH7C. 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 LINEDEVCAPSBJCCRA 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 lineOpen85WLQP. 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 LINEDEVCAPSBJCCRA 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 LINEDIALPARAMS867G05. 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 LINEDEVCAPSBJCCRA 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 lineTranslateAddress7VLD64 function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset fields of the LINETRANSLATEOUTPUT2_GZMO4 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 LINEDEVCAPSBJCCRA.

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 lineBlindTransfer0JTT52 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 VARSTRINGFZOPJB structure returned by lineGetDevConfig19SYTUS. 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

lineBlindTransfer, LINEDEVCAPS, LINEDIALPARAMS, lineGetDevConfig, lineMakeCall, lineOpen, lineTranslateAddress, LINETRANSLATEOUTPUT, VARSTRING