NdisIMQueueMiniportCallback

NdisIMQueueMiniportCallback

NDIS_STATUS
   NdisIMQueueMiniportCallback(
       IN NDIS_HANDLE MiniportAdapterHandle,
       IN W_MINIPORT_CALLBACK CallbackRoutine,
       IN PVOID CallbackContext
       );

NdisIMQueueMiniportCallback calls an intermediate driver’s callback function when it can execute in a MiniportXxx context, as, for example, to forward an indication to higher level protocols.

Parameters

MiniportAdapterHandle

Specifies the handle input to MiniportInitialize.

CallbackRoutine

Specifies the entry point of a driver-supplied function, declared as follows:

VOID
   MiniportCallback(
        IN NDIS_HANDLE MiniportAdapterContext,
        IN PVOID CallbackContext
        );

Parameters to the MiniportCallback function include the following:

MiniportAdapterContext

Specifies the handle to a miniport-allocated per-NIC context area, set up by MiniportInitialize.

CallbackContext

Specifies the driver-supplied pointer passed to NdisIMQueueMiniportCallback.

CallbackContext

Points to a caller-determined context. This pointer will be passed as an input parameter to the driver’s callback function when it is run.

For example, this parameter might point to a caller-allocated area containing an array of pointers to packets to be indicated to higher-level protocols.

Return Value

NdisIMQueueMiniportCallback can return one of the following:

NDIS_STATUS_SUCCESS

The function at CallbackRoutine has been run.

NDIS_STATUS_PENDING

The function at CallbackRoutine will be run asynchronously.

NDIS_STATUS_FAILURE

NDIS could not run the function at CallbackRoutine at this time, possibly due to resource constraints. This return does not necessarily mean that a subsequent call to NdisIMQueueMiniportCallback will fail.

Comments

An NDIS intermediate driver must be executing as if it were a NIC miniport when it indicates up to bound protocols.

For example, packet arrays indicated up to an NDIS intermediate driver’s ProtocolReceivePackets function cannot be forwarded directly to higher-level bound protocols with a call to NdisMIndicateReceivePacket.

When an intermediate driver’s call to NdisIMSwitchToMiniport returns FALSE, the driver calls NdisIMQueueMiniportCallback.

First, such a driver’s ProtocolXxx function should call NdisIMSwitchToMiniport. If this call succeeds, it is safe for the ProtocolXxx function to call miniport-only NdisMXxx functions and to call the reciprocal NdisIMRevertBack as soon as ProtocolXxx no longer has any more miniport-only processing to be done. If its call to NdisIMSwitchToMiniport returns FALSE, ProtocolXxx must call NdisIMQueueMiniportCallback with a driver function that essentially does exactly what ProtocolXxx would have done if its call to NdisIMSwitchToMiniport succeeded. However, the supplied MiniportCallback function also might return status to the caller in the CallbackContext or MiniportAdapterContext area.

If NdisIMQueueMiniportCallback returns NDIS_STATUS_SUCCESS, the ProtocolXxx function resumes execution with all necessary miniport-only work already done by the supplied function at CallbackRoutine.

The MiniportCallback function passed to NdisIMQueueMiniportCallback runs, by default, at IRQL DISPATCH_LEVEL.

Callers of NdisIMQueueMiniportCallback run at IRQL DISPATCH_LEVEL.