2.2.6.6 LINEADDRESSCAPS

The LINEADDRESSCAPS packet describes the capabilities of a specified address. LINEADDRESSCAPS is supplied by the server in the field VarData of the returned version of the GetAddressCaps packet if the request is completed successfully.

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

dwNeededSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, for this packet that is needed to hold all the returned information.

dwUsedSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the portion of this packet that contains useful information.

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

dwAddressSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the address field.

dwAddressOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of the packet to the variably sized address field. The size of the field MUST be specified by dwAddressSize.

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

dwDevSpecificOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of the packet to the variably sized device-specific field. The size of the field MUST be specified by dwDevSpecificSize.

dwAddressSharing (4 bytes): An unsigned 32-bit integer. The sharing mode of the address. This member MUST be one of the LINEADDRESSSHARING_Constants.

dwAddressStates (4 bytes): An unsigned 32-bit integer. When the address state changes, the application can get notified in the LINE_ADDRESSSTATE packet. This member MUST use one or more of the LINEADDRESSSTATE_Constants.

dwCallInfoStates (4 bytes): An unsigned 32-bit integer. The call information elements that are meaningful for all calls on this address. An application can get notified about changes in some of these states in LINE_CALLINFO packets. This member MUST use one or more of the LINECALLINFOSTATE_Constants.

dwCallerIDFlags (4 bytes): An unsigned 32-bit integer. The party identifier information types that can be provided for calls on this address. The caller MUST be the originator of the session. MUST be one or more of the LINECALLPARTYID_Constants.

dwCalledIDFlags (4 bytes): An unsigned 32-bit integer. The party identifier information types that can be provided for calls on this address. Here, "called" refers to the original destination. MUST be one or more of the LINECALLPARTYID_Constants.

dwConnectedIDFlags (4 bytes): An unsigned 32-bit integer. The party identifier information types that can be provided for calls on this address. MUST be one or more of the LINECALLPARTYID_Constants.

dwRedirectionIDFlags (4 bytes): An unsigned 32-bit integer. The party identifier information types that can be provided for calls on this address. Here, "redirection" is the new destination. MUST be one or more of the LINECALLPARTYID_Constants.

dwRedirectingIDFlags (4 bytes): An unsigned 32-bit integer. The party identifier information types that can be provided for calls on this address. Here, "redirecting" is the address that invoked redirection. MUST be one or more of the LINECALLPARTYID_Constants.

dwCallStates (4 bytes): An unsigned 32-bit integer. The call states that can be reported for calls on this address. This member MUST use one or more of the LINECALLSTATE_Constants.

dwDialToneModes (4 bytes): An unsigned 32-bit integer. The dial tone modes that can be reported for calls made on this address. This member is meaningful only if the dial tone call state can be reported. This member MUST use one or more of the LINEDIALTONEMODE_Constants.

dwBusyModes (4 bytes): An unsigned 32-bit integer. The busy modes that can be reported for calls made on this address. This member is meaningful only if the busy call state can be reported. This member MUST use one or more of the LINEBUSYMODE_Constants.

dwSpecialInfo (4 bytes): An unsigned 32-bit integer. The special information types that can be reported for calls made on this address. This member is meaningful only if the specialInfo call state can be reported. This member MUST use one or more of the LINESPECIALINFO_Constants.

dwDisconnectModes (4 bytes): An unsigned 32-bit integer. The disconnect modes that can be reported for calls that are made on this address. This member is meaningful only if the disconnected call state can be reported. This member MUST use one or more of the LINEDISCONNECTMODE_Constants.

dwMaxNumActiveCalls (4 bytes): An unsigned 32-bit integer. The maximum number of active call appearances that the address can handle. This number does not include calls on hold or calls on hold pending transfer or conference.

dwMaxNumOnHoldCalls (4 bytes): An unsigned 32-bit integer. The maximum number of call appearances at the address that can be on hold.

dwMaxNumOnHoldPendingCalls (4 bytes): An unsigned 32-bit integer. The maximum number of call appearances at the address that can be on hold pending transfer or conference.

dwMaxNumConference (4 bytes): An unsigned 32-bit integer. The maximum number of parties that can join a single conference call on this address.

dwMaxNumTransConf (4 bytes): An unsigned 32-bit integer. The number of parties (including "self") that can be added in a conference call that is initiated as a generic consultation call using the SetUpTransfer packet.

