W_SET_INFORMATION_HANDLER callback function

Article
06/19/2017

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 MiniportSetInformation function is a required function that allows bound protocol drivers (or NDIS) to request changes in the state information that the miniport driver maintains for particular OIDs, such as changes in multicast addresses.

Syntax

W_SET_INFORMATION_HANDLER MiniportSetInformation;

NDIS_STATUS MiniportSetInformation(
  _In_  NDIS_HANDLE MiniportAdapterContext,
  _In_  NDIS_OID    Oid,
  _In_  PVOID       InformationBuffer,
  _In_  ULONG       InformationBufferLength,
  _Out_ PULONG      BytesRead,
  _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 set operation the driver should carry out.
InformationBuffer [in]
Pointer to a buffer containing the OID-specific data used by MiniportSetInformation for the set.
InformationBufferLength [in]
Specifies the number of bytes at InformationBuffer.
BytesRead [out]
Pointer to a variable that MiniportSetInformation sets to the number of bytes it read from the buffer at InformationBuffer.
BytesNeeded [out]
Pointer to a variable that MiniportSetInformation sets to the total number of bytes it needs to satisfy the request if InformationBufferLength is less than Oid requires.

Return value

MiniportSetInformation can return one of the following:

Return code	Description
NDIS_STATUS_SUCCESS	MiniportSetInformation used the data at InformationBuffer to set itself or its NIC to the state required by the given Oid, and it set the variable at BytesRead to the amount of supplied data it used.
NDIS_STATUS_PENDING	The driver will complete the request asynchronously with a call to NdisMSetInformationComplete when it has set itself or its NIC to the state requested.
NDIS_STATUS_INVALID_OID	MiniportSetInformation did not recognize the Oid.
NDIS_STATUS_INVALID_LENGTH	The InformationBufferLength does not match the length required by the given Oid. MiniportSetInformation returned how many bytes the buffer should be at BytesNeeded.
NDIS_STATUS_INVALID_DATA	The data supplied at InformationBuffer was invalid for the given Oid.
NDIS_STATUS_NOT_ACCEPTED	MiniportSetInformation attempted the requested set operation on the NIC but was unsuccessful.
NDIS_STATUS_NOT_SUPPORTED	MiniportSetInformation does not support the Oid, which is optional.
NDIS_STATUS_RESOURCES	MiniportSetInformation could not carry out the requested operation due to resource constraints. 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 MiniportSetInformation either on its own behalf, such as to manage bindings to the miniport driver, or when a bound protocol driver calls NdisRequest.

If MiniportSetInformation returns NDIS_STATUS_PENDING, the driver must complete the request later by calling NdisMSetInformationComplete. Until it completes any request, the miniport driver can safely access the memory at InformationBuffer, BytesRead, and BytesNeeded. After the miniport driver completes any set request, ownership of these variables and the buffer reverts to NDIS or the caller of NdisRequest, whichever allocated the memory.

After a call to MiniportSetInformation, NDIS submits no other requests to the driver until it has completed the operation, either synchronously or asynchronously. Instead, NDIS holds requests queued until the current set operation is completed.

Note that NDIS does not validate the OID-specific contents at InformationBuffer. The driver itself must therefore validate these contents. If the driver determines that the value to be set is out of bounds, it should fail the request and return NDIS_STATUS_INVALID_DATA.

For more information about the system-defined OIDs, see NDIS Object Identifiers.

MiniportSetInformation 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