TAPI Objects

TAPI objects use a set of associated OIDs to make both query and set information requests. These OIDs define the request interface between user-mode TAPI service providers and underlying WAN miniport drivers. Each such request goes through NDISTAPI and NDISWAN to the target miniport driver. This section defines the OIDs that are associated with TAPI objects.

The TAPI OIDs are defined in ntddndis.h. When building a driver that supports these OIDs, include ntddndis.h and ndistapi.h.

For more information about higher-level TAPI components, especially about user-mode service providers in which these OID requests originate, see the Microsoft Win32 SDK.

The following chart summarizes the OIDs used to get operational characteristics for NDIS drivers and NICs that support TAPI on a WAN network.

QSName

Mandatory OID_TAPI_XXX

M

OID_TAPI_ANSWER
Answer

M

OID_TAPI_CLOSE
Close

M

OID_TAPI_CLOSE_CALL
Close Call

M

OID_TAPI_CONDITIONAL_MEDIA_DETECTION
Conditional Media Detection

M

OID_TAPI_DROP
Drop

M

OID_TAPI_GET_ADDRESS_CAPS
Get Address Capabilities

M

OID_TAPI_GET_ADDRESS_ID
Get Address ID

M

OID_TAPI_GET_ADDRESS_STATUS
Get Address Status

M

OID_TAPI_GET_CALL_ADDRESS_ID
Get Call Address ID

M

OID_TAPI_GET_CALL_INFO
Get Call Information

M

OID_TAPI_GET_CALL_STATUS
Get Call Status

M

OID_TAPI_GET_DEV_CAPS
Get Device Capabilities

M

OID_TAPI_GET_ID
Get ID

M

OID_TAPI_GET_LINE_DEV_STATUS
Get Line Device Status

M

OID_TAPI_MAKE_CALL
Make Call

M

OID_TAPI_OPEN
Open

M

OID_TAPI_PROVIDER_INITIALIZE
Provider Initialize

M

OID_TAPI_PROVIDER_SHUTDOWN
Provider Shutdown

M

OID_TAPI_SET_APP_SPECIFIC
Set Application Specific Member

M

OID_TAPI_SET_CALL_PARAMS
Set Call Parameters

M

OID_TAPI_SET_DEFAULT_MEDIA_DETECTION
Set Default Media Detection

M

OID_TAPI_SET_MEDIA_MODE
Set Media Mode

M

OID_TAPI_SET_STATUS_MESSAGES
Set Status Messages

Optional OID_TAPI_XXX

O

OID_TAPI_ACCEPT
Accept

O

OID_TAPI_CONFIG_DIALOG
Configuration Dialog

O

OID_TAPI_DEV_SPECIFIC
Device Specific

O

OID_TAPI_DIAL
Dial Specified Number for Specified Call

O

OID_TAPI_GET_DEV_CONFIG
Get Device Configuration

O

OID_TAPI_GET_EXTENSION_ID
Get Extension ID

O

OID_TAPI_NEGOTIATE_EXT_VERSION
Return Highest Acceptable Version Extension

O

OID_TAPI_SET_DEV_CONFIG
Set Device Configuration

O

OID_TAPI_SECURE_CALL
Secure Call

O

OID_TAPI_SELECT_EXT_VERSION
Select Extension Version

O

OID_TAPI_SEND_USER_USER_INFO
Send User Information

 

In contrast with other OIDs, defined TAPI OID values do not indicate whether each OID is required or optional. The length of the information buffer for TAPI OID requests varies according to the OID-specific structure. Instances of some OID-specific structures also vary in size, in particular for TAPI-defined structures with members of type VAR_STRING, described later.

WAN miniport drivers must support the OIDS labeled as Mandatory in the preceding chart. The extent to which a given miniport driver supports those labeled Optional in the preceding chart depends on the discretion of the driver writer and the capabilities of the NIC.

The functional requirements are quite simple for several of the TAPI OID requests. For example, the OID_TAPI_SET_APP_SPECIFIC request requires a NIC driver only to associate a ULONG value with a specified call instance, which can be retrieved later with an OID_TAPI_GET_CALL_INFO request. Requests that a NIC driver writer chooses to ignore should be completed with the NDIS_STATUS_TAPI_OPERATIONUNAVAIL status code.

A NIC driver can indicate the requests it supports, which might vary over time depending on line, address, or call state, by setting or clearing specific bits in the members of structures for some of the OID_TAPI_GET_XXX requests, such as in the ulAddrCapFlags member in the LINE_ADDRESS_CAPS structure.

For the declaration of LINE_ADDRESS_CAPS and other system-defined structures in which WAN miniport drivers maintain TAPI state, see ndistapi.h. For more information about these structures, see also the Win32 SDK.

TAPI Type VAR_STRING

For several OID_TAPI_XXX, the miniport driver is given an OID-specific structured information buffer. More than one of these TAPI structures have a member of type VAR_STRING, which is also a structured buffer, defined as follows:


typedef struct _VAR_STRING {
  ULONG  ulTotalSize;
  ULONG  ulNeededSize;
  ULONG  ulUsedSize;
  ULONG  ulStringFormat;
  ULONG  ulStringSize;
  ULONG  ulStringOffset;
} VAR_STRING, *PVAR_STRING;

The members of this structure contain the following information:

ulTotalSize

The total size in bytes of the buffer, including the buffered string.

ulNeededSize

The size in bytes of a buffer necessary to contain a particular string. For example, the underlying driver sets this value if a protocol-supplied buffer is too short to contain a requested string.

ulUsedSize

The number of bytes in the given buffer that were actually used.

ulStringFormat
Specifies how the buffered string should be interpreted, as one of the following:
STRINGFORMAT_ASCII
STRINGFORMAT_DBCS
STRINGFORMAT_UNICODE
STRINGFORMAT_BINARY
ulStringSize

The number of bytes in the given buffered string.

ulStringOffset

The offset within this buffer at which the string begins.

The following topics describe the OID_XXX elements that are listed in the preceding chart. These topics also describe any TAPI structures that may be associated with the OID_XXX elements.

TAPI Query Information Requests

TAPI Set Information Requests

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft