NdisCoGetTapiCallId function (ndis.h)

NdisCoGetTapiCallId retrieves a string that TAPI applications can use to identify a particular NDIS virtual connection (VC).

Syntax

NDIS_STATUS NdisCoGetTapiCallId(
  [in]      NDIS_HANDLE NdisVcHandle,
  [in, out] PVAR_STRING TapiCallId
);

Parameters

[in] NdisVcHandle

Specifies the NDIS handle to the VC. This handle was supplied by NDIS when the VC was originally created with the NdisCoCreateVc function.

[in, out] TapiCallId

Pointer to a caller-allocated buffer that receives a data structure of type VAR_STRING. Upon successful return, this structure describes a string that TAPI applications can use to identify the VC.

Return value

Returns one of the following status values:

Return code Description
NDIS_STATUS_SUCCESS
NDIS successfully returned a string identifier for the VC.
NDIS_STATUS_BUFFER_TOO_SHORT
The ulTotalSize member of the VAR_STRING structure specifies that the size of the buffer is not large enough to hold the string that identifies the VC. NdisCoGetTapiCallId sets the ulNeededSize member of the VAR_STRING structure to the required size in bytes.
NDIS_STATUS_INVALID_DATA
The handle to the VC specified by NdisVcHandle is not valid.

Remarks

Suppose a call manager calls NdisCoCreateVc to create a VC for a TAPI call. NDIS in turn supplies the handle to the VC to a client. The client passes this VC handle in a call to the NdisCoGetTapiCallId function to retrieve a string that identifies the VC. The client can pass this string identifier to a TAPI application to identify the VC.

The client creates a context for each VC that it manages. The client uses NdisCoGetTapiCallId to retrieve a string identifier for each VC. The client passes each string identifier to a TAPI application to identify each VC. Later, if a TAPI application passes one of these string identifiers down to the client in a VC-related operation, the client must pass this string identifier as a Unicode string in a call to NdisClGetProtocolVcContextFromTapiCallId to get back the correct context for the VC.

For more information about the VAR_STRING structure, see TAPI Objects.

Requirements

Requirement Value
Minimum supported client Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisCoGetTapiCallId (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisCoGetTapiCallId (NDIS 5.1)) in Windows XP.
Target Platform Desktop
Header ndis.h (include Ndis.h)
Library Ndis.lib
IRQL DISPATCH_LEVEL
DDI compliance rules Irql_Connection_Function(ndis)

See also

NdisClGetProtocolVcContextFromTapiCallId

NdisCoCreateVc