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.
| Q | S | Name |
|---|---|---|
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