W_QUERY_INFORMATION_HANDLER callback function
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
The MiniportQueryInformation function is a required function that returns information about the capabilities and status of the driver and/or its NIC.
Syntax
W_QUERY_INFORMATION_HANDLER MiniportQueryInformation;
NDIS_STATUS MiniportQueryInformation(
_In_ NDIS_HANDLE MiniportAdapterContext,
_In_ NDIS_OID Oid,
_In_ PVOID InformationBuffer,
_In_ ULONG InformationBufferLength,
_Out_ PULONG BytesWritten,
_Out_ PULONG BytesNeeded
)
{ ... }
Parameters
MiniportAdapterContext [in]
Specifies the handle to a miniport driver-allocated context area in which the driver maintains per-NIC state, set up by MiniportInitialize.Oid [in]
Specifies the system-defined OID_XXX code designating the global query operation the driver should carry out.InformationBuffer [in]
Pointer to a buffer in which MiniportQueryInformation should return the OID-specific information.InformationBufferLength [in]
Specifies the number of bytes at InformationBuffer.BytesWritten [out]
Pointer to a variable that MiniportQueryInformation sets to the number of bytes it is returning at InformationBuffer.BytesNeeded [out]
Pointer to a variable that MiniportQueryInformation sets to the total number of bytes it needs to satisfy the request if InformationBufferLength is less than Oid requires.
Return value
MiniportQueryInformation can return one of the following:
| Return code | Description |
|---|---|
| NDIS_STATUS_SUCCESS | MiniportQueryInformation returned the requested information at InformationBuffer and set the variable at BytesWritten to the amount of information it returned. |
| NDIS_STATUS_PENDING | The driver will complete the request asynchronously with a call to NdisMQueryInformationComplete when it has gathered the requested information. |
| NDIS_STATUS_INVALID_OID | MiniportQueryInformation does not recognize the Oid. |
| NDIS_STATUS_INVALID_LENGTH | The InformationBufferLength does not match the length required by the given Oid. MiniportQueryInformation returned how many bytes the buffer should be at BytesNeeded. |
| NDIS_STATUS_NOT_ACCEPTED | MiniportQueryInformation attempted to gather the requested information from the NIC but was unsuccessful. |
| NDIS_STATUS_NOT_SUPPORTED | MiniportQueryInformation does not support the Oid, which is optional. |
| NDIS_STATUS_RESOURCES | MiniportQueryInformation could not allocate sufficient resources to return the requested information. This return value does not necessarily mean that the same request, submitted at a later time, will be failed for the same reason. |
Remarks
NDIS calls the MiniportQueryInformation function either on its own behalf, such as to determine which options the driver supports or to manage binding-specific information for the miniport driver, or when a bound protocol driver calls NdisRequest.
NDIS makes one or more calls to MiniportQueryInformation just after a driver's MiniportInitialize function returns NDIS_STATUS_SUCCESS. NDIS supplies the following OIDs in its initialization-time calls to the driver's MiniportQueryInformation function:
OID_GEN_MAXIMUM_LOOKAHEAD
MiniportQueryInformation must return how many bytes of lookahead data the NIC can provide, that is, the initial transfer capacity of the NIC.Even if a driver supports multipacket receives and, therefore, will indicate an array of pointers to fully set up packets, MiniportQueryInformation must supply this information. Such a driver should return the maximum packet size it can indicate.
OID_GEN_MAC_OPTIONS
MiniportQueryInformation must return a bitmask set with the appropriate NDIS_MAC_OPTION_XXX flags indicating which options it (or its NIC) supports, or it can return zero at InformationBuffer if the driver supports none of the options designated by these flags.
For example, a NIC driver always sets the NDIS_MAC_OPTION_NO_LOOPBACK flag if its NIC has no internal hardware support for loopback. This tells NDIS to manage loopback for the driver, which cannot provide software loopback code as efficient as the NDIS library's because NDIS manages all binding-specific information for miniports. Any miniport driver that tries to provide software loopback must check the destination address of every send packet against the currently set filter addresses to determine whether to loop back each packet. WAN NIC drivers must set this flag.
If the NIC driver sets the NDIS_MAC_OPTION_FULL_DUPLEX flag, the NDIS library serializes calls to the MiniportSendPackets, MiniportSend, or MiniportWanSend function separately from its serialized calls to other MiniportXxx functions in SMP machines. However, NDIS returns incoming send packets to protocols while such a driver's MiniportReset function is executing: that is, NDIS never calls a full-duplex miniport driver to transmit a packet until its reset operation is completed. The designer of any full-duplex driver can expect that driver to achieve significantly higher performance in SMP machines, but the driver must synchronize its accesses to shared resources carefully to prevent race conditions or deadlocks from occurring. NDIS assumes that all intermediate drivers are full-duplex drivers.
Note The NDIS_MAC_OPTION_FULL_DUPLEX flag has been deprecated for use by NDIS 5.0 and later miniport drivers. NDIS 5.0 and later ignores this flag.
Depending on the NdisMediumXxx that MiniportInitialize selected, NDIS submits additional initialization-time requests to MiniportQueryInformation, such as the following:
OID_XXX_CURRENT_ADDRESS
If the driver's MiniportInitialize function selected an NdisMediumXxx for which the system supplies a filter, NDIS calls MiniportQueryInformation to return the NIC's current address in medium-specific format. For FDDI drivers, NDIS requests both long and short current addresses.OID_802_3_MAXIMUM_LIST_SIZE
For Ethernet drivers, NDIS requests the multicast list size.OID_FDDI_LONG/SHORT_MAX_LIST_SIZE
For FDDI drivers, NDIS requests the multicast list sizes.
If possible, MiniportQueryInformation should not return NDIS_STATUS_PENDING for initialization-time requests. Until NDIS has sufficient information to set up bindings to the miniport driver, such requests should be handled synchronously.
Subsequently, the NDIS library intercepts all protocol-initiated queries on certain OIDs, such as the following:
For more information about the system-defined OIDs, see NDIS Object Identifiers.
If MiniportQueryInformation does not complete a request synchronously and returns NDIS_STATUS_PENDING, the driver must complete the request later with a call to NdisMQueryInformationComplete. Until it completes any such request, the miniport driver can safely access the memory at InformationBuffer, BytesWritten, and BytesNeeded. After the miniport driver completes any query, ownership of these variables and the buffer reverts to NDIS or the caller of NdisRequest, whichever allocated the memory.
After a call to MiniportQueryInformation, NDIS submits no other requests to the driver until it has completed the current request, either synchronously or asynchronously. Instead, NDIS holds requests queued until the current query is completed.
MiniportQueryInformation can be preempted by an interrupt.
Requirements
Target platform |
Desktop |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use MiniportOidRequest instead. Supported for NDIS 5.1 drivers in Windows Vista and Microsoft Windows XP. |
Header |
Ndis.h (include Ndis.h) |
IRQL |
<= DISPATCH_LEVEL |
See also