ProtocolRequestComplete (Windows Embedded CE 6.0)

1/6/2010

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

Syntax

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

Parameters

• ProtocolBindingContext
  [in] 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
  [in] Points to the protocol-supplied structure previously passed to NdisRequest.

• Status
  [in] 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.

Return Value

None.

Remarks

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 network adapter 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 connectionless miniport's call to NdisMQueryInformationComplete or NdisMSetInformationComplete causes NDIS to call the ProtocolRequestComplete function. NDIS forwards the miniport-determined Status passed to NdisMXXXInformationComplete 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.

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

Requirements

See Also

Reference

NDIS Lower-Edge Functions
NdisRequest
NDIS_REQUEST
NdisMQueryInformationComplete
NdisMSetInformationComplete
NdisOpenAdapter
NdisReset
NdisSendPackets