MacOpenAdapter

MacOpenAdapter

NDIS_STATUS
   MacOpenAdapter(
       OUT PNDIS_STATUS OpenErrorStatus,
       OUT NDIS_HANDLE *MacBindingHandle,
       OUT PUINT SelectedMediumIndex,
       IN PNDIS_MEDIUM MediumArray,
       IN UINT MediumArraySize,
       IN NDIS_HANDLE NdisBindingContext,
       IN NDIS_HANDLE MacAdapterContext,
       IN UINT OpenOptions,
       IN PSTRING AddressingInformation OPTIONAL
       );

MacOpenAdapter is called when a protocol driver requests a binding to the NIC with NdisOpenAdapter.

Parameters

OpenErrorStatus

Points to the caller-supplied variable in which MacOpenAdapter returns an NDIS_STATUS_XXX indicating the reason for a failure to open the NIC if the open fails.

MacBindingHandle

Points to the caller-supplied variable in which MacOpenAdapter returns a handle that the NIC driver associates with the binding. This value is typically a pointer to a driver-defined structure in resident memory containing binding-specific information. All future requests that NDIS forwards from the protocol driver to the NIC driver specify this value if the request concerns this binding.

SelectedMediumIndex

Points to the caller-supplied variable in which this function returns the index of the NIC driver’s medium type, selected from the supplied values at MediumArray.

MediumArray

Points to an array of media types the protocol driver supports.

MediumArraySize

Specifies the number of elements in MediumArray.

NdisBindingContext

Specifies the context that NDIS associates with the binding. The NIC driver uses this handle when it sends an indication to the protocol driver.

MacAdapterContext

Specifies the context that the NIC driver associates with the NIC.

OpenOptions

Specifies a bitmask containing flags the protocol driver passes to the NIC driver. Currently, the bitmask is undefined.

AddressingInformation

Points to an optional variable-length string containing specific information the NIC driver can use to program the network interface card. A NIC driver supporting an asynchronous modem can use this information for dialing. The addressing information, if specified, remains valid until this function completes. This parameter can be NULL.

Return Value

MacOpenAdapter can return the following status codes:

NDIS_STATUS_ADAPTER_NOT_FOUND
NDIS_STATUS_FAILURE
NDIS_STATUS_NOT_ACCEPTED
NDIS_STATUS_OPEN_FAILED
NDIS_STATUS_OPEN_LIST_FULL
NDIS_STATUS_PENDING
NDIS_STATUS_RESOURCES
NDIS_STATUS_SUCCESS
NDIS_STATUS_UNSUPPORTED_MEDIA

Comments

In its call to NdisOpenAdapter, the protocol driver specifies an array containing the media types that it supports. The NIC driver reads this array and writes the index of its own media type in SelectedMediumIndex.

A NIC driver can imitate a medium type other than the true underlying type of its NIC, and this imitation is transparent to the protocol driver. If the NIC driver cannot find a medium type that it and the protocol driver both support, MacOpenAdapter returns NDIS_STATUS_UNSUPPORTED_MEDIA.

When the protocol driver calls NdisOpenAdapter, MacOpenAdapter activates the NIC if it is not already physically enabled. Subsequently, the NIC driver does not disable the network interface card until its reference count for open bindings returns to zero. The maximum number of simultaneous opens the NIC driver supports can be configured.

Before MacOpenAdapter completes the open request, the filter library causes the NIC driver to reset all multicast and functional addresses for the newly bound protocol driver. The reset of filter database information has no effect on other protocol drivers that are also bound to the NIC.

MacOpenAdapter completes synchronously if it finishes the open operation before it returns control with a status code other than NDIS_STATUS_PENDING.

If MacOpenAdapter cannot complete the open operation before it returns control, it returns NDIS_STATUS_PENDING. For example, MacOpenAdapter usually returns NDIS_STATUS_PENDING at the initial open for its NIC. Then, the NIC driver eventually calls NdisCompleteOpenAdapter, which, in turn, calls the ProtocolOpenAdapterComplete function of the driver that initiated the open. This asynchronous completion allows protocol driver postprocessing of the NIC open request.

Whether MacOpenAdapter completes an open synchronously or asynchronously, it must set values for MacBindingHandle and SelectedMediumIndex before it returns control.

MacOpenAdapter runs at IRQL DISPATCH_LEVEL.