5.8 TAPI Objects

This defines the OIDs for TAPI objects, both for query and set information requests. These OIDs define the request interface between user-mode TAPI service providers and underlying WAN NIC miniports. Each such request goes through NDISTAPI and NDISWAN to the target miniport.

For more information about higher-level TAPI components, especially about user-mode service providers in which these OID requests originate, see the 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.

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 Paramaters
	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 User Information

WAN NIC miniports must support the OIDS labeled as Mandatory in the preceding chart. The extent to which a given miniport 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 miniports 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 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 describes the OID_XXX listed in the preceding chart and their associated TAPI structures, if any, more fully.

TAPI Query Information Requests

Query-information requests differ from set-information requests in that one or more members in the associated structure, denoted by the “OUT” prefix in the structure definition, are reserved for information the underlying miniport should return to the initiator of the request. WAN NIC drivers should treat structure members prefixed with “IN” as read-only.

The first member of all the structures used in query-information requests, ulRequestID, is reserved for future use. Miniport drivers should ignore this member.

OID_TAPI_GET_ADDRESS_CAPS

This OID requests the WAN NIC driver to return information for the specified address on the specified line about its telephony capabilities.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_ADDRESS_CAPS structure, defined as follows, to query the telephony capabilities of a specified address:

typedef struct _NDIS_TAPI_GET_ADDRESS_CAPS { 
    IN ULONG               ulRequestID; 
    IN ULONG               ulDeviceID; 
    IN ULONG               ulAddressID; 
    IN ULONG               ulExtVersion; 
    OUT LINE_ADDRESS_CAPS  LineAddressCaps; 
} NDIS_TAPI_GET_ADDRESS_CAPS, *PNDIS_TAPI_GET_ADDRESS_CAPS; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceID

Specifies the link or data channel to be queried. This was set up in a preceding OID_TAPI_GET_ID request.

ulAddressID

Specifies the address on the given link for which capabilities should be returned. The value of this member is not validated by NDISTAPI when this request is made.

ulExtVersion

Specifies the version number of the miniport-specific extensions to be used. This member is zero if no device-specific extensions are used. Otherwise, the high-order bytes contain the major version number and the low-order bytes contain the minor version number. The value of this member is not validated by NDISTAPI when this request is made.

LineAddressCaps

Specifies the base virtual address of a variable-size structure of type LINE_ADDRESS_CAPS. See ndistapi.h for details.

This structure has at least sizeof(LINE_ADDRESS_CAPS) bytes reserved.

Upon successful completion of the request, the miniport fills this structure with address capabilities information.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INCOMPATIBLEEXTVERSION
NDIS_STATUS_TAPI_INVALADDRESSID
NDIS_STATUS_TAPI_NODRIVER
NDIS_STATUS_FAILURE

OID_TAPI_GET_ADDRESS_ID

This OID requests the WAN NIC driver to return the address ID associated with the address in a different format on the specified line.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_ADDRESS_ID structure, defined as follows:

typedef struct _NDIS_TAPI_GET_ADDRESS_ID { 
    IN ULONG      ulRequestID; 
    IN HDRV_LINE  hdLine; 
    OUT ULONG     ulAddressID; 
    IN ULONG      ulAddressMode; 
    IN ULONG      ulAddressSize; 
    IN CHAR       szAddress[1]; 
} NDIS_TAPI_GET_ADDRESS_ID, *PNDIS_TAPI_GET_ADDRESS_ID; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle to the line for which the address ID should be retrieved. This was set up in a preceding OID_TAPI_OPEN request.

ulAddressID

Specifies the requested address ID. The miniport fills in this member with the address ID corresponding to szAddress to complete this request successfully.

ulAddressMode

Specifies the address mode of the address contained in szAddress. This member can have only the following LINEADDRESSMODE flag set:

LINEADDRESSMODE_DIALABLEADDR

ulAddressSize

Specifies the size in bytes of the address in szAddress.

szAddress

Specifies the virtual address of variable-size structure containing an address assigned to the line device. The format of the address is determined by the ulAddressMode member. If it is LINEADDRESSMODE_DIALABLEADDR, szAddress uses the common dialable number format and is zero-terminated.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_INVALADDRESS
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_ADDRESS_STATUS

This OID requests the miniport to return the current status for the specified address.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_ADDRESS_STATUS structure, defined as follows, to query the current status for the specified address:

typedef struct _NDIS_TAPI_GET_ADDRESS_STATUS { 
    IN ULONG                 ulRequestID; 
    IN HDRV_LINE             hdLine; 
    IN ULONG                 ulAddressID; 
    OUT LINE_ADDRESS_STATUS  LineAddressStatus; 
} NDIS_TAPI_GET_ADDRESS_STATUS, *PNDIS_TAPI_GET_ADDRESS_STATUS; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle for the line.

ulAddressID

Specifies an address on the given open line device. This is the address for which the status should be returned. The value of this member is not validated by NDISTAPI when this request is made.

LineAddressStatus

Specifies the virtural address of a variable-size structure of type LINE_ADDRESS_STATUS. See ndistapi.h for details.

The miniport fills this structure with address status information to complete this request successfully.

The LineAddressStatus member has at least sizeof(LINE_ADDRESS_STATUS) bytes reserved.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_INVALADDRESSID
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_CALL_ADDRESS_ID

This OID requests the miniport to return the address ID for the specified call.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_CALL_ADDRESS_ID structure, defined as follows:

typedef struct _NDIS_TAPI_GET_CALL_ADDRESS_ID { 
    IN ULONG      ulRequestID, 
    IN HDRV_CALL  hdCall, 
    OUT ULONG     ulAddressID 
} NDIS_TAPI_GET_CALL_ADDRESS_ID, *PNDIS_TAPI_GET_CALL_ADDRESS_ID; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call for which the ID should be retrieved. This handle was set up either in a preceding OID_TAPI_MAKE_CALL request or when the miniport called NdisMIndicateStatus to report an incoming call.

ulAddressID

Specifies the address ID. The miniport fills this member with the corresponding address ID for hdCall to complete this request successfully.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_CALL_INFO

