Share via

NdisOpenAdapter (Windows Embedded CE 6.0)

  • Article

1/6/2010

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

Syntax

            VOID
            NdisOpenAdapter(
            PNDIS_STATUS
            Status
            ,
            PNDIS_STATUS
            OpenErrorStatus
            ,
            PNDIS_HANDLE
            NdisBindingHandle
            ,
            PUINT
            SelectedMediumIndex
            ,
            PNDIS_MEDIUM
            MediumArray
            ,
            UINT
            MediumArraySize
            ,
            NDIS_HANDLE
            NdisProtocolHandle
            ,
            NDIS_HANDLE
            ProtocolBindingContext
            ,
            PNDIS_STRING
            AdapterName
            ,
            UINT
            OpenOptions
            ,
            PSTRING
            AddressingInformation
            );

Parameters

  • Status
    [out] Pointer to a caller-supplied variable that indicates status.
  • OpenErrorStatus
    [out] Pointer to a caller-supplied variable that can contain an NDIS_STATUS_XXX error 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
    [out] 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
    [in] 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
    [in] 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.

    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.

    NdisMediumDix

    Specifies an Ethernet network for which the drivers use the DIX Ethernet header format.

    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
    [in] Specifies the number of elements at MediumArray.
  • ProtocolBindingContext
    [in] Handle to a caller-supplied resident context area in which the protocol maintains state information about this binding after it has been established.
  • AdapterName
    [in] 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 (MiniportXXX) functions.
  • OpenOptions
    [in] Specifies a bitmask containing flags that the caller passes to the next-lower driver, assumed to be a NIC driver. Currently, this parameter is reserved for system use.
  • AddressingInformation
    Unused. Set to NULL.

Return Value

The following table shows return values for this function.

Value Description

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 the NdisXXX functions.

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 the state that 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.

Remarks

Protocol drivers call this function from either Initialization of NDIS Protocol Drivers functions or from a ProtocolBindAdapter function. NDIS intermediate drivers usually make this call from a ProtocolBindAdapter function.

The string at AdapterName remains valid only until this function 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 this function 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 because this handle is an input parameter to ProtocolOpenAdapterComplete.

A protocol driver should keep the handle returned at NdisProtocolHandle. Other NDIS functions that the driver calls later may require this parameter. The supplied ProtocolBindingContext is an input parameter to the caller's protocol functions.

The caller uses the value returned at SelectedMediumIndex in subsequent calls to the NdisRequest function. The object identifiers that it sets in the request packet depend on the returned NdisMediumXXX function. 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 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 NdisSendPackets function. The protocol driver can expect its ProtocolReceivePacket function to get indications of prioritized packets if the underlying driver also supports multipacket receive indications.

Requirements

Header ndis.h
Windows Embedded CE Windows CE .NET 4.0 and later

See Also

Reference

NDIS Library Functions
NdisCloseAdapter
NdisMIndicateReceivePacket
NdisRegisterProtocol
NdisRequest
NdisSendPackets
OID_802_3_MAC_OPTIONS
OID_WAN_MEDIUM_SUBTYPE
ProtocolOpenAdapterComplete
ProtocolBindAdapter
ProtocolReceivePacket

Concepts

Initialization of NDIS Protocol Drivers
Initialization of NDIS Protocol Drivers