ProtocolRequestComplete

ProtocolRequestComplete

VOID
ProtocolRequestComplete(
IN NDIS_HANDLE ProtocolBindingContext,
IN PNDIS_REQUEST NdisRequest,
IN NDIS_STATUS Status
);

ProtocolRequestComplete is a required driver function that completes the processing of a protocol-initiated query or set for which NdisRequest returned NDIS_STATUS_PENDING.

Parameters

ProtocolBindingContext

Specifies the handle to a protocol-allocated context area in which the protocol driver maintains per-binding runtime state. The driver supplied this handle when it called NdisOpenAdapter.

NdisRequest

Points to the protocol-supplied structure previously passed to NdisRequest.

Status

Specifies the final status of the request set by the underlying driver or by NDIS. This argument determines what ProtocolRequestComplete does with the information at NdisRequest.

Comments

ProtocolRequestComplete uses the input Status as follows:

·If this argument is NDIS_STATUS_SUCCESS, the BytesRead or BytesWritten member of the NDIS_REQUEST structure has been set by NDIS or the underlying driver to specify how much protocol-supplied information was transferred from the buffer at InformationBuffer to the NIC in a set operation or how much information was returned at InformationBuffer in response to a query operation.

If the protocol made a query, ProtocolRequestComplete can use the data returned at InformationBuffer in any protocol-determined way, depending on the value of the Oid member.

For example, if the protocol originally initiated an OID_GEN_MAXIMUM_SEND_PACKETS query, ProtocolRequestComplete 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 NdisSendPackets.

·If this argument 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 carry out the requested operation.

In these circumstances, ProtocolRequestComplete can allocate sufficient buffer space for the request, set up another NDIS_REQUEST structure with the required InformationBufferLength and same Oid, and retry the call to NdisRequest.

ProtocolRequestComplete can retry requests for certain other NDIS_STATUS_XXX arguments, as well, as described in the reference for NdisRequest.

·If this argument is an NDIS_STATUS_XXX that is an unrecoverable error, ProtocolRequestComplete should release the memory allocated for the NDIS_REQUEST structure and determine whether the driver should call NdisReset, 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 miniport's call to NdisMQueryInformationComplete or NdisMSetInformationComplete causes NDIS to call the ProtocolRequestComplete function. NDIS forwards the miniport-determined Status passed to NdisM..InformationComplete as the input Status to ProtocolRequestComplete.

For binding-specific queries, NDIS calls the ProtocolRequestComplete function itself. Because the NDIS library maintains bindings for all miniports, 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-initiated binding-specific queries to other miniports.

For more information about system-defined OIDs, see Chapter 5.

ProtocolRequestComplete can be called before the protocol has had time to inspect the status code that NdisRequest returns at Status.

The ProtocolRequestComplete function of an NDIS intermediate driver cannot simply forward completion indications to still higher-level protocols. Such an attempt can cause a deadlock. Instead, such a driver must call NdisIMSwitchToMiniport to forward the indication from the appropriate context. If NdisIMSwitchToMiniport returns FALSE, the driver must call NdisIMQueueMiniportCallback and forward the indication from a protocol-supplied MiniportCallback function.

By default, ProtocolRequestComplete runs at IRQL DISPATCH_LEVEL in an arbitrary thread context.