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