Expand Minimize

NdisOpenAdapter 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.

NdisOpenAdapter sets up a binding between the calling protocol and a particular underlying NIC driver or NDIS intermediate driver.

Syntax


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_opt_  PSTRING AddressingInformation
);

Parameters

Status [out]

Pointer 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 [out]

Pointer 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 [out]

Pointer 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 [out]

Pointer 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 [in]

Pointer 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

Specifies an ATM network. Connection-oriented client protocols can bind themselves to an underlying miniport driver that returns this value. Otherwise, legacy protocols bind themselves to the system-supplied LanE intermediate driver, which reports its medium type as either of NdisMedium802_3 or NdisMedium802_5, depending on how the LanE driver is configured by the network administrator.

NdisMediumWirelessWan

Specifies a wireless network. NDIS 5.X miniport drivers that support wireless LAN (WLAN) or wireless WAN (WWAN) packets declare their medium as NdisMedium802_3 and emulate Ethernet to higher-level NDIS drivers.

Note   This media type is not available for use beginning with Windows Vista.

NdisMediumIrda

Specifies an infrared (IrDA) network.

NdisMediumCoWan

Specifies a wide area network in a connection-oriented environment.

NdisMedium1394

Specifies an IEEE 1394 (fire wire) network.

MediumArraySize [in]

Specifies the number of elements at MediumArray.

NdisProtocolHandle [in]

Specifies the handle returned by NdisRegisterProtocol.

ProtocolBindingContext [in]

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 [in]

Pointer to an NDIS_STRING type containing a counted string, specified in the system-default character set, naming the NIC or the virtual adapter of an underlying NDIS driver. This driver exports a set of upper-edge ( MiniportXxx) functions. For Windows 2000 and later drivers, this counted string contains Unicode characters. That is, for Windows 2000 and later, NDIS defines the NDIS_STRING type as a UNICODE_STRING type.

OpenOptions [in]

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 [in, optional]

Pointer 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.

Return value

None

Remarks

A protocol driver calls NdisOpenAdapter from its ProtocolBindAdapter function. NDIS no longer supports calling NdisOpenAdapter from the DriverEntry function, which was an option available to legacy (V3.0) protocols. NDIS no longer supports V3.0 protocols. NDIS fails any attempt to call NdisOpenAdapter outside the context of ProtocolBindAdapter.

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, so protocols usually pass an NdisProtocolHandle pointer to a variable somewhere in the caller-allocated context area in their calls to NdisOpenAdapter.

The caller uses the value returned at SelectedMediumIndex in subsequent calls to NdisRequest and/or NdisCoRequest. The OIDs it sets in the request packet depend on the returned NdisMediumXxx. For example, if NdisMediumAtm is returned at SelectedMediumIndex, the protocol driver calls NdisCoRequest when specifying OID_ATM_ XXX or OID_CO_XXX codes, and NdisRequest when specifying OID_GEN_XXX codes.

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.

For more information about the general and medium-specific OIDs that protocol drivers use to negotiate with a just-bound NDIS driver, see NDIS Object Identifiers.

Requirements

Version

Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisOpenAdapterExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

See also

ANSI_STRING
DriverEntry of NDIS Protocol Drivers
MiniportInitialize
MiniportQueryInformation
MiniportSendPackets
MiniportSetInformation
NdisCloseAdapter
NdisClOpenAddressFamily
NdisCoRequest
NdisCmRegisterAddressFamily
NdisIMInitializeDeviceInstance
NdisIMRegisterLayeredMiniport
NdisMIndicateReceivePacket
NDIS_PACKET_OOB_DATA
NdisRegisterProtocol
NdisRequest
NdisSendPackets
ProtocolBindAdapter
ProtocolOpenAdapterComplete
ProtocolReceivePacket
UNICODE_STRING

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft