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.

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 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