PROTOCOL_CO_OID_REQUEST callback function (ndis.h)

Article
10/21/2021

The ProtocolCoOidRequest function handles OID requests that CoNDIS clients or stand-alone call managers initiate by calls to the NdisCoOidRequest function or that a miniport call manager (MCM) driver initiates by calls to the NdisMCmOidRequest function.

Note You must declare the function by using the PROTOCOL_CO_OID_REQUEST type. For more information, see the following Examples section.

Syntax

PROTOCOL_CO_OID_REQUEST ProtocolCoOidRequest;

NDIS_STATUS ProtocolCoOidRequest(
  [in]      NDIS_HANDLE ProtocolAfContext,
  [in]      NDIS_HANDLE ProtocolVcContext,
  [in]      NDIS_HANDLE ProtocolPartyContext,
  [in, out] PNDIS_OID_REQUEST OidRequest
)
{...}

Parameters

[in] ProtocolAfContext

A handle that identifies an address family (AF) context area. If the driver is a client, it supplied this handle when it called the NdisClOpenAddressFamilyEx function to connect itself to the call manager. If the driver is a call manager, it supplied this handle from its ProtocolCmOpenAf function.

[in] ProtocolVcContext

A handle that identifies the virtual connection (VC) to query or set information on, if the request is VC-specific. Otherwise, this parameter is NULL.

[in] ProtocolPartyContext

A handle that identifies the party on a multipoint VC to query or set information on, if the request is party-specific. Otherwise, this parameter is NULL.

[in, out] OidRequest

A pointer to an NDIS_OID_REQUEST structure that contains both the buffer and the request packet for the target driver to handle. Depending on the request, the driver returns requested information in the structure that OidRequest points to.

Return value

ProtocolCoOidRequest can return one of the following:

Return code	Description
NDIS_STATUS_SUCCESS	The client or call manager carried out the requested operation.
NDIS_STATUS_PENDING	The client, or call manager is handling this request asynchronously, and it will call the NdisCoOidRequestComplete function or the NdisMCmOidRequestComplete function when the requested operation is complete.
NDIS_STATUS_INVALID_LENGTH or NDIS_STATUS_BUFFER_TOO_SHORT	The driver is failing the request because the caller of the NdisCoOidRequest or NdisMCmOidRequest function did not supply an adequate value for the InformationBuffer member of the NDIS_OID_REQUEST structure for the given request. The driver set the BytesNeeded member of NDIS_OID_REQUEST in the buffer at the OidRequest parameter to the OID-specific value of the InformationBufferLength member that is required to carry out the requested operation.
NDIS_STATUS_XXX	The client or call manager failed the request for some driver-determined reason, such as invalid input data that was specified for a set.
NDIS_STATUS_NOT_SUPPORTED	The client or call manager failed this request because it did not recognize the OID_GEN_CO_XXX code in the Oid member in the buffer at NdisRequest.

Remarks

The ProtocolCoOidRequest function is required for CoNDIS clients, call managers, and MCMs. ProtocolCoOidRequest is similar to the miniport driver's MiniportCoOidRequest function.

CoNDIS clients and call managers send information to each other by specifying a non-NULL value in the NdisAfHandle parameter when they call the NdisCoOidRequest function. Similarly, MCMs call the NdisMCmOidRequest with explicit values for NdisAfHandle to communicate information to clients. Such calls to NdisCoOidRequest or NdisMCmOidRequest cause NDIS to call the ProtocolCoOidRequest function of the targeted client, call manager, or MCM that is associated with the specified AF handle.

To register ProtocolCoOidRequest as a client, a driver initializes an NDIS_CO_CLIENT_OPTIONAL_HANDLERS structure and passes it at the OptionalHandlers parameter of the NdisSetOptionalHandlers function. To register ProtocolCoOidRequest as a call manager, a driver initializes an NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS structure and passes it at the OptionalHandlers parameter.

If the NdisVcHandle and NdisPartyHandle parameters of NdisCoOidRequest or NdisMCmOidRequest are NULL, the request is global in nature. That is, an explicit value for NdisVcHandle or NdisPartyHandle indicates that ProtocolCoOidRequest should satisfy the given request on a per-VC or per-party basis, respectively.

The buffer at the OidRequest parameter was allocated from nonpaged pool and is, therefore, accessible at raised IRQL. The caller of NdisCoOidRequest(or NdisMCmOidRequest) must release this buffer and the internal buffer at the InformationBuffer member of the NDIS_OID_REQUEST structure that OidRequest points to.

If ProtocolCoOidRequest returns NDIS_STATUS_PENDING, the driver must subsequently call the NdisCoOidRequestComplete function, or the NdisMCmOidRequestComplete function for an MCM driver, when the driver completes the request.

Examples

To define a ProtocolCoOidRequest function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a ProtocolCoOidRequest function that is named "MyCoOidRequest", use the PROTOCOL_CO_OID_REQUEST type as shown in this code example:

PROTOCOL_CO_OID_REQUEST MyCoOidRequest;

Then, implement your function as follows:

_Use_decl_annotations_
NDIS_STATUS
 MyCoOidRequest(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest
    )
  {...}

The PROTOCOL_CO_OID_REQUEST function type is defined in the Ndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the PROTOCOL_CO_OID_REQUEST function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.0 and later.
Target Platform	Windows
Header	ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL