ProtocolCoOidRequest routine

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,
  _Inout_  PNDIS_OID_REQUEST OidRequest
)
{ ... }

Parameters

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
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

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

<= DISPATCH_LEVEL

See also

MiniportCoOidRequest
NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS
NDIS_CO_CLIENT_OPTIONAL_HANDLERS
NDIS_OID_REQUEST
NdisClOpenAddressFamilyEx
NdisCoOidRequest
NdisCoOidRequestComplete
NdisMCmOidRequest
NdisMCmOidRequestComplete
NdisSetOptionalHandlers
ProtocolCmOpenAf

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft