2.2.6.19 LINECALLINFO

The LINECALLINFO packet MUST contain call data. This data remains fixed during the call and is obtained with the GetCallInfo packet. If a part of the packet does change, then a LINE_CALLINFO packet is sent indicating which data item has changed. Dynamically changing call data, such as call progress status, is available in the LINECALLSTATUS packet, returned with the GetCallStatus packet.

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

dwNeededSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, for this packet needed to contain 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.

hLine (4 bytes): An unsigned 32-bit integer. The handle for the line device with which this call is associated.

dwLineDeviceID (4 bytes): An unsigned 32-bit integer. The device identifier of the line device with which this call is associated.

dwAddressID (4 bytes): An unsigned 32-bit integer. The address identifier of the address on the line on which this call exists.

dwBearerMode (4 bytes): An unsigned 32-bit integer. The value that specifies the current bearer mode of the call. It MUST use LINE_CALLINFO

dwRate (4 bytes): An unsigned 32-bit integer. The rate, in bits per second (bps), of the call data stream.

dwMediaMode (4 bytes): An unsigned 32-bit integer. The value that specifies the media mode of the data stream currently on the call. This is the media mode determined by the owner of the call, which is not necessarily the same as that of the last LINE_MONITORMEDIA packet. This member is not directly affected by the LINE_MONITORMEDIA packets. It MUST use one or more of the LINEMEDIAMODE_Constants.

dwAppSpecific (4 bytes): An unsigned 32-bit integer. The opaque, client-specified value uninterpreted by the protocol.

dwCallID (4 bytes): An unsigned 32-bit integer. In some telephony environments, the switch, or service provider, can assign a unique identifier to each call. This enables the call to be tracked across transfers, forwards, or other events. The domain of these call identifiers and their scope is service provider-defined. The dwCallID member makes this unique identifier available.

dwRelatedCallID (4 bytes): An unsigned 32-bit integer. Telephony environments that use the call identifier can find it necessary to relate one call to another. The dwRelatedCallID member can be used by the service provider for this purpose.

dwCallParamFlags (4 bytes): An unsigned 32-bit integer. This field specifies a collection of call-related parameters when the call is outgoing. These are the same call parameters specified in the MakeCall packet This member MUST use LINECALLPARAMFLAGS_Constants.

dwCallStates (4 bytes): An unsigned 32-bit integer. The value that specifies the call states of type LINECALLSTATE_Constants for which the application can be notified on this call. The dwCallStates member is constant in LINECALLINFO and does not change depending on the call state. It MUST use LINECALLSTATE_Constants.

dwMonitorDigitModes (4 bytes): An unsigned 32-bit integer. The value that specifies the various digit modes using LINEDIGITMODE_Constants.

dwMonitorMediaModes (4 bytes): An unsigned 32-bit integer. This field specifies the various media modes for which monitoring is currently enabled using LINEMEDIAMODE_Constants.

DialParams (16 bytes): A LINEDIALPARAMS. The dialing parameters currently in effect on the call, of type LINEDIALPARAMS. Unless these parameters are set by either MakeCall or the SetCallParams packet, their values MUST be the same as the defaults used in the LINEDEVCAPS packet.

dwOrigin (4 bytes): An unsigned 32-bit integer. The value that identifies where the call originated. It uses  one or more of the LINECALLORIGIN_Constants.

dwReason (4 bytes): An unsigned 32-bit integer. The value that specifies the reason why the call occurred. It uses one or more of the LINECALLREASON_Constants.

dwCompletionID (4 bytes): An unsigned 32-bit integer. The value that specifies the completion identifier for the incoming call if it is the result of a completion request that terminates. This identifier is meaningful only if dwReason is LINECALLREASON_CALLCOMPLETION.

dwNumOwners (4 bytes): An unsigned 32-bit integer. The number of application modules with different call handles that have owner privilege for the call.

dwNumMonitors (4 bytes): An unsigned 32-bit integer. The number of application modules with different call handles with monitor privilege for the call.

dwCountryCode (4 bytes): An unsigned 32-bit integer. The country or region code of the destination party. Zero if unknown.

dwTrunk (4 bytes): An unsigned 32-bit integer. The number of the trunk over which the call is routed. This member is used for both incoming and outgoing calls. The dwTrunk member SHOULD be set to 0xFFFFFFFF if it is unknown.

dwCallerIDFlags (4 bytes): An unsigned 32-bit integer. The value that determines the validity and content of the caller party identifier data. The caller is the originator of the call. It MUST use one or more of the LINECALLPARTYID_Constants.

dwCallerIDSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the data identifying the caller.

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

dwCallerIDNameSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the data identifying the name of the calling party.

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

dwCalledIDFlags (4 bytes): An unsigned 32-bit integer. The value that determines the validity and content of the called-party identifier data. The called party corresponds to the originally addressed party. It uses one or more of the LINECALLPARTYID_Constants.

dwCalledIDSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the called-party identifier number data.

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

dwCalledIDNameSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the called-party identifier name data.

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

dwConnectedIDFlags (4 bytes): An unsigned 32-bit integer. The value that determines the validity and content of the connected-party identifier data. The connected party is the party to which the connection was made. This can be different from the called-party identifier if the call was diverted. It uses one or more of the LINECALLPARTYID_Constants.

dwConnectedIDSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the connected-party identifier number data.

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

dwConnectedIDNameSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the connected-party identifier name data.

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

dwRedirectionIDFlags (4 bytes): An unsigned 32-bit integer. The value that determines the validity and content of the redirection-party identifier data. The redirection party identifies to the calling user the number toward which diversion was invoked. It uses one or more of the LINECALLPARTYID_Constants.

dwRedirectionIDSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the redirection-party identifier number data.

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

dwRedirectionIDNameSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the redirection-party identifier name data.

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

dwRedirectingIDFlags (4 bytes): An unsigned 32-bit integer. The value that determines the validity and content of the redirection-party identifier data. The party that received the call identifies the new destination number or whatever data is detected to the call originator. It uses one or more of the LINECALLPARTYID_Constants.

dwRedirectingIDSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the redirection-party identifier number data.

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

dwRedirectingIDNameSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that contains the redirection-party identifier name data.

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

dwAppNameSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that holds the application name of the application that first originated, accepted, or answered the call.

dwAppNameOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. This is the name that an application can specify in the Initialize packet. If the application specifies no such name, then the application's module file name is used.

dwDisplayableAddressSize (4 bytes): An unsigned 32-bit integer. This field specifies the displayable string that is used for logging purposes. The data is obtained from LINECALLPARAMS for functions that initiate calls.

dwDisplayableAddressOffset (4 bytes): An unsigned 32-bit integer. This field specifies the displayable string that is used for logging purposes. The data is obtained from LINECALLPARAMS for functions that initiate calls.

dwCalledPartySize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that holds a user-friendly description of the called party.

dwCalledPartyOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. This data can be specified with the MakeCall packet and can be optionally specified in the lpCallParams parameter whenever a new call is established. It is useful for call logging purposes.

dwCommentSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that holds a comment about the call that is provided by the application that originated the call using the MakeCall packet.

dwCommentOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. This data can be optionally specified in the lpCallParams parameter using the MakeCall packet whenever a new call is established.

dwDisplaySize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that holds raw display data.

dwDisplayOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. Depending on the telephony environment, a service provider can extract functional data from this member pair for formatting and presentation that is most appropriate for this telephony configuration.

dwUserUserInfoSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that holds user-user data.

dwUserUserInfoOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. The protocol discriminator field for the user-user data, if used, appears as the first byte of the data pointed to by dwUserUserInfoOffset and is accounted for in dwUserUserInfoSize.

dwHighLevelCompSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that holds high-level compatibility data.

dwHighLevelCompOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. The format of this data MUST be specified by other standards (ISDN Q.931).

dwLowLevelCompSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that holds low-level compatibility data.

dwLowLevelCompOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. The format of this data MUST be specified by other standards (ISDN Q.931).

dwChargingInfoSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the field that holds charging data.

dwChargingInfoOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. The format of this data MUST be specified by other standards (ISDN Q.931).

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

dwTerminalModesOffset (4 bytes): An unsigned 32-bit integer. The offset, in bytes, from the beginning of this packet. The set of LINETERMMODE is indexed by terminal identifiers, in the range from 0 to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the SetTerminal packet for this call's media stream. The following values are predefined.

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

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

dwCallTreatment (4 bytes): An unsigned 32-bit integer. The call treatment currently being applied on the call or that is applied when the call enters the next applicable state. Can be 0 if call treatments are not supported.

dwCallDataSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the application-settable call data.

dwCallDataOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of the packet to the application-settable call data. The size of the field is specified by dwCallDataSize.

dwSendingFlowspecSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the quality of service information.

dwSendingFlowspecOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of the packet to a FLOWSPEC packet followed by Winsock provider-specific data, equivalent to what would have been stored in SendingFlowspec in a QoS packet. Specifies the quality of service currently in effect in the sending direction on the call. The size of the field is specified by dwSendingFlowspecSize.

dwReceivingFlowspecSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the QoS information.

dwReceivingFlowspecOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of the packet to a FLOWSPEC packet followed by Winsock provider-specific data, equivalent to what would have been stored in ReceivingFlowspec in a QoS packet. Specifies the quality of service currently in effect in the receiving direction on the call. The size of the field is specified by dwReceivingFlowspecSize.

dwCallerIDAddressType (4 bytes): An unsigned 32-bit integer. The address type of the caller. This MUST use one of the LINEADDRESSTYPE_Constants. This member of the packet is available only if the negotiated TAPI version is 3.0 or 3.1.

dwCalledIDAddressType (4 bytes): An unsigned 32-bit integer. The address type of the called party. This MUST use one of the LINEADDRESSTYPE_Constants. This member of the packet is available only if the negotiated TAPI version is 3.0 or 3.1.

dwConnectedIDAddressType (4 bytes): An unsigned 32-bit integer. The address type of the destination to which the call was actually connected. This MUST use one of the LINEADDRESSTYPE_Constants. This member of the packet is available only if the negotiated TAPI version is 3.0 or 3.1.

dwRedirectionIDAddressType (4 bytes): An unsigned 32-bit integer. The address type of the new call destination. This member of the packet is available only if the negotiated TAPI version is 3.0 or 3.1.

dwRedirectingIDAddressType (4 bytes): An unsigned 32-bit integer. The address type of the location that redirected the call. This member of the packet is available only if the negotiated TAPI version is 3.0 or 3.1.

Device-specific extensions SHOULD use the DevSpecific (dwDevSpecificSize and dwDevSpecificOffset) variably sized area of this packet.

The LINECALLINFO packet contains relatively fixed data about a call. This packet is returned with the GetCallInfo packet. When data items in this packet have changed, a LINECALLINFO packet is sent to the application. A parameter to this packet is the data item or field that changed.

The fields dwCallTreatment through dwReceivingFlowspecOffset are available only to applications that open the line device with a TAPI version of 2.0, 2.1, 2.2, 3.0, or 3.1.

Note The preferred format for specification of the contents of the dwCallID member and the other five similar members (dwCallerIDFlag, dwCallerIDSize, dwCallerIDOffset, dwCallerIDNameSize, and dwCallerIDNameOffset) is the TAPI canonical number format. For example, an incoming call line identification (ICLID) of 5551234567 received from the switch SHOULD be converted to "+1 (555) 1234567" before being placed in the LINECALLINFO packet. This standardized format facilitates searching of databases and call-back functions implemented in applications.