This OID requests the miniport to return detailed information about the specified call.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_CALL_INFO structure, defined as follows:

typedef struct _NDIS_TAPI_GET_CALL_INFO { 
    IN ULONG            ulRequestID; 
    IN HDRV_CALL        hdCall; 
    OUT LINE_CALL_INFO  LineCallInfo; 
} NDIS_TAPI_GET_CALL_INFO, *PNDIS_TAPI_GET_CALL_INFO; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call for which it should return information.

LineCallInfo

Specifies the virtual address variable-size data structure of type LINE_CALL_INFO. See ndistapi.h for details.

The miniport fills this structure with call-related information to complete this request successfully.

The structure at LineCallInfo has at least sizeof(LINE_CALL_INFO) bytes reserved.

The MiniportQueryInformation function can return one of the following: NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_CALL_STATUS

This OID requests the miniport to return the current status of the specified call.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_CALL_STATUS structure, defined as follows:

typedef struct _NDIS_TAPI_GET_CALL_STATUS { 
    IN ULONG              ulRequestID; 
    IN HDRV_CALL          hdCall; 
    OUT LINE_CALL_STATUS  LineCallStatus; 
} NDIS_TAPI_GET_CALL_STATUS, *PNDIS_TAPI_GET_CALL_STATUS; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call for which the current status should be returned.

LineCallStatus

Specifies the virtual address of a variable-size structure of type LINE_CALL_STATUS. See ndistapi.h for details.

The miniport fills this structure with call status information to complete this request successfully.

The structure at LineCallStatus has at least sizeof(LINE_CALL_STATUS) bytes reserved.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_DEV_CAPS

This OID requests the miniport to return the telephony capabilities of a specified line device. The returned information is valid for all addresses on the given line device.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_DEV_CAPS structure, defined as follows:

typedef struct _NDIS_TAPI_GET_DEV_CAPS { 
    IN ULONG           ulRequestID; 
    IN ULONG           ulDeviceID; 
    IN ULONG           ulExtVersion; 
    OUT LINE_DEV_CAPS  LineDevCaps; 
} NDIS_TAPI_GET_DEV_CAPS, *PNDIS_TAPI_GET_DEV_CAPS; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceID

Specifies the link or data channel to be queried. This was set up in a preceding OID_TAPI_GET_ID request.

ulExtVersion

Specifies the negotiated extension version number, if any.

The value has already been negotiated for this device through the OID_TAPI_NEGOTIATE_EXT_VERSION request. The value of this member is not validated when this request is made.

LineDevCaps

Specifies the virtual address of a variable-size structure of type LINE_DEV_CAPS. See ndistapi.h for details.

The NIC driver fills this structure with line device capabilities information to complete this request successfully.

The structure at LineDevCaps has at least sizeof(LINE_DEV_CAPS) bytes reserved.

The supplied provider information in the dwProviderInfoOffset member of LINE_DEV_CAPS must have the following format:

MediaName\0ProviderName\0 
where
MediaName is ISDN, SW56, FrameRelay, and so forth, as appropriate
and
ProviderName is the name of the manufacturer of the device and the unique name of the device, if any.

For example, the driver of an ISDN device from SomeIHV Inc. would set the dwProviderInfoOffset member with a pointer to the string “ISDN\0SomeIHV\0”

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_NODRIVER
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_DEV_CONFIG

This OID requests the miniport to return the current configuration of a device associated one-to-one with a particular line.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_DEV_CONFIG structure, defined as follows:

typedef struct _NDIS_TAPI_GET_DEV_CONFIG { 
    IN ULONG        ulRequestID; 
    IN ULONG        ulDeviceID; 
    IN ULONG        ulDeviceClassSize; 
    IN ULONG        ulDeviceClassOffset; 
    OUT VAR_STRING  DeviceConfig; 
} NDIS_TAPI_GET_DEV_CONFIG, *PNDIS_TAPI_GET_DEV_CONFIG; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceID

Specifies the line device to be queried. This value was set up in a preceding OID_TAPI_PROVIDER_INITIALIZE request.

ulDeviceClassSize

Specifies the number of bytes in the device-class string.

ulDeviceClassOffset

Specifies the offset in bytes to the zero-terminated, variable-size counted string specifying the class of the device whose configuration is requested. Valid device class strings are the same as those specified for the OID_TAPI_GET_ID request when it is applied to a “line” device (ulSelect has the value LINECALLSELECT_LINE).

DeviceConfig

Specifies the virtual address of a structure of type VAR_STRING to contain the device configuration information for the associated device.

The ulStringFormat member of the VAR_STRING structure must be set to STRINGFORMAT_BINARY.

The miniport fills this structure with the device configuration information to complete this request successfully.

In general, the contents of the NDIS_TAPI_GET_DEV_CONFIG structure are specific to the NIC driver’s line and the device class.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NNDIS_STATUS_TAPI_INVALDEVICECLASS
NDIS_STATUS_TAPI_STRUCTURETOOSMALL
NDIS_STATUS_TAPI_NODRIVER
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_ID

This OID requests the miniport to return a device ID for the specified device class associated with the selected line, address, or call.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_ID structure, defined as follows:

typedef struct _NDIS_TAPI_GET_ID { 
    IN ULONG        ulRequestID; 
    IN HDRV_LINE    hdLine; 
    IN ULONG        ulAddressID; 
    IN HDRV_CALL    hdCall; 
    IN ULONG        ulSelect; 
    IN ULONG        ulDeviceClassSize; 
    IN ULONG        ulDeviceClassOffset; 
    OUT VAR_STRING  DeviceID; 
} NDIS_TAPI_GET_ID, *PNDIS_TAPI_GET_ID; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle to the line.

ulAddressID

Specifies an address on the given open line device. The value of this member is not validated by NDISTAPI when this request is made.

hdCall

Specifies the miniport’s handle to the call.

ulSelect

Specifies whether the device ID is associated with the line, address, or a single call as one of the following:

LINECALLSELECT_LINE

Selects the specified line device. The hdLine member must contain a valid line handle; hdCall and ulAddressID are unused.

LINECALLSELECT_ADDRESS

Selects the specified address on the line. Both hdLine and ulAddressID must be valid; hdCall is unused.

LINECALLSELECT_CALL

Selects the specified call. The hdCall member must be valid; hdLine and ulAddressID are unused.

ulDeviceClassSize

Specifies the size in bytes of the zero-terminated, variable-size string specifying the device class of the device for which the configuration should be returned.

ulDeviceClassOffset

Specifies the offset in bytes to the device-class string.

DeviceID

Specifies the virtual address of a data structure of type VAR_STRING in which the the device ID should be returned.

The miniport fills this structure with the device ID to complete this request successfully.

Currently, there are two types of this request that must be supported by WAN NIC drivers:

1. IN  DeviceClass = “ndis” // case insensitive
    IN  ulSelect = LINECALLSELECT_CALL
    IN  hdCall = ActiveCallHandle
    OUT  DeviceID = ConnectionWrapperID 

DeviceID should be set to the NdisLinkContext handle returned by NDISWAN in the NDIS_MAC_LINE_UP structure for the initial NDIS_STATUS_WAN_LINE_UP indication to establish the link.

The miniport must make the initial line-up indication to establish a link (or open a data channel on a line) before returning from this request in order to supply this DeviceID value.

2. IN  DeviceClass = “tapi/line”
    IN  ulSelect = LINECALLSELECT_LINE
    IN  hdLine = OpenLineHandle
    OUT  DeviceID = ulDeviceID 

DeviceID will be set to the miniport-determined DeviceID associated with the line handle.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_INVALADDRESSID
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_NODEVICE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_LINE_DEV_STATUS

This OID requests the miniport to return the current status for the specified open line device. The returned information is global to all addresses on the line.

Support for this request is mandatory.

This request uses an NDIS_TAPI_GET_LINE_DEV_STATUS structure, defined as follows:

typedef struct _NDIS_TAPI_GET_LINE_DEV_STATUS { 
    IN ULONG             ulRequestID; 
    IN HDRV_LINE         hdLine; 
    OUT LINE_DEV_STATUS  LineDevStatus; 
} NDIS_TAPI_GET_LINE_DEV_STATUS, *PNDIS_TAPI_GET_LINE_DEV_STATUS; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle to the line to be queried.

LineDevStatus

Specifies a variable-sized structure of type LINE_DEV_STATUS. See ndistapi.h for details.

The miniport fills this structure with the line’s current device status to complete this request successfully.

The structure at LineDevStatus has at least sizeof(LINE_DEV_STATUS) bytes reserved.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_MAKE_CALL

This OID requests the miniport to place a call on the specified line to the specified destination address. Optionally, additional call parameters can be specified if the miniport is to use something other than default call-setup parameters.

Support for this request is mandatory.

This request uses an NDIS_TAPI_MAKE_CALL structure, defined as follows:

typedef struct _NDIS_TAPI_MAKE_CALL { 
    IN ULONG             ulRequestID; 
    IN HDRV_LINE         hdLine; 
    IN HTAPI_CALL        htCall; 
    OUT HDRV_CALL        hdCall; 
    IN ULONG             ulDestAddressSize; 
    IN ULONG             ulDestAddressOffset; 
    IN BOOLEAN           bUseDefaultLineCallParams; 
    IN LINE_CALL_PARAMS  LineCallParams; 
} NDIS_TAPI_MAKE_CALL, *PNDIS_TAPI_MAKE_CALL; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle to the line on which the new call is to be originated.

htCall

Specifies NDISTAPI’s handle to the call.

The miniport must save this handle for use in subsequent notifications, in particular the initial NDIS_MAC_LINE_UP notification to establish a link or data channel.

hdCall

Specifies the miniport’s handle to the call. The miniport must fill this member with its handle for the call before completing this request successfully. This handle is ignored if the miniport returns an error status.

ulDestAddressSize

Specifies the size in bytes of the variable-size buffer at ulDestAddressOffset containing the destination address.

This member can be zero for undialed addresses, such as for a hot phone, which always automatically connects to a predefined number, or when dialing will be done subsequently with an OID_TAPI_DIAL request.

ulDestAddressOffset

Specifies the offset in bytes from the beginning of this structure to the destination address. This destination addresss is in standard dialable number format. This member should be zero if ulDestAddressSize is zero.

If dialing will be done subsequently with an OID_TAPI_DIAL request, the driver should allocate an available call appearance on receipt of this request and remain in the dialtone state until dialing begins. Drivers of NICs that have inverse multiplexing capabilities can allow an application to specify many addresses at once.

bUseDefaultLineCallParams

Specifies whether the miniport should use the default call-setup parameters or the parameters specified in LineCallParams when making the call. If this member is FALSE, the driver should ignore LineCallParams.

LineCallParams

The LINE_CALL_PARAMS structure at this member specifies how the call should be set up. It selects elements such as the call’s bearer mode, data rate, expected media mode, origination address, blocking of caller ID information, and dialing parameters. See ndistapi.h for details.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_ADDRESSBLOCKED
NDIS_STATUS_TAPI_BEARERMODEUNAVAIL
NDIS_STATUS_TAPI_CALLUNAVAIL
NDIS_STATUS_TAPI_DIALBILLING
NDIS_STATUS_TAPI_DIALQUIET
NDIS_STATUS_TAPI_DIALDIALTONE
NDIS_STATUS_TAPI_DIALPROMPT
NDIS_STATUS_TAPI_INUSE
NDIS_STATUS_TAPI_INVALBEARERMODE
NDIS_STATUS_TAPI_INVALMEDIAMODE
NDIS_STATUS_TAPI_INVALLINESTATE
NDIS_STATUS_TAPI_INVALRATE
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_INVALADDRESS
NDIS_STATUS_TAPI_INVALADDRESSID
NDIS_STATUS_TAPI_INVALCALLPARAMS
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_TAPI_RATEUNAVAIL
NDIS_STATUS_TAPI_USERUSERINFOTOOBIG
NDIS_STATUS_FAILURE

OID_TAPI_OPEN

This OID requests the miniport to open the line device designated by the given device ID and return the NIC driver’s handle for the device.

Support for this request is mandatory.

