NdisOpenAdapter (Windows CE 3.0 Device Driver Developement)

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

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

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
);

Parameters

Status

Pointer to a caller-supplied variable that can be one of the following values on return from this function:

Value	Description
STATUS_SUCCESS	The requested binding is now set up, so the caller can use the values returned at NdisBindingHandleand SelectedMediumIndexin subsequent calls to the Ndis XXXfunctions.
NDIS_STATUS_PENDING	The requested operation is being handled asynchronously, and the caller's ProtocolOpenAdapterCompletefunction will be called when the open is completed.
NDIS_STATUS_RESOURCES	The requested operation failed because NDIS could not allocate sufficient memory or initialize the state that it uses to track an open binding.
NDIS_STATUS_ADAPTER_NOT_FOUND	The requested operation failed because the name at AdapterNamecould not be found in the system object namespace.
NDIS_STATUS_UNSUPPORTED_MEDIA	The array at MediumArraydid 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 AdapterNameis 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

Pointer to a caller-supplied variable that can contain an NDIS_STATUS_ XXXerror supplying more information if this function returns an error at Status. For example, the driver of a token ring NIC might return a ring error in this variable.

NdisBindingHandle

Pointer to a caller-supplied variable in which NDIS returns a handle representing a successful binding between the caller and the specified physical or virtual NIC specified at AdapterName.

SelectedMediumIndex

Pointer to a caller-supplied variable in which NDIS returns the index of the array element that specifies the type of media that the underlying NDIS driver uses.

MediumArray

Pointer to an array of NDIS_MEDIUM-type values specifying the types of media that the caller supports. Possible elements include any proper subset of the following:

Value	Description
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 and 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.

MediumArraySize

Specifies the number of elements at MediumArray.

NdisProtocolHandle

Handle returned by NdisRegisterProtocol.

ProtocolBindingContext

Handle to a caller-supplied resident context area in which the protocol maintains state information about this binding after it has been established.

AdapterName

Pointer 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 ( Miniport XXX) functions.

OpenOptions

Specifies a bitmask containing flags that the caller passes to the next-lower driver, assumed to be an NIC driver. Currently, this parameter is reserved for system use.

AddressingInformation

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.

Remarks

Protocol drivers call this function from either their DriverEntryor their ProtocolBindAdapterfunctions. NDIS intermediate drivers usually make this call from their ProtocolBindAdapterfunctions.

The string at AdapterNameremains valid only until this function returns control, even if it returns NDIS_STATUS_PENDING at Status.

The variables at NdisBindingHandleand SelectedMediumIndexshould be ignored until the ProtocolOpenAdapterCompletefunction is called if this function returns NDIS_STATUS_PENDING. Because these variables can remain invalid until ProtocolOpenAdapterCompleteis called, they cannot be on the stack. Usually, these variables reside in the ProtocolBindingContextarea 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 NDIS functions that the driver calls subsequently. The supplied ProtocolBindingContextis an input parameter to the caller's protocol functions.

The caller uses the value returned at SelectedMediumIndexin subsequent calls to the NdisRequestfunction. The OIDs that it sets in the request packet depend on the returned NdisMedium XXXfunction. For example, if NdisMediumWan is returned at SelectedMediumIndex, the protocol driver calls NdisRequestspecifying OID_WAN_MEDIUM_SUBTYPE in a query to determine which of the WAN media types that 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 the NdisSendPacketsfunction. The protocol driver can expect its ProtocolReceivePacketfunction to get indications of prioritized packets if the underlying driver also supports multipacket receive indications.

A driver that calls this function runs at IRQL PASSIVE_LEVEL.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	2.0 and later	Ndis.h

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

Last updated on Tuesday, July 13, 2004