PROTOCOL_CO_OID_REQUEST callback function

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.



NDIS_STATUS ProtocolCoOidRequest(
  _In_    NDIS_HANDLE       ProtocolAfContext,
  _In_    NDIS_HANDLE       ProtocolVcContext,
  _In_    NDIS_HANDLE       ProtocolPartyContext,
  _Inout_ PNDIS_OID_REQUEST OidRequest
{ ... }


ProtocolAfContext [in]

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.

ProtocolVcContext [in]

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.

ProtocolPartyContext [in]

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.

OidRequest [in, out]

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 codeDescription

The client or call manager carried out the requested operation.


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.


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.


The client or call manager failed the request for some driver-determined reason, such as invalid input data that was specified for a set.


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.



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.


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:


Then, implement your function as follows:

    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,

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.



Supported in NDIS 6.0 and later.


Ndis.h (include Ndis.h)



See also




Send comments about this topic to Microsoft