MiniportQueryInformation (Windows Embedded CE 6.0)

1/6/2010

This function is a required function that returns information about the capabilities and status of the driver and/or its network adapter.

Syntax

NDIS_STATUS MiniportQueryInformation(
  NDIS_HANDLE MiniportAdapterContext,
  NDIS_OID Oid,
  PVOID InformationBuffer,
  ULONG InformationBufferLength,
  PULONG BytesWritten,
  PULONG BytesNeeded
)

Parameters

• MiniportAdapterContext
  [in] Specifies the handle to a miniport-allocated context area in which the driver maintains per-network adapter 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] Points to a buffer in which MiniportQueryInformation should return the OID-specific information.

• InformationBufferLength
  [in] Specifies the number of bytes at InformationBuffer.

• BytesWritten
  [out] Points to a variable that MiniportQueryInformation sets to the number of bytes it is returning at InformationBuffer.

• BytesNeeded
  [out] Points to a variable that MiniportQueryInformation sets to the number of additional bytes it needs to satisfy the request if InformationBufferLength is less than Oid requires.

Return Value

MiniportQueryInformation can return one of the following values.

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, 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 object identifiers in its initialization-time calls to the driver's MiniportQueryInformation function:

• OID_GEN_MAXIMUM_LOOKAHEAD
  MiniportQueryInformation must return how many bytes of look-ahead data the network adapter can provide, that is, the initial transfer capacity of the network adapter.
  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 network adapter) supports, or it can return zero at InformationBuffer if the driver supports none of the options designated by these flags.
  For example, a network adapter driver always sets the NDIS_MAC_OPTION_NO_LOOPBACK flag if its network adapter 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 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 network adapter drivers must set this flag.

Windows Embedded CE does not support full duplex. The following information is provided if driver portability is a concern.

Depending on the NdisMediumXXX that MiniportInitialize selected, NDIS submits additional initialization-time requests to MiniportQueryInformation, such as the following:

• OID_WAN_CURRENT_ADDRESS or OID_GEN_NETWORK_LAYER_ADDRESSES
  If the driver's MiniportInitialize function selected an NdisMediumXXX for which the system supplies a filter, NDIS calls MiniportQueryInformation to return the network adapter's current address in medium-specific format.
• OID_802_3_MAXIMUM_LIST_SIZE
  For Ethernet drivers, NDIS requests the multicast list size.

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, such requests should be handled synchronously.

Subsequently, the NDIS library intercepts all protocol-initiated queries on certain object identifiers, such as the following:

• OID_GEN_CURRENT_PACKET_FILTER
• OID_GEN_PROTOCOL_OPTIONS
• OID_802_5_CURRENT_FUNCTIONAL
• OID_802_3_MULTICAST_LIST

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 can safely access the memory at InformationBuffer, BytesWritten, and BytesNeeded. After the miniport completes any query, ownership of these variables and the buffer reverts to the driver that allocated the memory, NDIS or the caller of NdisRequest.

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 pre-empted by an interrupt.

Requirements

See Also

Reference

NDIS Upper-Edge Functions
MiniportInitialize
NdisMQueryInformationComplete
NdisRequest
OID_WAN_CURRENT_ADDRESS
OID_GEN_NETWORK_LAYER_ADDRESSES