Share via

ProtocolOidRequestComplete (Compact 2013)

  • Article

3/26/2014

This function completes the processing of a protocol driver-initiated OID request for which the NdisOidRequest function returned NDIS_STATUS_PENDING.

Syntax

VOID
  ProtocolOidRequestComplete(
    IN NDIS_HANDLE  ProtocolBindingContext,
    IN PNDIS_OID_REQUEST  OidRequest,
    IN NDIS_STATUS  Status
    );

Parameters

  • ProtocolBindingContext
    A handle to a protocol driver-allocated context area in which the protocol driver maintains per-binding run-time state. The driver supplied this handle when it called the NdisOpenAdapterEx function.
  • OidRequest
    A pointer to the protocol driver-supplied NDIS_OID_REQUEST structure that was previously passed to the NdisOidRequest function.
  • Status
    The final status of the request. The underlying driver or NDIS determines this final status. This parameter determines what ProtocolOidRequestComplete does with the information at OidRequest.

Return Value

None

Remarks

ProtocolOidRequestComplete 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 has been set by NDIS or the underlying driver to specify how much protocol driver-supplied information was transferred from the buffer at InformationBuffer to the network adapter in a set operation or how much information was returned at InformationBuffer in response to a query operation.
  • If the protocol driver made a query, ProtocolOidRequestComplete can use the data returned at InformationBuffer in any way determined by the protocol driver, depending on the value of the Oid member.
  • For example, if the protocol driver originally initiated an OID_GEN_MAXIMUM_SEND_PACKETS query, ProtocolOidRequestComplete might set up state variables in the ProtocolBindingContext area to throttle the number of outstanding sends the driver will set up for subsequent calls to the NdisSendNetBufferLists function.
  • If Status is NDIS_STATUS_INVALID_LENGTH or NDIS_STATUS_BUFFER_TOO_SHORT, the BytesNeeded member specifies the OID-specific value of the InformationBufferLength member required to perform the requested operation.
  • In these circumstances, ProtocolOidRequestComplete can allocate sufficient buffer space for the request, set up another NDIS_OID_REQUEST structure with the required InformationBufferLength and same Oid, and retry the call to the NdisOidRequest function.
  • ProtocolOidRequestComplete can retry requests for certain other NDIS_STATUS_XXX arguments, additionally, as described in the reference for the NdisOidRequest function.
  • If Status is an NDIS_STATUS_XXX value that is an unrecoverable error, ProtocolOidRequestComplete should release the memory allocated for the NDIS_OID_REQUEST structure and 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 global queries and sets, the underlying connectionless miniport driver's call to the NdisMOidRequestComplete function causes NDIS to call the ProtocolOidRequestComplete function. NDIS forwards the miniport driver-determined Status passed to NdisMOidRequestComplete as the input Status to ProtocolOidRequestComplete.

For binding-specific queries, NDIS calls the ProtocolOidRequestComplete function itself. Because the NDIS library maintains bindings for all miniport drivers, NDIS can return binding-specific information only about underlying drivers that report their medium-type as one for which the system provides a filter library. NDIS returns NDIS_STATUS_NOT_SUPPORTED for protocol driver-initiated binding-specific queries to other miniport drivers.

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

ProtocolOidRequestComplete can be called before the protocol driver has had time to inspect the status code that NdisOidRequest returns at Status.

NDIS calls ProtocolOidRequestComplete at IRQL <= DISPATCH_LEVEL.

See Also

Reference

NDIS OID Request Interface for Protocol Drivers
NDIS_OID_REQUEST
NdisMOidRequestComplete
NdisOpenAdapterEx
NdisOidRequest
OID_GEN_MAXIMUM_SEND_PACKETS
NDIS OID Request Interface for Filter Drivers