NDIS_MAC_LINE_UP

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

NDIS_MAC_LINE_UP contains information associated with a line-up indication made by a WAN NIC miniport.

Members

LinkSpeed

Specifies the speed of the link, in units of 100 bps.

Zero indicates no change from the speed the miniport originally returned for the OID_GEN_LINK_SPEED query.

Quality

Specifies the quality of service (QOS) of the new line as returned when the protocol called NdisRequest with OID_WAN_QUALITY_OF_SERVICE.

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 NDISWAN should use the value returned for MaxTransmit 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 client(s). 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 handle 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 ulParam2 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, that is passed down in subsequent calls, such as 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 zero 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 NDISWAN, to be used in future calls, such as to indicate receives, for the established link.

Comments

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

• When a link between a local node and a remote node in a wide area network 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 NDISWAN, for subsequent calls to NdisMIndicateStatus and NdisWanXxx functions affecting the just established link.

  MiniportQueryInformation also must use the returned NdisLinkContext handle as the value returned to NDISTAPI at DeviceID in 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, or to dynamically change the value of SendWindow specifying the number of outstanding sends the NIC driver accepts for its internal queue. For example, a miniport can make a subsequent line-up indication if the originally specified Quality of the line changes.

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 at the first NDIS_MAC_LINE_UP indication that the miniport makes for each link or data channel.

After NDISWAN has submitted the number of packets specified in SendWindow to MiniportWanSend, NDISWAN holds incoming send packets queued until the miniport returns a completed send packet or calls NdisMWanSendComplete with a packet for which it previously returned NDIS_STATUS_PENDING, whichever occurs first. Subsequent NDIS_MAC_LINE_UPs can be indicated 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.

NDISWAN supplies a unique handle at NdisLinkContext for 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.

For more information about WAN and TAPI OIDs, see Chapter 5.

See Also

MiniportQueryInformation, MiniportSetInformation, NDIS_MAC_FRAGMENT, NDIS_MAC_LINE_DOWN, NdisMIndicateStatus, NdisMWanIndicateReceive, NdisRequest, NDIS_TAPI_EVENT, ProtocolStatus