dwAddrCapFlags (4 bytes): An unsigned 32-bit integer. The packed bit flags that describe a variety of address capabilities. This member MUST use one or more of the LINEADDRCAPFLAGS_Constants.

dwCallFeatures (4 bytes): An unsigned 32-bit integer. The switching capabilities or features that are available for all calls on this address by using the LINECALLFEATURE_Constants. This member represents the call-related features that can possibly be available on an address (static availability as opposed to dynamic availability). Invoking a supported feature requires the call to be in the correct state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature can be available if the application has the right privileges to the call and the call is in the appropriate state for the operation to be meaningful. This member allows an application to discover which call features can be (and which can never be) supported by the address.

dwRemoveFromConfCaps (4 bytes): An unsigned 32-bit integer. The capabilities of an address for removing calls from a conference call. This member MUST use one of the LINEREMOVEFROMCONF_Constants.

dwRemoveFromConfState (4 bytes): An unsigned 32-bit integer. Uses one or more of the LINECALLSTATE_Constants to specify the state of the call after it has been removed from a conference call.

dwTransferModes (4 bytes): An unsigned 32-bit integer. The capabilities of an address for resolving transfer requests. This member MUST use one of the LINETRANSFERMODE_Constants.

dwParkModes (4 bytes): An unsigned 32-bit integer. The different call park modes that are available at this address. This member MUST use one of the LINEPARKMODE_Constants.

dwForwardModes (4 bytes): An unsigned 32-bit integer. The different modes of forwarding that are available for this address. This member MUST use one or more of the LINEFORWARDMODE_Constants.

dwMaxForwardEntries (4 bytes): An unsigned 32-bit integer. The maximum number of entries that can be passed to the Forward packet in the lpForwardList parameter.

dwMaxSpecificEntries (4 bytes): An unsigned 32-bit integer. The maximum number of entries in the lpForwardList parameter that is passed to the Forward packet that can contain forwarding instructions based on a specific caller ID (selective call forwarding). This member is zero if selective call forwarding is not supported.

dwMinFwdNumRings (4 bytes): An unsigned 32-bit integer. The minimum number of rings that can be set to determine when a call is officially considered "no answer."

dwMaxFwdNumRings (4 bytes): An unsigned 32-bit integer. The maximum number of rings that can be set to determine when a call is officially considered "no answer." If this number of rings cannot be set, then dwMinFwdNumRings and dwMaxNumRings are equal.

dwMaxCallCompletions (4 bytes): An unsigned 32-bit integer. The maximum number of concurrent call completion requests that can be outstanding on this line device. Zero implies that call completion is not available.

dwCallCompletionConds (4 bytes): An unsigned 32-bit integer. The different call conditions under which call completion can be requested. This member MUST use one or more of the LINECALLCOMPLCOND_Constants.

dwCallCompletionModes (4 bytes): An unsigned 32-bit integer. The ways in which the call can be completed. This member MUST use one of the LINECALLCOMPLMODE_Constants.

dwNumCompletionMessages (4 bytes): An unsigned 32-bit integer. The number of call completion packets that can be selected from, when using the LINECALLCOMPLMODE_MESSAGE option. Individual packets are identified by values in the range zero through one less than dwNumCompletionMessages.

dwCompletionMsgTextEntrySize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of each of the call completion text descriptions that are specified by dwCompletionMsgTextSize and dwCompletionMsgTextOffset.

dwCompletionMsgTextSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the call completion text.

dwCompletionMsgTextOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of this packet to the variably sized field that contains descriptive text about each of the call completion packets. Each packet is dwCompletionMsgTextEntrySize bytes long. The string format of these textual descriptions is indicated by dwStringFormat in the line's device capabilities. The size of the field MUST be specified by dwCompletionMsgTextSize.

dwAddressFeatures (4 bytes): An unsigned 32-bit integer. The features that are available for this address by using the LINEADDRFEATURE_Constants. Invoking a supported feature requires the address to be in the proper state and the underlying line device to be opened in a compatible mode. A zero in a bit position indicates that the corresponding feature is never available. A one indicates that the corresponding feature can be available if the address is in the appropriate state for the operation to be meaningful. This member allows an application to discover which address features can be (and which can never be) supported by the address.

dwPredictiveAutoTransferStates (4 bytes): An unsigned 32-bit integer. The call state or states upon which a call that is made by a predictive dialer can be set to automatically transfer the call to another address; one or more of the LINECALLSTATE_Constants. The value 0 indicates that automatic transfer based on call state is unavailable. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwNumCallTreatments (4 bytes): An unsigned 32-bit integer. The number of entries in the array of LINECALLTREATMENTENTRY packets delimited by dwCallTreatmentListSize and dwCallTreatmentListOffset. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwCallTreatmentListSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the call treatment array. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwCallTreatmentListOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of the packet to an array of LINECALLTREATMENTENTRY packets that specify the call treatments supported on the address (that can be selected using the SetCallTreatment packet). The value is dwNumCallTreatments times SIZEOF(LINECALLTREATMENTENTRY). The size of the field MUST be specified by dwCallTreatmentListSize. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwDeviceClassesSize (4 bytes): An unsigned 32-bit integer. The size, in bytes, of the list of supported device classes. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwDeviceClassesOffset (4 bytes): An unsigned 32-bit integer. The offset from the beginning of the packet to a string that consists of the device class identifiers that are supported on this address for use with the GetID packet. The elements are separated by null characters, and the last class identifier is followed by two null characters. The size of the field MUST be specified by dwDeviceClassesSize. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwMaxCallDataSize (4 bytes): An unsigned 32-bit integer. The maximum number of bytes that an application can set in LINECALLINFO by using the SetCallData packet. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwCallFeatures2 (4 bytes): An unsigned 32-bit integer. The additional switching capabilities or features that are available for all calls on this address by using the LINECALLFEATURE2_Constants. It is an extension of the dwCallFeatures member. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwMaxNoAnswerTimeout (4 bytes): An unsigned 32-bit integer. The maximum value, in seconds, that can be set in the dwNoAnswerTimeout member in LINECALLPARAMS when making a call. A value of 0 indicates that automatic abandonment of unanswered calls is not supported by the service provider or that the time-out value is not adjustable by applications. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwConnectedModes (4 bytes): An unsigned 32-bit integer. The LINECONNECTEDMODE_Constants that can appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE packets for calls on this address. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwOfferingModes (4 bytes): An unsigned 32-bit integer. The LINECONNECTEDMODE_Constants that can appear in the dwCallStateMode member of LINECALLSTATUS and in LINE_CALLSTATE packets for calls on this address. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

dwAvailableMediaModes (4 bytes): An unsigned 32-bit integer. The media types (modes) that can be invoked on new calls created on this address, when the dwAddressFeatures member indicates that new calls are possible. If this member is zero, it indicates that the service provider either does not know or cannot indicate which media types are available; in which case, any or all of the media types that are indicated in the dwMediaModes member in LINEDEVCAPS can be available. This member of the packet is available only if the negotiated TAPI version is 2.0 or higher.

VarData (variable): MUST contain

• Address information as specified by dwAddressOffset.

• Device-specific information as specified by dwDevSpecificOffset.

• Descriptive text about each of the call completion packets as specified by dwCompletionMsgTextOffset.

• An array of LINECALLTREATMENTENTRY packets that specify the call treatments supported on the address as specified by dwCallTreatmentListOffset.

• A string consisting of the device class identifiers that are supported on this address as specified by dwDeviceClassesOffset.

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

Sessions that are negotiated with TAPI versions that are earlier than TAPI version 2.0 are not aware of the new members in the LINEADDRESSCAPS packet. The application passes in a dwAPIVersion parameter with the GetAddressCaps packet, which can be used for guidance by TAPI in handling this situation. If the application passes in a dwTotalSize member that is less than the size of the fixed portion of the packet, as defined in the dwAPIVersion member specified, LINEERR_STRUCTURETOOSMALL MUST be returned. If sufficient memory has been allocated by the application, before sending the GetAddressCaps packet, TAPI MUST set the dwNeededSize and dwUsedSize members to the fixed size of the packet as it existed in the specified TAPI version.

New service providers (that support the new TAPI version) MUST examine the TAPI version that is passed in. If the TAPI version is less than the highest version that is supported by the provider, the service provider MUST NOT fill in fields that are not supported in older TAPI versions because these would fall in the variable portion of the older packet.

New applications MUST be aware of the TAPI version that is negotiated and not examine the contents of fields in the fixed portion beyond the original end of the fixed portion of the packet for the negotiated TAPI version.

The members dwPredictiveAutoTransferStates through dwAvailableMediaModes are available only to sessions that request a TAPI version of 2.0, 2.1, 2.2, 3.0, or 3.1 by using the GetAddressCaps packet.