NDIS_MAC_LINE_UP (Windows Embedded CE 6.0)

1/6/2010

This structure contains information associated with a line-up indication made by a wide area network (WAN) network interface card (NIC) miniport.

Syntax

typedef struct _NDIS_MAC_LINE_UP {
  ULONG LinkSpeed;
  NDIS_WAN_QUALITY Quality;
  USHORT SendWindow;
  NDIS_HANDLE ConnectionWrapperID;
  NDIS_HANDLE NdisLinkHandle;
  NDIS_HANDLE NdisLinkContext;
} NDIS_MAC_LINE_UP, *PNDIS_MAC_LINE_UP;

Members

• LinkSpeed
  Specifies the speed of the link, in units of 100 bits per second (BPS).

• Quality
  Reserved for future use.

• SendWindow
  Specifies the number of send packets the miniport, or its NIC, can accept at a time; effectively how many NDIS_WAN_PACKET-type send packets the WAN NIC driver queues internally. Zero indicates that the WAN protocol driver should use the value of the MaxTransmit member of the NDIS_WAN_INFO structure returned in response to the OID_WAN_GET_INFO query.

• ConnectionWrapperID
  Specifies the handle by which this link (or data channel on a link) will be known to TAPI clients. This handle must be unique, so the miniport uses the htCall handle supplied by NDISTAPI. Before the miniport makes the initial line-up indication that establishes such a link (or data channel), it already acquired the NDISTAPI-assigned htCall handle in one of the following ways:

  • For an outbound call, the driver's MiniportQueryInformation function saved the htCall member of the NDIS_TAPI_MAKE_CALL structure that NDISTAPI supplied in a preceding OID_TAPI_MAKE_CALL request.
  • For an incoming call, the miniport saved the htCall handle that NDISTAPI returned in the ulParam2 member of the NDIS_TAPI_EVENT structure that the miniport passed to NdisMIndicateStatus with ulMsg set to LINE_NEWCALL.

• NdisLinkHandle
  Specifies the handle, originally supplied by the NIC driver, drivers pass down in subsequent calls, such a call to MiniportWanSend to identify a particular link or to identify a particular channel on a link capable of handling more than one data stream.

• NdisLinkContext
  Specifies 0 when a WAN NIC driver calls NdisMIndicateStatus with this structure to establish a link. On return from NdisMIndicateStatus, this member contains a handle (supplied by the WAN protocol driver) useful for future calls. For example, such a call might indicate a receive for the established link.

Remarks

A WAN NIC driver calls NdisMIndicateStatus with this type of indication in any of the following conditions:

• When a link between a local node and a remote node in a WAN becomes active in the process of establishing the new link, the MiniportQueryInformation function makes this indication in the context of an OID_TAPI_GET_ID request for which ulSelect is set to LINECALLSELECT_CALL.
  When NdisMIndicateStatus returns, the miniport must save the NdisLinkContext handle, supplied by the WAN protocol driver, for subsequent calls to NdisMIndicateStatus and NdisWanXXX functions affecting the just established link.
  MiniportQueryInformation must also use the returned NdisLinkContext handle as the value returned to NDISTAPI in the DeviceID member of the NDIS_TAPI_GET_ID structure.
  If it can handle more than one data channel on a link, a WAN NIC driver's MiniportQueryInformation function is called once with OID_TAPI_GET_ID as each such channel on the link is opened. On such a link, NdisLinkContext handles are channel-specific rather than link-specific.
• After such a link is established, the NIC driver makes this indication with the given NdisLinkContext handle if line characteristics change. For example, a miniport can make a subsequent line-up indication if the originally specified quality of the line changes.
• After such a link is established, the NIC driver makes this indication to dynamically change the value of the SendWindowmember specifying the number of outstanding sends the NIC driver accepts for its internal queue.

Typically, a WAN NIC driver provides a pointer to a driver-allocated control block for each link as NdisLinkHandle. This handle is link-specific or, if the driver manages more than one data stream per link, data-channel-specific. In either case, a WAN NIC miniport must set up its NdisLinkHandle member at the first NDIS_MAC_LINE_UP indication that the miniport makes for each link or data channel.

After the WAN protocol driver has submitted the number of packets specified in the SendWindow member to the MiniportWanSend function, the WAN protocol driver holds incoming send packets queued until the miniport returns a completed send packet or calls NdisMWanSendComplete with a packet for which it previously returned an NDIS_STATUS_PENDING status, whichever occurs first. Subsequent NDIS_MAC_LINE_UP indications can be used if the NIC driver needs to change the SendWindow value dynamically.

Whenever subsequent NDIS_MAC_LINE_UP indications are made, whether to change the SendWindow value or for changes in line characteristics, the NdisLinkHandle member must be filled with the value set in the driver's initial line-up call to NdisMIndicateStatus for the same link.

The WAN protocol driver supplies a unique handle in the NdisLinkContext member of every initial NDIS_MAC_LINE_UP indication that establishes a new link or channel. The miniport must supply the given NdisLinkContext handle when it makes any subsequent NDIS_MAC_LINE_UP, NDIS_MAC_LINE_DOWN, and NDIS_MAC_FRAGMENT indications for the same link or channel.

Requirements

See Also

Reference

NDIS Structures
MiniportQueryInformation
MiniportWanSend
NDIS_MAC_FRAGMENT
NDIS_MAC_LINE_DOWN
NDIS_TAPI_EVENT
NDIS_TAPI_MAKE_CALL
NDIS_WAN_INFO
NDIS_WAN_PACKET
NdisMIndicateStatus
NdisMWanSendComplete
NdisRequest
OID_GEN_LINK_SPEED
OID_TAPI_GET_ID
OID_TAPI_MAKE_CALL
OID_WAN_GET_INFO