PROTOCOL_CO_OID_REQUEST_COMPLETE callback function (ndis.h)

Article
10/21/2021

The ProtocolCoOidRequestComplete function completes the processing of an asynchronous CoNDIS OID request.

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

Syntax

PROTOCOL_CO_OID_REQUEST_COMPLETE ProtocolCoOidRequestComplete;

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

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 or miniport call manager (MCM), it supplied this handle from its ProtocolCmOpenAf function.

[in] ProtocolVcContext

A handle that identifies the active virtual connection (VC) that the driver requested or set information for, if the request was VC-specific. Otherwise, this parameter is NULL.

[in] ProtocolPartyContext

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

[in, out] OidRequest

A pointer to the driver-supplied NDIS_OID_REQUEST structure that was previously passed to the NdisCoOidRequest or NdisMCmOidRequest function.

[in] Status

The final status of the request. The target driver or NDIS determines this final status. This parameter determines what ProtocolCoOidRequestComplete does with the information at OidRequest.

Return value

None

Remarks

NDIS calls the ProtocolCoOidRequestComplete function to complete the processing of CoNDIS client, call manager, or MCM OID request for which the NdisCoOidRequest function or NdisMCmOidRequest function returned NDIS_STATUS_PENDING.

To register ProtocolCoOidRequestComplete 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 ProtocolCoOidRequestComplete as a call manager, a driver initializes an NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS structure and passes it at the OptionalHandlers parameter of NdisSetOptionalHandlers.

The target driver is the driver that serviced the OID information request. A target driver's call to the NdisMCoOidRequestComplete, NdisCoOidRequestComplete, or NdisMCmOidRequestComplete function caused NDIS to call the ProtocolCoOidRequestComplete function. NDIS forwards the value of the Status parameter that was passed to these functions as the input Status parameter to ProtocolCoOidRequestComplete.

ProtocolCoOidRequestComplete uses the input value of Status as follows:

If Status is NDIS_STATUS_SUCCESS, the BytesRead or BytesWritten member of the NDIS_OID_REQUEST structure that the OidRequest parameter points to specifies how much information was transferred from the buffer in the InformationBuffer member of NDIS_OID_REQUEST to the target driver or how much information was returned at InformationBuffer, respectively.
If the driver made a query request, ProtocolCoOidRequestComplete can use the data that is returned in InformationBuffer as appropriate for the value that is specified in the Oid member of NDIS_OID_REQUEST.
If Status is NDIS_STATUS_INVALID_LENGTH or NDIS_STATUS_BUFFER_TOO_SHORT, the BytesNeeded member of the NDIS_OID_REQUEST structure that OidRequest points to specifies the OID-specific value of the InformationBufferLength member of NDIS_OID_REQUEST that is required to carry out the requested operation.
In these circumstances, ProtocolCoOidRequestComplete can allocate sufficient buffer space for the request, set up another NDIS_OID_REQUEST structure with the required value for InformationBufferLength, and retry the OID request.
If Status is an NDIS_STATUS_ XXX value that is an unrecoverable error, ProtocolCoOidRequestComplete should release the memory for the NDIS_OID_REQUEST structure. ProtocolCoOidRequestComplete should also determine whether the driver should close the binding or adjust its binding-specific state information to handle continued network I/O operations on the binding.

For more information about system-defined OIDs, see NDIS OIDs.

ProtocolCoOidRequestComplete can be called before the driver has had time to inspect the status code that NdisCoOidRequest or NdisMCmOidRequest returns.

NDIS calls ProtocolCoOidRequestComplete at IRQL <= DISPATCH_LEVEL.

Examples

To define a ProtocolCoOidRequestComplete 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 ProtocolCoOidRequestComplete function that is named "MyCoOidRequestComplete", use the PROTOCOL_CO_OID_REQUEST_COMPLETE type as shown in this code example:

PROTOCOL_CO_OID_REQUEST_COMPLETE MyCoOidRequestComplete;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyCoOidRequestComplete(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  ProtocolPartyContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

The PROTOCOL_CO_OID_REQUEST_COMPLETE 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_COMPLETE 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 (see Remarks section)