Microsoft Windows CE 3.0  

NdisSend

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function forwards a send request to the underlying driver.

VOID NdisSend(
OUT PNDIS_STATUS
Status
,
IN NDIS_HANDLE
NdisBindingHandle
,
IN PNDIS_PACKET
Packet
);

Parameters

Status
Pointer to a caller-supplied variable that is set on return from this function. The underlying driver determines which NDIS_STATUS_ XXXis returned, but it is usually one of the following values:
Value Description
NDIS_STATUS_SUCCESS The specified packet is being transmitted over the network.
NDIS_STATUS_PENDING The request is being handled asynchronously, and the caller's ProtocolSendCompletefunction will be called when it is completed.
NDIS_STATUS_INVALID_PACKET The size of the requested transfer is too large for the NIC, or possibly the NIC indicated an erroneous packet transmission to its driver.
NDIS_STATUS_CLOSING The underlying driver is closing.
NDIS_STATUS_RESET_IN_PROGRESS The underlying driver is currently resetting the NIC. The caller's ProtocolStatusfunction was or will be called with NDIS_STATUS_RESET_START to indicate that a reset is in progress.
NDIS_STATUS_FAILURE This value is usually a nonspecific default returned when none of the more specific NDIS_STATUS_ XXXcaused the underlying driver to fail the request.

The specific NDIS_STATUS_ XXXreturned for device I/O errors that occur during a transmit operation depends on the nature of the NIC and the discretion of the NIC driver writer. For example, a miniport might return NDIS_STATUS_NO_CABLE if its NIC indicates this condition to the driver.

NdisBindingHandle
Handle returned by the NdisOpenAdapterfunction that identifies the target NIC or the virtual adapter of the next-lower driver to which the caller is bound.
Packet
Pointer to the caller-supplied packet descriptor, allocated with the NdisAllocatePacketfunction, with chained buffer descriptors mapping buffers containing the data that the underlying NIC driver should transmit over the wire.

Remarks

Before calling this function, a protocol driver can call the NdisSetPacketFlagsfunction to set the flags in the private header, reserved for use by NDIS, of the packet descriptor that it allocated. These flags specify caller-determined information about the requested send operation that is not contained in the packet data. The underlying NIC driver's MiniportSendfunction is given the send flags as an input parameter. The meaning of the packet flags bits is medium-specific and defined by the pair of collaborating drivers.

However, such a pair of collaborating drivers can use the NDIS_PACKET_OOB_DATAstructure associated with each packet descriptor to communicate far more information than the packet flags can convey. Before calling this function, a protocol can use the NDIS_SET_PACKET_TIME_TO_SENDand/or NDIS_SET_PACKET_MEDIA_SPECIFIC_INFOmacros to set up out-of-band information, if any, relevant to the underlying driver in the NDIS_PACKET_OOB_DATAstructure associated with the protocol-allocated packet descriptor.

When an underlying driver has insufficient resources to transmit a valid send packet, the driver has two alternatives:

  • Its MiniportSendfunction can insert the packet into an internal queue and return NDIS_STATUS_PENDING.

    The driver holds the packet queued until resources become available and sends the packet when they are.

  • Its MiniportSendfunction can return control with NDIS_STATUS_RESOURCES.

    The NDIS library holds such a returned packet in an internal queue for resubmission to the miniport. The miniport indicates its readiness to accept send packets later by calling NdisMSendResourcesAvailableor NdisMSendComplete, whichever call occurs first.

    In either of the preceding situations, this function returns NDIS_STATUS_PENDING to the caller, and the driver's ProtocolSendCompletefunction is called when the packet is transmitted.

    As soon as a protocol calls this function, it relinquishes ownership of the packet descriptor at Packetof all buffers mapped by buffer descriptors that it chained to the packet and of any out-of-band information that it supplied with the packet descriptor. The protocol regains ownership of these resources when the packet is completed with a status other than NDIS_STATUS_PENDING or when its ProtocolSendCompletefunction is called.

    When either occurs, the protocol can call the NdisReinitializePacketfunction to prepare the packet for reuse after saving the buffer descriptors chained to the packet descriptor with calls to an NdisUnchainBufferAt XXXfunction. Reusing such a packet descriptor yields better performance than returning the packet to driver-allocated packet pool with the NdisFreePacketfunction, and then reallocating it for another send later.

    An NDIS intermediate driver must repackage incoming sends from still higher level protocols in fresh packet descriptors before passing such a send request to the underlying miniport with this function.

    A driver that calls this function runs at IRQL <= DISPATCH_LEVEL.

    Requirements

    Runs on Versions Defined in Include Link to
    Windows CE OS 2.0 and later Ndis.h    
    Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

    See Also

    NdisAllocateBuffer, NdisAllocatePacket, NdisFreePacket, NdisGetPacketFlags, NdisMSendResourcesAvailable, NdisReinitializePacket, NdisUnchainBufferAtBack, NdisUnchainBufferAtFront



     Last updated on Tuesday, July 13, 2004

    © 2004 Microsoft Corporation. All rights reserved.