This request uses an NDIS_TAPI_OPEN structure, defined as follows:

typedef struct _NDIS_TAPI_OPEN { 
    IN ULONG       ulRequestID; 
    IN ULONG       ulDeviceID; 
    IN HTAPI_LINE  htLine; 
    OUT HDRV_LINE  hdLine; 
} NDIS_TAPI_OPEN, *PNDIS_TAPI_OPEN; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceID

Specifies the line device to be queried. This was set up in a preceding OID_TAPI_PROVIDER_INITIALIZE request.

htLine

Specifies NDISTAPI’s handle to the line device to be used in subsequent calls to the LINE_EVENT callback procedure to identify the line

hdLine

Specifies the miniport NIC driver’s handle to the line device.

The NIC driver must fill this location with its handle for the line device to complete this request successfully. This handle is ignored if the miniport completes the request with an error status.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_ALLOCATED
NDIS_STATUS_TAPI_INVALMEDIAMODE
NDIS_STATUS_FAILURE

The miniport must retain the htLine handle for the device provided by NDISTAPI for use in subsequent NDIS_TAPI_EVENT notifications using the LINE_EVENT structure.

OID_TAPI_PROVIDER_INITIALIZE

This OID requests that the miniport initialize itself as a TAPI provider. The driver should set up whatever internal state it uses to track incoming requests from TAPI.

Support for this request is mandatory.

This request uses an NDIS_TAPI_PROVIDER_INITITIALIZE structure, defined as follows:

typedef struct _NDIS_TAPI_PROVIDER_INITIALIZE { 
    IN ULONG   ulRequestID; 
    IN ULONG   ulDeviceIDBase; 
    OUT ULONG  ulNumLineDevs; 
    OUT ULONG  ulProviderID; 
} NDIS_TAPI_PROVIDER_INITIALIZE, *PNDIS_TAPI_PROVIDER_INITIALIZE; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceIDBase

Specifies the lowest device ID for the line devices supported by the miniport. Subsequent to this request, the driver uses this value as the zero-based line device identifier value. That is, if ulNumLineDevs is greater than one, the ulDeviceID values subsequently passed in requests such as OID_TAPI_OPEN, contains this value for the first line, this value plus one for the second line, and so forth.

ulNumLineDevs

Specifies the number of line devices supported by the miniport to complete this request successfully.

ulProviderID

Specifies an ID for the WAN NIC driver if this request is completed successfully. This value must be unique within the set of WAN drivers that support TAPI; the NdisMiniportContext handle passed in to the MiniportInitialize function can be used to provide a guaranteed unique value.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_CONFIG_DIALOG

This OID requests the miniport to return the name of a user-mode dynamic-link library that can be loaded and called to configure the specified device.

Such a configuration DLL exports the following function by name:

    LONG
    WINAPI
    ConfigDialog(
        IN HWND hwndOwner,
        IN ULONG ulDeviceID,
        IN LPCSTR lpszDeviceClass
        );

Support for this request is optional. This request is not made by RAS.

The NDIS_TAPI_CONFIG_DIALOG structure, defined as follows, is used with this OID to retrieve the name of a user-mode dynamic link library that can be called to configure the specified device.

typedef struct _NDIS_TAPI_CONFIG_DIALOG { 
    IN ULONG  ulRequestID; 
    IN ULONG  ulDeviceID; 
    IN ULONG  ulDeviceClassSize; 
    IN ULONG  ulDeviceClassOffset; 
    IN ULONG  ulLibraryNameTotalSize; 
    OUT ULONG ulLibraryNameNeededSize; 
    OUT CHAR  szLibraryName[1]; 
} NDIS_TAPI_CONFIG_DIALOG, *PNDIS_TAPI_CONFIG_DIALOG; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceID

Specifies the line device to be configured. This was set up in a preceding OID_TAPI_PROVIDER_INITIALIZE request.

ulDeviceClassSize

Specifies the size in bytes of the device-class string.

ulDeviceClassOffset

Specifies the offset in bytes to the zero-terminated, variable-size counted string specifying the class of the device whose configuration is requested. Valid device class strings are the same as those specified for the OID_TAPI_GET_ID request when it is applied to a “line” device (ulSelect has the value LINECALLSELECT_LINE).

ulLibraryNameTotalSize

Specifies the size in bytes of the szLibraryName member.

ulLibraryNameNeededSize

Specifies the size in bytes that is needed to hold all the returned information.

szLibraryName

Specifies space for a zero-terminated string naming a configuration DLL for the requested device. Names not containing a complete path or an extension will be subject to the rules used by the Win32 LoadLibrary function for determining default paths and extensions. If the miniport determines this buffer is too small to hold all the information, it should specify the necessary size in the ulLibraryNameNeededSize member and return an NDIS_STATUS_TAPI_STRUCTURETOOSMALL error.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_STRUCTURETOOSMALL
NDIS_STATUS_TAPI_INVALDEVICECLASS
NDIS_STATUS_TAPI_OPERATIONUNAVAIL
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_DEV_SPECIFIC

This OID requests the miniport to provide access to features not accessible through other OID requests. The meaning of the extensions are device-specific, so the application must be fully aware of them to take advantage of these extensions.

Support for this request is optional.

This request uses an NDIS_TAPI_DEV_SPECIFIC structure, defined as follows, to query and provide access to features not specified in other TAPI OID requests:

typedef struct _NDIS_TAPI_DEV_SPECIFIC { 
    IN ULONG      ulRequestID; 
    IN HDRV_LINE  hdLine; 
    IN ULONG      ulAddressID; 
    IN HDRV_CALL  hdCall; 
    IN OUT ULONG  ulParamsSize; 
    IN OUT UCHAR  Params[1]; 
} NDIS_TAPI_DEV_SPECIFIC, *PNDIS_TAPI_DEV_SPECIFIC; 
 

The members of this structure contain the following device-specific information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle to the line to be operated on.

ulAddressID

Specifies the address on the specified line to be operated on.

hdCall

Specifies the miniport’s handle to the call to be operated on. This member can be NULL.

ulParamsSize

Specifies the number of bytes in the following parameter block. On entry, this member will contain the size in bytes of the parameter block passed in to the miniport.

If the miniport returns information in the parameter block, it should set this member to the size in bytes of the returned information, which cannot exceed the input ulParamsSize. Otherwise, the miniport should set this member to zero to indicate that it is returning no information.

Params

Specifies a device-specific parameter block.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_INVALADDRESSID
NDIS_STATUS_TAPI_OPERATIONUNAVAIL
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_GET_EXTENSION_ID

This OID requests the miniport to return the extension ID for the specified line device.

Support for this request is optional.

This request uses an NDIS_TAPI_GET_EXTENSION_ID structure, defined as follows:

typedef struct _NDIS_TAPI_GET_EXTENSION_ID { 
    IN ULONG               ulRequestID; 
    IN ULONG               ulDeviceID; 
    OUT LINE_EXTENSION_ID  LineExtensionID; 
} NDIS_TAPI_GET_EXTENSION_ID, *PNDIS_TAPI_GET_EXTENSION_ID; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceID

Specifies the link or data channel to be queried. This was set up in a preceding OID_TAPI_GET_ID request.

LineExtensionID

Points to a structure of type LINE_EXTENSION_ID. See ndistapi.h for details.

If the miniport supports device-specific extensions, it fills this structure with the extension ID of these extensions. Otherwise, it fills this structure with zeros.

For a bound protocol, a valid extension ID cannot consist of all zeros.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_NEGOTIATE_EXT_VERSION

This OID requests the miniport to return the highest version extension number the miniport is willing to operate under for this device, given the range of possible extension versions.

Support for this request is optional.

This request uses an NDIS_TAPI_NEGOTIATE_EXT_VERSION structure, defined as follows:

typedef struct _NDIS_TAPI_NEGOTIATE_EXT_VERSION { 
    IN ULONG   ulRequestID; 
    IN ULONG   ulDeviceID; 
    IN ULONG   ulLowVersion; 
    IN ULONG   ulHighVersion; 
    OUT ULONG  ulExtVersion; 
} NDIS_TAPI_NEGOTIATE_EXT_VERSION, *PNDIS_TAPI_NEGOTIATE_EXT_VERSION; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceID

Specifies the link or data channel for which the extension version negotiation is to be performed. The value INITIALIZE_NEGOTIATION cannot be used. This was set up in a preceding OID_TAPI_GET_ID request.

ulLowVersion

Specifies the lowest extension version under which NDISTAPI or its client application will operate. The most significant two bytes specify the major version and the least significant two bytes specify the minor version. The value of this member is not validated by NDISTAPI when this request is made.

ulHighVersion

Specifies the highest extension version under which NDISTAPI or its client application will operate. The most significant two bytes specify the major version and the least significant two bytes specify the minor version. The value of this member is not validated by NDISTAPI when this request is made.

ulExtVersion

Specifies the miniport’s extension version within the range specified by ulLowVersion and ulHighVersion. The most significant two bytes specifiy the major version and the least significant two bytes specify the minor version.

The miniport fills this member with the highest extension version number, within the range requested by the caller, under which it is willing to operate to complete this request successfully.

If the requested range specified in ulLowVersion and ulHighVersion does not overlap the range supported by the miniport, it returns NDIS_STATUS_TAPI_INCOMPATIBLEEXTVERSION.

The MiniportQueryInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INCOMPATIBLEEXTVERSION
NDIS_STATUS_TAPI_NODRIVER
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

TAPI Set Information Requests

WAN miniports return no information for set requests other than the completion status. All OID-specific structures are provided by the protocol driver, and their members are read-only to the underlying WAN NIC miniport.

OID_TAPI_ANSWER

This OID requests the miniport to answer the specified call on offer. Optionally, it requests that the miniport send the specified user-to-user information to the calling party.

Support for this request is mandatory.

The OID_TAPI_ANSWER request uses an NDIS_TAPI_ANSWER structure, defined as follows:

typedef struct _NDIS_TAPI_ANSWER { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
    IN ULONG      ulUserUserInfoSize; 
    IN UCHAR      UserUserInfo[1]; 
} NDIS_TAPI_ANSWER, *PNDIS_TAPI_ANSWER; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call to be answered. The driver set this handle up when it called NdisMIndicateStatus with the LINE_EVENT_NEWCALL indication.

ulUserUserInfoSize

Specifies the size in bytes of the user-to-user information in UserUserInfo. If this member is zero, UserUserInfo should be ignored .

UserUserInfo

Specifies a string containing user-to-user information to be sent to the remote party as part of the call accept. User-to-user information is sent only if supported by the underlying network (see OID_TAPI_GET_DEV_CAPS).

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_INVALCALLSTATE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_TAPI_USERUSERINFOTOOBIG
NDIS_STATUS_FAILURE

Upon successful completion of the OID_TAPI_ANSWER request, the miniport must be prepared to respond to the OID_TAPI_GET_ID request.

The initiating application must wait for the LINECALLSTATE_CONNECTED indication before actually writing data.

OID_TAPI_CLOSE

This OID requests the miniport to close the specified open line device.

Support for this request is mandatory.

This request uses an NDIS_TAPI_CLOSE structure, defined as follows:

typedef struct _NDIS_TAPI_CLOSE { 
    IN ULONG      ulRequestID; 
    IN HDRV_LINE  hdLine; 
} NDIS_TAPI_CLOSE, *PNDIS_TAPI_CLOSE; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle to the line to be closed. After the line has been successfully closed, this handle is no longer valid.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING

OID_TAPI_CLOSE_CALL

This OID requests the miniport to close a specified call after completing or terminating all outstanding asynchronous requests on the call.

Support for this request is mandatory.

This request uses an NDIS_TAPI_CLOSE_CALL structure, defined as follows:

typedef struct _NDIS_TAPI_CLOSE_CALL { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
} NDIS_TAPI_CLOSE_CALL, *PNDIS_TAPI_CLOSE_CALL; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call to be closed. After the call has been successfully closed this handle is no longer valid.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING

OID_TAPI_CONDITIONAL_MEDIA_DETECTION

NDISTAPI makes this OID request to NDISWAN, which passes it down to WAN NIC miniports, whenever a client application uses LINEMAPPER as the dwDeviceID in the lineOpen function to request that lines be scanned to find one that supports the desired media mode(s) and call parameters.

NDISTAPI scans based on the union of the desired media modes and the other media modes currently being monitored on the line, to give each WAN miniport the opportunity to indicate whether it can simultaneously monitor for all of the requested media modes.

Support for this request is mandatory.

This request uses an NDIS_TAPI_CONDITIONAL_MEDIA_DETECTION structure, defined as follows:

typedef struct _NDIS_TAPI_CONDITIONAL_MEDIA_DETECTION { 
    IN ULONG             ulRequestID; 
    IN HDRV_LINE         hdLine; 
    IN ULONG             ulMediaModes; 
    IN LINE_CALL_PARAMS  LineCallParams; 
} NDIS_TAPI_CONDITIONAL_MEDIA_DETECTION, 
    *PNDIS_TAPI_CONDITIONAL_MEDIA_DETECTION; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the the miniport’s handle to the line on which media monitoring and parameter capabilites are to be set.

ulMediaModes

Specifies the media mode(s) currently of interest to the calling application. This parameter uses the LINEMEDIAMODE constants. See ndistapi.h for details.

LineCallParams

The LINE_CALL_PARAMS structure specifies information that the line device should provide. The only relevent members for the purpose of this request are the following:

ULONG ulBearerMode;

ULONG ulMinRate;

ULONG ulMaxRate;

ULONG ulMediaMode;

ULONG ulCallParamFlags;

ULONG ulAddressMode;

If the value of ulAddressMode is LINEADDRESSMODE_ADDRESSID, any address on the line is acceptable. Otherwise, the value of ulAddressMode is LINEADDRESSMODE_DIALABLEADDR, indicating either that the miniport should search for a specific originating address (phone number), or, if it is a provider-specific extension, the ulOrigAddressSize/Offset and the ulDevSpecificSize/Offset values are also relevant. All other members of the LINE_CALL_PARAMS structure are irrelevant to this OID request.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_NODRIVER
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_TAPI_INVALMEDIAMODE
NDIS_STATUS_FAILURE

If a miniport can monitor for the specified set of media modes and support the capabilities specified in CallParams, it completes the request with NDIS_STATUS_SUCCESS, but it leaves the active media monitoring modes for the line unchanged.

OID_TAPI_DROP

This OID requests the miniport to drop or disconnect the specified call.

User-to-user information can optionally be transmitted as part of the call disconnect. This request can be made by the application at any time.

Support for this request is mandatory.

This request uses an NDIS_TAPI_DROP structure, defined as follows:

typedef struct _NDIS_TAPI_DROP { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
    IN ULONG      ulUserUserInfoSize; 
    IN UCHAR      UserUserInfo[1]; 
} NDIS_TAPI_DROP, *PNDIS_TAPI_DROP; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call to be dropped.

ulUserUserInfoSize

Specifies the size in bytes of the user-to-user information in UserUserInfo. If this member is zero, the miniport should ignore the next member.

UserUserInfo

Specifies a string containing user-to-user information to be sent to the remote party as part of the call drop. User-to-user information is sent only if supported by the underlying network (see OID_TAPI_GET_DEV_CAPS).

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_INVALCALLSTATE
NDIS_STATUS_TAPI_USERUSERINFOTOOBIG
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

When a miniport completes this request successfully, the call should be in the idle state. However, the miniport can still receive requests, such as statistics queries, specifying the hdCall handle until it completes the OID_TAPI_CLOSE_CALL request for this handle.

OID_TAPI_PROVIDER_SHUTDOWN

This OID requests the miniport to shut down its TAPI operations when TAPI is cleaning up its state because applications are no longer using TAPI services.

On receipt of this OID, the miniport should terminate any activities associated with TAPI that it has in progress, call NdisMIndicateStatus with NDIS_MAC_LINE_DOWN to NDISWAN for any lines currently open, and clean up any state it was using to track TAPI operations.

Support for this request is mandatory.

This request uses an NDIS_TAPI_PROVIDER_SHUTDOWN structure, defined as follows:

typedef struct _NDIS_TAPI_PROVIDER_SHUTDOWN { 
    IN ULONG  ulRequestID; 
} NDIS_TAPI_PROVIDER_SHUTDOWN, *PNDIS_TAPI_PROVIDER_SHUTDOWN; 
 

The member of this structure contains the following information:

ulRequestID

Reserved.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SET_APP_SPECIFIC

This OID requests the miniport to set the ulAppSpecific member of the specified call’s LINECALLINFO structure. See ndistapi.h for details of this structure.

Support for this request is mandatory.

This request uses an NDIS_TAPI_SET_APP_SPECIFIC structure, defined as follows:

typedef struct _NDIS_TAPI_SET_APP_SPECIFIC { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
    IN ULONG      ulAppSpecific; 
} NDIS_TAPI_SET_APP_SPECIFIC, *PNDIS_TAPI_SET_APP_SPECIFIC; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call for which the application-specific member is to be set.

ulAppSpecific

Specifies the new content of the ulAppSpecific member for the call’s LINECALLINFO structure. This value is uninterpreted by the NIC driver. The value is not validated by NDISTAPI when this request is made.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SET_CALL_PARAMS

This OID requests the miniport to set certain call parameters for an existing call.

Support for this request is mandatory.

This request uses an NDIS_TAPI_SET_CALL_PARAMS structure, defined as follows:

struct _NDIS_TAPI_SET_CALL_PARAMS { 
    IN ULONG             ulRequestID; 
    IN HDRV_CALL         hdCall; 
    IN ULONG             ulBearerMode; 
    IN ULONG             ulMinRate; 
    IN ULONG             ulMaxRate; 
    IN BOOLEAN           bSetLineDialParams; 
    IN LINE_DIAL_PARAMS  LineDialParams; 
} NDIS_TAPI_SET_CALL_PARAMS, *PNDIS_TAPI_SET_CALL_PARAMS; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call for which the following parameters are to be changed.

ulBearerMode

Specifies the new bearer mode for the call. This member can have only one of the following LINEBEARERMODE flags set:

LINEBEARERMODE_VOICE

LINEBEARERMODE_SPEECH

LINEBEARERMODE_MULTIUSE

LINEBEARERMODE_DATA

LINEBEARERMODE_ALTSPEECHDATA

LINEBEARERMODE_NONCALLSIGNALING

ulMinRate

Specifies a lower bound for the call’s new data rate. The value of this member is not validated by NDISTAPI before the miniport is called.

This value indicates that the caller is willing to accept a new rate as low as this one.

ulMaxRate

Specifies an upper bound for the call’s new data rate. The value of this member is not validated by NDISTAPI before the miniport is called.

This value indicates the maximum data rate the caller would like.

Equal values for the ulMinRate and ulMaxRate members indicate that the caller requires an exact rate.

bSetLineDialParams

Specifies whether the following dialing parameters should be used for the call. If this member is FALSE, the call’s current dialing parameters should be used and the next member should be ignored.

LineDialParams

This structure specifies the new dial parameters for the call. See ndistapi.h for details.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_INVALCALLSTATE
NDIS_STATUS_TAPI_INVALBEARERMODE
NDIS_STATUS_TAPI_BEARERMODEUNAVAIL
NDIS_STATUS_TAPI_INVALRATE
NDIS_STATUS_TAPI_RATEUNAVAIL
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SET_DEFAULT_MEDIA_DETECTION

This OID requests the miniport to use a new set of media modes to detect for the indicated line, thereby replacing whatever set it was using.

The miniport must not notify NDISWAN of an incoming call unless this request has been successfully completed for the incoming call’s media mode.

Support for this request is mandatory.

This request uses an NDIS_TAPI_SET_DEFAULT_MEDIA_DETECTION structure, defined as follows:

typedef struct _NDIS_TAPI_SET_DEFAULT_MEDIA_DETECTION { 
    IN ULONG      ulRequestID; 
    IN HDRV_LINE  hdLine; 
    IN ULONG      ulMediaModes; 
} NDIS_TAPI_SET_DEFAULT_MEDIA_DETECTION, 
    *PNDIS_TAPI_SET_DEFAULT_MEDIA_DETECTION; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle to the line for which the default media mode should be set.

ulMediaModes

Specifies the media mode(s) of interest to NDISTAPI. This member is set with one or more of the LINEMEDIAMODE constants. See ndistapi.h for details.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_INVALMEDIAMODE
NDIS_STATUS_TAPI_NODRIVER
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SET_DEV_CONFIG

This OID requests the miniport to restore the configuration of a device associated one-to-one with the line device from a configuration previously obtained using OID_TAPI_GET_DEV_CONFIG.

The contents of this structure are specific to the miniport’s line and device class.

Support for this request is mandatory.

This request uses an NDIS_TAPI_SET_DEV_CONFIG structure, defined as follows:

typedef struct _NDIS_TAPI_SET_DEV_CONFIG { 
    IN ULONG  ulRequestID; 
    IN ULONG  ulDeviceID; 
    IN ULONG  ulDeviceClassSize; 
    IN ULONG  ulDeviceClassOffset; 
    IN ULONG  ulDeviceConfigSize; 
    IN UCHAR  DeviceConfig[1]; 
} NDIS_TAPI_SET_DEV_CONFIG, *PNDIS_TAPI_SET_DEV_CONFIG; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

ulDeviceID

Specifies the line device to be configured. This value was set up in a preceding OID_TAPI_PROVIDER_INITIALIZE request.

ulDeviceClassSize

Specifies the size in bytes of the device class for the device whose configuration is to be restored. Valid device class strings are the same as those specified for the OID_TAPI_GET_ID request when it is applied to a “line” device (ulSelect has the value LINECALLSELECT_LINE).

ulDeviceClassOffset

Specifies the offset in bytes to the device class of the device whose configuration is to be restored.

ulDeviceConfigSize

Specifies the number of bytes at DeviceConfig. This value was already returned in the ulStringSize member in the VAR_STRING structure returned for a preceding OID_TAPI_GET_DEV_CONFIG request.

DeviceConfig

Specifies data that was returned in the variable portion of the VAR_STRING structure for a preceding OID_TAPI_GET_DEV_CONFIG request.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALDEVICECLASS
NDIS_STATUS_TAPI_INVALPARAM
NDIS_STATUS_TAPI_NODRIVER
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SET_MEDIA_MODE

This OID requests the miniport to change a call’s media mode as stored in the LINE_CALL_INFO structure for that call. See ndistapi.h for the declaration of LINE_CALL_INFO.

Support for this request is mandatory.

This request uses an NDIS_TAPI_SET_MEDIA_MODE structure, defined as follows:

typedef struct _NDIS_TAPI_SET_MEDIA_MODE { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
    IN ULONG      ulMediaMode; 
} NDIS_TAPI_SET_MEDIA_MODE, *PNDIS_TAPI_SET_MEDIA_MODE; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call for which it should change the media mode.

ulMediaMode

Specifies the new media mode(s) for the call as one or more of the LINEMEDIAMODE_XXX flags.

If the LINEMEDIAMODE_UNKNOWN flag is set, other media mode flags also can be set. Such a combination of flags specifies that the call’s media mode is not fully determined, but that it has been narrowed down to a subset of possible media modes. If the LINEMEDIAMODE_UNKNOWN flag is clear, only a single media mode can be specified.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_INVALMEDIAMODE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SET_STATUS_MESSAGES

This OID requests the miniport to allow NDISTAPI to specify which notification messages the miniport should generate for events related to status changes for the specified line or any of its addresses.

By default, address-status and line-status reporting is initially disabled for a line.

Support for this request is mandatory.

This request uses an NDIS_TAPI_SET_STATUS_MESSAGES structure, defined as follows:

typedef struct _NDIS_TAPI_SET_STATUS_MESSAGES { 
    IN ULONG      ulRequestID; 
    IN HDRV_LINE  hdLine; 
    IN ULONG      ulLineStates; 
    IN ULONG      ulAddressStates; 
} NDIS_TAPI_SET_STATUS_MESSAGES, *PNDIS_TAPI_SET_STATUS_MESSAGES; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the miniport’s handle to the line device.

ulLineStates

Specifies a bit array that identifies status changes for which messages should be sent to NDISTAPI. This parameter uses the LINEDEVSTATE constants. See ndistapi.h for details.

ulAddressStates

Specifies a bit array that identifies which address status changes the miniport should monitor to send appropriate notifications to NDISTAPI. The value is an ORed combination of LINEADDRESSSTATE flags. See ndistapi.h for details.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALLINEHANDLE
NDIS_STATUS_TAPI_INVALLINESTATE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_ACCEPT

This OID requests the miniport to accept the specified call. Optionally, it requests that the miniport send the specified user-to-user information to the calling party.

Support for this request is optional.

The request uses an NDIS_TAPI_ACCEPT structure, defined as follows:

typedef struct _NDIS_TAPI_ACCEPT { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
    IN ULONG      ulUserUserInfoSize; 
    IN UCHAR      UserUserInfo[1]; 
} NDIS_TAPI_ACCEPT, *PNDIS_TAPI_ACCEPT; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call to be accepted. The driver set this handle up when it called NdisMIndicateStatus with the LINE_EVENT_NEWCALL indication.

ulUserUserInfoSize

Specifies the size in bytes of the user-to-user information in UserUserInfo. If this member is zero, the miniport should ignore the next member.

UserUserInfo

Specifies a string containing user-to-user information to be sent to the remote party as part of the call-accept operation. User-to-user information is sent only if supported by the underlying network (see OID_TAPI_GET_DEV_CAPS).

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_INVALCALLSTATE
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_TAPI_USERUSERINFOTOOBIG
NDIS_STATUS_FAILURE

OID_TAPI_DIAL

This OID requests the miniport to dial the specified number on the specified call.

Support for this request is optional.

This request uses an NDIS_TAPI_DIAL structure, defined as follows:

typedef struct _NDIS_TAPI_DIAL { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
    IN ULONG      ulDestAddressSize; 
    IN CHAR       szDestAddress[1]; 
} NDIS_TAPI_DIAL, *PNDIS_TAPI_DIAL; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call for which it should dial. This handle was set up in a preceding OID_TAPI_MAKE_CALL request.

ulDestAddressSize

Specifies the size in bytes of the address in the next member.

szDestAddress

Specifies the destination to be dialed in standard dialable number format.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_INVALADDRESS
NDIS_STATUS_TAPI_INVALCALLSTATE
NDIS_STATUS_TAPI_ADDRESSBLOCKED
NDIS_STATUS_TAPI_DIALBILLING
NDIS_STATUS_TAPI_DIALQUIET
NDIS_STATUS_TAPI_DIALDIALTONE
NDIS_STATUS_TAPI_DIALPROMPT
NDIS_STATUS_TAPI_OPERATIONUNAVAIL
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SECURE_CALL

This OID requests the miniport to secure a particular call from any interruptions or interference that can affect the call’s media stream.

Support for this request is optional.

This request uses an NDIS_TAPI_SECURE_CALL structure, defined as follows:

typedef struct _NDIS_TAPI_SECURE_CALL { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
} NDIS_TAPI_SECURE_CALL, *PNDIS_TAPI_SECURE_CALL; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call to be secured.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_INVALCALLSTATE
NDIS_STATUS_TAPI_OPERATIONUNAVAIL
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SELECT_EXT_VERSION

This OID requests the miniport to select the indicated extension version for the indicated line device. Subsequent requests on the line operate according to the selected extension version.

Support for this request is optional.

This request uses an NDIS_TAPI_SELECT_EXT_VERSION structure, defined as follows:

typedef struct _NDIS_TAPI_SELECT_EXT_VERSION { 
    IN ULONG      ulRequestID; 
    IN HDRV_LINE  hdLine; 
    IN ULONG      ulExtVersion; 
} NDIS_TAPI_SELECT_EXT_VERSION, *PNDIS_TAPI_SELECT_EXT_VERSION; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdLine

Specifies the handle to the line for which the extension version is to be selected.

ulExtVersion

Specifies the extension version to be selected. The most significant two bytes specify the major version number, and the least significant two bytes specify the minor version number. Zero indicates the miniport should cancel the current selection.

This version has been negotiated in a preceding OID_TAPI_NEGOTIATE_EXT_VERSION request.

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INCOMPATIBLEEXTVERSION
NDIS_STATUS_TAPI_OPERATIONUNAVAIL
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE

OID_TAPI_SEND_USER_USER_INFO

This OID requests the miniport to send user-to-user information to the remote party on the specified call.

Support for this request is optional.

This request uses an NDIS_TAPI_SEND_USER_USER_INFO structure, defined as follows:

typedef struct _NDIS_TAPI_SEND_USER_USER_INFO { 
    IN ULONG      ulRequestID; 
    IN HDRV_CALL  hdCall; 
    IN ULONG      ulUserUserInfoSize; 
    IN UCHAR      UserUserInfo[1]; 
} NDIS_TAPI_SEND_USER_USER_INFO, *PNDIS_TAPI_SEND_USER_USER_INFO; 
 

The members of this structure contain the following information:

ulRequestID

Reserved.

hdCall

Specifies the miniport’s handle to the call on which to send user-to-user information.

ulUserUserInfoSize

Specifies the size in bytes of the UserUserInfo string.

UserUserInfo

Specifies a string containing user-to-user information to be sent to the remote party as part of a call-accept operation. User-to-user information is sent only if supported by the underlying network (see OID_TAPI_GET_DEV_CAPS).

The MiniportSetInformation function can return one of the following:
NDIS_STATUS_SUCCESS
NDIS_STATUS_PENDING
NDIS_STATUS_TAPI_INVALCALLHANDLE
NDIS_STATUS_TAPI_INVALCALLSTATE
NDIS_STATUS_TAPI_USERUSERINFOTOOBIG
NDIS_STATUS_TAPI_OPERATIONUNAVAIL
NDIS_STATUS_TAPI_RESOURCEUNAVAIL
NDIS_STATUS_FAILURE