NdisOpenAdapter
VOID
NdisOpenAdapter(
OUT PNDIS_STATUS Status,
OUT PNDIS_STATUS OpenErrorStatus,
OUT PNDIS_HANDLE NdisBindingHandle,
OUT PUINT SelectedMediumIndex,
IN PNDIS_MEDIUM MediumArray,
IN UINT MediumArraySize,
IN NDIS_HANDLE NdisProtocolHandle,
IN NDIS_HANDLE ProtocolBindingContext,
IN PNDIS_STRING AdapterName,
IN UINT OpenOptions,
IN PSTRING AddressingInformation
);
NdisOpenAdapter sets up a binding between the calling protocol and a
particular underlying NIC driver or NDIS intermediate driver.
Parameters
-
Status
-
Points to a caller-supplied variable that can be one of the following values
on return from this function:
-
STATUS_SUCCESS
-
The requested binding is now set up so the caller can use the values returned
at NdisBindingHandle and SelectedMediumIndex in subsequent calls
to NdisXxx.
-
NDIS_STATUS_PENDING
-
The requested operation is being handled asynchronously, and the caller’s
ProtocolOpenAdapterComplete function will be called when the open is
completed.
-
NDIS_STATUS_RESOURCES
-
The requested operation failed because NDIS could not allocate sufficient
memory or initialize state it uses to track an open binding.
-
NDIS_STATUS_ADAPTER_NOT_FOUND
-
The requested operation failed because the name at AdapterName could
not be found in the system object namespace.
-
NDIS_STATUS_UNSUPPORTED_MEDIA
-
The array at MediumArray did not specify any medium that is supported
by NDIS or by the underlying driver.
-
NDIS_STATUS_CLOSING
-
Either the caller or the physical or virtual device designated at AdapterName
is being closed.
-
NDIS_STATUS_OPEN_FAILED
-
The open attempt failed for none of the preceding specific reasons. For
example, possibly NDIS could not initialize the filter package for the
selected medium.
-
OpenErrorStatus
-
Points to a caller-supplied variable that can contain an NDIS_STATUS_XXX
error supplying more information if NdisOpenAdapter returns an error at
Status. For example, the driver of a Token Ring NIC might return a ring
error in this variable.
-
NdisBindingHandle
-
Points to a caller-supplied variable in which NDIS returns a handle
representing a successful binding between the caller and the given physical or
virtual NIC specified at AdapterName.
-
SelectedMediumIndex
-
Points to a caller-supplied variable in which NDIS returns the index of the
array element that specifies the type of media the underlying NDIS driver
uses.
-
MediumArray
-
Points to an array of NDIS_MEDIUM-type values specifying the types of media
the caller can support. Possible elements include any proper subset of the
following:
-
NdisMedium802_3
-
Specifies an Ethernet (802.3) network.
-
NdisMedium802_5
-
Specifies a Token Ring (802.5) network.
-
NdisMediumFddi
-
Specifies a Fiber Distributed Data Interface (FDDI) network.
-
NdisMediumWan
-
Specifies a wide area network. This type covers various forms of
point-to-point and WAN NICs, as well as variant address/header formats that
must be negotiated between the protocol driver and the underlying driver after
the binding is established.
-
NdisMediumLocalTalk
-
Specifies a LocalTalk network.
-
NdisMediumDix
-
Specifies an Ethernet network for which the drivers use the DIX Ethernet
header format.
-
NdisMediumArcnetRaw
-
Specifies an ARCNET network.
-
NdisMediumArcnet878_2
-
Specifies an ARCNET (878.2) network.
-
NdisMediumAtm
-
This value is reserved for future use. Currently, NIC drivers support ATM
through LAN emulation (LanE 1.0 as defined in the ATM Forum’s 1.0
specification and UNI 3.1 signaling). Such a driver should report its medium
type as either of NdisMedium802_3 or NdisMedium802_5.
-
NdisMediumWirelessWan
-
Specifies a wireless network. This type covers various wireless media that do
not include the infrared wireless types designated by NdisMediumIrda.
-
NdisMediumIrda
-
This value is reserved for future use in Windows NT drivers.
-
MediumArraySize
-
Specifies the number of elements at MediumArray.
-
NdisProtocolHandle
-
Specifies the handle returned by NdisRegisterProtocol.
-
ProtocolBindingContext
-
Specifies the handle for a caller-supplied resident context area in which the
protocol maintains state about this binding after it has been established.
-
AdapterName
-
Points to a counted string, specified in the system-default character set,
naming the NIC or the virtual adapter of an underlying NDIS driver that
exports a set of upper-edge (MiniportXxx) functions. For Windows NT
drivers, this counted string contains Unicode characters.
-
OpenOptions
-
Specifies a bitmask containing flags the caller passes to the next-lower
driver, assumed to be a NIC driver. Currently, this parameter is reserved for
system use.
-
AddressingInformation
-
Points to an optional variable-length counted string containing information
specific to the underlying NIC that the NIC driver can use to program the
netcard. This pointer can be NULL.
If it is supplied, the addressing information must remain valid until the open
operation completes. An underlying NIC driver that supports an asynchronous
modem can use this information for dialing.
Comments
Protocol drivers call NdisOpenAdapter either from their DriverEntry
or ProtocolBindAdapter functions. NDIS intermediate drivers usually make this
call from their ProtocolBindAdapter functions.
The string at AdapterName remains valid only until NdisOpenAdapter
returns control, even if it returns NDIS_STATUS_PENDING at Status.
The variables at NdisBindingHandle and SelectedMediumIndex
should be ignored until the ProtocolOpenAdapterComplete function is called if NdisOpenAdapter
returns NDIS_STATUS_PENDING. Because these variables can remain invalid until
ProtocolOpenAdapterComplete is called, they cannot be on the stack. Usually,
these variables reside in the ProtocolBindingContext area since this
handle is an input parameter to ProtocolOpenAdapterComplete.
A protocol driver should keep the handle returned at NdisProtocolHandle.
It is a required parameter to other NdisXxx functions that the
driver calls subsequently. The supplied ProtocolBindingContext is an
input parameter to the caller’s ProtocolXxx functions.
The caller uses the value returned at SelectedMediumIndex in subsequent
calls to NdisRequest. The OIDs it sets in the request packet depend on
the returned NdisMediumXxx. For example, if NdisMediumWan
is returned at SelectedMediumIndex, the protocol driver calls NdisRequest
specifying OID_WAN_MEDIUM_SUBTYPE in a query to determine which of the WAN
media types the underlying driver uses.
If a previously issued global query of OID_NETWORK_TYPE for wireless media
indicates that the driver and underlying NIC support more than one NdisMediumWirelessWan-type
medium, the protocol must select one of the supported media as soon as NDIS
has set up the binding and before the protocol selects the header format.
As another example, if NdisMedium802_3 is returned, a protocol driver
can determine whether the underlying driver supports packet priority by
calling NdisRequest specifying OID_802_3_MAC_OPTIONS as a query to
check whether the underlying driver sets the flags with
NDIS_802_3_MAC_OPTION_PRIORITY. If this flag is set when the query is
complete, the protocol driver can pass down prioritized packets to the
underlying NIC driver with NdisSendPackets. The protocol driver can
expect its ProtocolReceivePacket function to get indications of prioritized
packets if the underlying driver also supports multipacket receive
indications.
For more information about the general and medium-specific OIDs that protocol
drivers use to negotiate with a just-bound NDIS driver, see Chapter
5.
Callers of NdisOpenAdapter run at IRQL PASSIVE_LEVEL.
See Also
DriverEntry of NDIS
Protocol Drivers, MiniportInitialize,
MiniportQueryInformation, MiniportSendPackets,
MiniportSetInformation, NdisCloseAdapter,
NdisIMInitializeDeviceInstance,
NdisIMRegisterLayeredMiniport,
NdisMIndicateReceivePacket,
NDIS_PACKET_OOB_DATA, NdisRegisterProtocol,
NdisRequest, NdisSendPackets,
ProtocolBindAdapter, ProtocolOpenAdapterComplete,
ProtocolReceivePacket