Share via

NdisIfRegisterInterface (Compact 2013)

  • Article

3/26/2014

This function registers an NDIS network interface.

Syntax

NDIS_STATUS
  NdisIfRegisterInterface(
    IN NDIS_HANDLE  NdisProviderHandle,
    IN NET_LUID  NetLuid,
    IN NDIS_HANDLE  ProviderIfContext,
    IN PNET_IF_INFORMATION  pIfInfo,
    OUT PNET_IFINDEX  pIfIndex
    );

Parameters

  • NdisProviderHandle
    A handle that identifies the network interface provider that is registering the interface. The caller obtained this handle from a previous call to the NdisIfRegisterProvider function.
  • NetLuid
    The caller-supplied NET_LUID value that is associated with the interface. The interface provider used the NDIS_MAKE_NET_LUID macro to create this NET_LUID value. The interface provider should recover the NET_LUID value from persistent storage after the device restarts and provide the same NET_LUID value every time that it registers a particular interface.
  • ProviderIfContext
    A handle to a caller-allocated context area that is associated with the interface. NDIS passes this handle to the callback functions that the caller registered with NdisIfRegisterProvider.
  • pIfInfo
    A pointer to a caller-allocated NET_IF_INFORMATION structure that provides information about the interface. This structure contains information that remains constant while the interface exists.
  • pIfIndex
    A pointer to a caller-supplied interface index variable. If NDIS successfully registers an interface, NDIS allocates an interface index for that interface and sets the value at pIfIndex. The interface index is a 24-bit value that is unique on the local device. NDIS might not return the same interface index every time that a provider registers an interface with the same NET_LUID value . The interface index value zero is reserved, and NDIS does not assign it to any interface. Do not confuse the interface index with a NET_LUID index.

Return Value

NdisIfRegisterInterface returns one of the following status values:

Value

Description

NDIS_STATUS_SUCCESS

The operation completed successfully.

NDIS_STATUS_RESOURCES

The operation failed because of insufficient resources.

NDIS_STATUS_INVALID_PARAMETER

NdisIfRegisterInterface failed because some input parameters are invalid.

NDIS_STATUS_DUPLICATE_OBJECTID

NdisIfRegisterInterface failed because there is already an interface registered with the same NET_LUID value that the NetLuid parameter specified.

Remarks

NDIS interface providers call the NdisIfRegisterInterface function to register a network interface. A call to this function does not imply that the interface is active.

Whenever a device restarts, NDIS starts with an empty list of registered network interfaces. An interface provider calls the NdisIfRegisterInterface function whenever an interface is started (or detected) and the interface's NET_LUID is known.

The method for detecting or starting an interface is application dependent. For example, if an LBFO MUX intermediate driver is an interface provider, that driver might register an internal interface when NDIS calls the driver's ProtocolBindAdapterEx function for the first underlying miniport adapter.

An interface provider can put information about an interface in persistent storage and restore the interface as required for the particular application. For example, the provider can store additional information about the interface with the NET_LUID and it can reregister the interface after the device restarts.

If NdisIfRegisterInterface is successful, NDIS adds the interface to the list of known interfaces and allocates a new interface index for this interface. Interface providers should register both enabled and disabled interfaces, wherever possible. All enabled interfaces must be registered.

NDIS might not return the same interface index every time that a provider registers an interface with the same NET_LUID value. For example, NDIS does not necessarily assign the same interface index when an interface is reregistered after a device restarts or when the interface is deregistered and reregistered. The interface index value zero is reserved, and NDIS does not assign it to any interface.

To indicate that an interface should be removed from the list of known interfaces on the device, an interface provider calls the NdisIfDeregisterInterface function, for example, because the interface has been uninstalled.

Requirements

Header

ndis.h

See Also

Reference

NDIS Network Interface Functions
NDIS_MAKE_NET_LUID
NdisIfDeregisterInterface
NdisIfRegisterProvider
NET_IF_INFORMATION
ProtocolBindAdapterEx

Other Resources

NET_LUID