Platform SDK: TAPI

LINECALLINFO

The LINECALLINFO structure contains information about a call. This information remains relatively fixed for the duration of the call. Multiple functions use LINECALLINFO. The structure is returned by the lineGetCallInfo function and the TSPI_lineGetCallInfo function. If a part of the structure does change, then a LINE_CALLINFO message is sent to the application indicating which information item has changed.

Dynamically changing information about a call, such as call progress status, is available in the LINECALLSTATUS structure, returned by a call to the lineGetCallStatus function.

typedef struct linecallinfo_tag {
  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize;

 HLINE  hLine;
  DWORD  dwLineDeviceID;
  DWORD  dwAddressID;

  DWORD  dwBearerMode;
  DWORD  dwRate;
   DWORD  dwMediaMode;

  DWORD  dwAppSpecific;
  DWORD  dwCallID;
  DWORD  dwRelatedCallID;
  DWORD  dwCallParamFlags;
  DWORD  dwCallStates;

  DWORD  dwMonitorDigitModes;
  DWORD  dwMonitorMediaModes;
 LINEDIALPARAMS  DialParams;

  DWORD  dwOrigin;
  DWORD  dwReason;
  DWORD  dwCompletionID;

  DWORD  dwNumOwners;
  DWORD  dwNumMonitors;

  DWORD  dwCountryCode;
  DWORD  dwTrunk;

  DWORD  dwCallerIDFlags;
  DWORD  dwCallerIDSize;
  DWORD  dwCallerIDOffset;
  DWORD  dwCallerIDNameSize;
  DWORD  dwCallerIDNameOffset;

  DWORD  dwCalledIDFlags;
  DWORD  dwCalledIDSize;
  DWORD  dwCalledIDOffset;
  DWORD  dwCalledIDNameSize;
  DWORD  dwCalledIDNameOffset;

  DWORD  dwConnectedIDFlags;
  DWORD  dwConnectedIDSize;
  DWORD  dwConnectedIDOffset;
  DWORD  dwConnectedIDNameSize;
  DWORD  dwConnectedIDNameOffset;

  DWORD  dwRedirectionIDFlags;
  DWORD  dwRedirectionIDSize;
  DWORD  dwRedirectionIDOffset;
  DWORD  dwRedirectionIDNameSize;
  DWORD  dwRedirectionIDNameOffset;

  DWORD  dwRedirectingIDFlags;
  DWORD  dwRedirectingIDSize;
  DWORD  dwRedirectingIDOffset;
  DWORD  dwRedirectingIDNameSize;
  DWORD  dwRedirectingIDNameOffset;

  DWORD  dwAppNameSize;
  DWORD  dwAppNameOffset;
  DWORD  dwDisplayableAddressSize; 
  DWORD  dwDisplayableAddressOffset; 
 
  DWORD  dwCalledPartySize;
  DWORD  dwCalledPartyOffset;

  DWORD  dwCommentSize;
  DWORD  dwCommentOffset;

  DWORD  dwDisplaySize;
  DWORD  dwDisplayOffset;

  DWORD  dwUserUserInfoSize;
  DWORD  dwUserUserInfoOffset;

  DWORD  dwHighLevelCompSize;
  DWORD  dwHighLevelCompOffset;

  DWORD  dwLowLevelCompSize;
  DWORD  dwLowLevelCompOffset;

  DWORD  dwChargingInfoSize;
  DWORD  dwChargingInfoOffset;

  DWORD  dwTerminalModesSize;
  DWORD  dwTerminalModesOffset;

  DWORD  dwDevSpecificSize;
  DWORD  dwDevSpecificOffset;

  DWORD  dwCallTreatment;

  DWORD  dwCallDataSize;
  DWORD  dwCallDataOffset;

  DWORD  dwSendingFlowspecSize;
  DWORD  dwSendingFlowspecOffset;

  DWORD  dwReceivingFlowspecSize;
  DWORD  dwReceivingFlowspecOffset;

  DWORD  dwCallerIDAddressType;      //TAPI Version 3.0
  DWORD  dwCalledIDAddressType;      //TAPI Version 3.0
  DWORD  dwConnectedIDAddressType;   //TAPI Version 3.0
  DWORD  dwRedirectionIDAddressType; //TAPI Version 3.0
  DWORD  dwRedirectingIDAddressType; //TAPI Version 3.0

} LINECALLINFO, FAR *LPLINECALLINFO;

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.
hLine: The handle for the line device with which this call is associated.
dwLineDeviceID: The device identifier of the line device with which this call is associated.
dwAddressID: The address identifier of the address on the line on which this call exists. An address identifier is permanently associated with an address; the identifier remains constant across operating system upgrades.
dwBearerMode: The current bearer mode of the call. This member uses one of the LINEBEARERMODE_ constants.
dwRate: The rate of the call's data stream in bps (bits per second).
dwMediaMode: Specifies the media type of the information stream currently on the call. This is the media type as determined by the owner of the call, which is not necessarily the same as that of the last LINE_MONITORMEDIA message. This member is not directly affected by the LINE_MONITORMEDIA messages. This member uses the LINEMEDIAMODE_ constants.
dwAppSpecific: Not interpreted by the API implementation and service provider. It can be set by any owner application of this call with the lineSetAppSpecific function.
dwCallID: In some telephony environments, the switch or service provider can assign a unique identifier to each call. This allows the call to be tracked across transfers, forwards, or other events. The domain of these call IDs and their scope is service provider-defined. The dwCallID member makes this unique identifier available to the applications.
dwRelatedCallID: Telephony environments that use the call ID often may find it necessary to relate one call to another. The dwRelatedCallID member may be used by the service provider for this purpose.
dwCallParamFlags: A collection of call-related parameters when the call is outgoing. These are the same call parameters specified in lineMakeCall, one or more of the LINECALLPARAMFLAGS_ constants.
dwCallStates: The call states, one or more of the 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.
dwMonitorDigitModes: The various digit modes, one or more of the LINEDIGITMODE_ constants, for which monitoring is currently enabled.
dwMonitorMediaModes: The various media types for which monitoring is currently enabled, one or more of the LINEMEDIAMODE_ constants.
DialParams: The dialing parameters currently in effect on the call, of type LINEDIALPARAMS. Unless these parameters are set by either lineMakeCall or lineSetCallParams, their values are the same as the defaults used in the LINEDEVCAPS structure.
dwOrigin: Identifies where the call originated, one of the LINECALLORIGIN_ constants.
dwReason: The reason why the call occurred, one of the LINECALLREASON_ constants.
dwCompletionID: 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: The number of application modules with different call handles with owner privilege for the call.
dwNumMonitors: The number of application modules with different call handles with monitor privilege for the call.
dwCountryCode: The country code of the destination party. Zero if unknown.
dwTrunk: 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: Determines the validity and content of the caller, or originator, party identifier information. This member uses one of the LINECALLPARTYID_ constants.
dwCallerIDSize
dwCallerIDOffset: The size, in bytes, of the variably sized field containing the caller party ID number information, and the offset, in bytes, from the beginning of this data structure.
dwCallerIDNameSize
dwCallerIDNameOffset: The size, in bytes, of the variably sized field containing the caller party ID name information, and the offset, in bytes, from the beginning of this data structure.
dwCalledIDFlags: Determines the validity and content of the called-party ID information. The called party corresponds to the originally addressed party. This member uses one of the LINECALLPARTYID_ constants.
dwCalledIDSize
dwCalledIDOffset: The size, in bytes, of the variably sized field containing the called-party ID number information, and the offset, in bytes, from the beginning of this data structure.
dwCalledIDNameSize
dwCalledIDNameOffset: The size, in bytes, of the variably sized field containing the called-party ID name information, and the offset, in bytes, from the beginning of this data structure.
dwConnectedIDFlags: Determines the validity and content of the connected party ID information. The connected party is the party that was actually connected to. This may be different from the called-party ID if the call was diverted. This member uses one of the LINECALLPARTYID_ constants.
dwConnectedIDSize
dwConnectedIDOffset: The size, in bytes, of the variably sized field containing the connected party identifier number information, and the offset, in bytes, from the beginning of this data structure.
dwConnectedIDNameSize
dwConnectedIDNameOffset: The size, in bytes, of the variably sized field containing the connected party identifier name information, and the offset, in bytes, from the beginning of this data structure.
dwRedirectionIDFlags: Determines the validity and content of the redirection party identifier information. The redirection party identifies the address to which the session was redirected. This member uses one of the LINECALLPARTYID_ constants.
dwRedirectionIDSize
dwRedirectionIDOffset: The size, in bytes, of the variably sized field containing the redirection party identifier number information, and the offset, in bytes, from the beginning of this data structure.
dwRedirectionIDNameSize
dwRedirectionIDNameOffset: The size, in bytes, of the variably sized field containing the redirection party identifier name information, and the offset, in bytes, from the beginning of this data structure.
dwRedirectingIDFlags: Determines the validity and content of the redirecting party identifier information. The redirecting party identifies the address which redirect the session. This member uses one of the LINECALLPARTYID_ constants.
dwRedirectingIDSize
dwRedirectingIDOffset: The size, in bytes, of the variably sized field containing the redirecting party identifier number information, and the offset, in bytes, from the beginning of this data structure.
dwRedirectingIDNameSize
dwRedirectingIDNameOffset: The size, in bytes, of the variably sized field containing the redirecting party identifier name information, and the offset, in bytes, from the beginning of this data structure.
dwAppNameSize
dwAppNameOffset: The size, in bytes, and the offset, in bytes, from the beginning of this data structure of the variably sized field holding the user-friendly application name of the application that first originated, accepted, or answered the call. This is the name that an application can specify in lineInitializeEx. If the application specifies no such name, then the application's module filename is used instead.
dwDisplayableAddressSize
dwDisplayableAddressOffset: The displayable string is used for logging purposes. The information is obtained from LINECALLPARAMS for functions that initiate calls. The lineTranslateAddress function returns appropriate information to be placed in this field in the dwDisplayableAddressSize and dwDisplayableAddressOffset members of the LINETRANSLATEOUTPUT structure.
dwCalledPartySize
dwCalledPartyOffset: The size, in bytes, of the variably sized field holding a user-friendly description of the called party, and the offset, in bytes, from the beginning of this data structure. This information can be specified with lineMakeCall and can be optionally specified in the lpCallParams parameter whenever a new call is established. It is useful for call logging purposes.
dwCommentSize
dwCommentOffset: The size, in bytes, of the variably sized field holding a comment about the call provided by the application that originated the call using lineMakeCall, and the offset, in bytes, from the beginning of this data structure. This information can be optionally specified in the lpCallParams parameter whenever a new call is established.
dwDisplaySize
dwDisplayOffset: The size, in bytes, of the variably sized field holding raw display information, and the offset, in bytes, from the beginning of this data structure. Depending on the telephony environment, a service provider may extract functional information from this member pair for formatting and presentation most appropriate for this telephony configuration.
dwUserUserInfoSize
dwUserUserInfoOffset: The size, in bytes, of the variably sized field holding user-user information, and the offset, in bytes, from the beginning of this data structure The protocol discriminator field for the user-user information, if used, appears as the first byte of the data pointed to by dwUserUserInfoOffset, and is 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. The format of this information is specified by other standards (ISDN Q.931).
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. The format of this information is specified by other standards (ISDN Q.931).
dwChargingInfoSize
dwChargingInfoOffset: The size, in bytes, of the variably sized field holding charging information, and the offset, in bytes, from the beginning of this data structure. The format of this information is specified by other standards (ISDN Q.931).
dwTerminalModesSize
dwTerminalModesOffset: The size, in bytes, of the variably sized device field containing an array with DWORD-sized entries, and the offset, in bytes, from the beginning of this data structure. Array entries are indexed by terminal identifiers, in the range from zero to one less than dwNumTerminals. Each entry in the array specifies the current terminal modes for the corresponding terminal set with the lineSetTerminal function for this call's media stream, as specified by one of the LINETERMMODE_ constants.
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.
dwCallTreatment: The call treatment currently being applied on the call or that is applied when the call enters the next applicable state. Can be zero if call treatments are not supported.
dwCallDataSize
dwCallDataOffset: The size, in bytes, and offset from the beginning of LINECALLINFO of the application-settable call data.
dwSendingFlowspecSize
dwSendingFlowspecOffset: The total size, in bytes, and offset from the beginning of LINECALLINFO 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 current in effect 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.
dwReceivingFlowspecSize
dwReceivingFlowspecOffset: The total size, in bytes, and offset from the beginning of LINECALLINFO 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 current in effect 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.
dwCallerIDAddressType: The address type of the caller. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
dwCalledIDAddressType: The address type of the called party. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
dwConnectedIDAddressType: The address type of the destination to which the call was actually connected. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
dwRedirectionIDAddressType: The address type of the new call destination. This member of the structure is available only if the negotiated TAPI version is 3.0 or higher.
dwRedirectingIDAddressType: The address type of the location which redirected 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.

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

The members dwCallTreatment through dwReceivingFlowspecOffset are available only to applications that open the line device with an API version of 2.0 or later.

Note The preferred format for specification of the contents of the dwCallID field and the other five similar fields (dwCallerIDFlag, dwCallerIDSize, dwCallerIDOffset, dwCallerIDNameSize, and dwCallerIDNameOffset) is the TAPI canonical number format. For example, a ICLID of "4258828080" received from the switch should be converted to "+1 (425) 8828080" before being placed in the LINECALLINFO structure. This standardized format facilitates searching of databases and callback functions implemented in applications.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
  Windows 95/98: Requires Windows 95 or later.
  Version: Requires TAPI 1.4 or later.
  Header: Declared in Tapi.h.

LINECALLINFO

Members

Remarks

Requirements

See Also