NdisSend function

Article
06/19/2017

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisSend forwards a send request to the underlying driver.

Syntax

VOID NdisSend(
  _Out_ PNDIS_STATUS Status,
  _In_  NDIS_HANDLE  NdisBindingHandle,
  _In_  PNDIS_PACKET Packet
);

Parameters

Status [out]
Pointer to a caller-supplied variable that is set on return from this function. The underlying driver determines which NDIS_STATUS_XXX is returned, but it is usually one of the following values:
- NDIS_STATUS_SUCCESS
  The given packet is being transmitted over the network.
- NDIS_STATUS_PENDING
  The request is being handled asynchronously, and the caller's ProtocolSendComplete function 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 ProtocolStatus function was or will be called with NDIS_STATUS_RESET_START to indicate that a reset is in progress.
- NDIS_STATUS_FAILURE
  This value usually is a nonspecific default, returned when none of the more specific NDIS_STATUS_XXX caused the underlying driver to fail the request.
The specific NDIS_STATUS_XXX returned 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 driver might return NDIS_STATUS_NO_CABLE if its NIC indicates this condition to the driver.
NdisBindingHandle [in]
Specifies the handle returned by NdisOpenAdapter that identifies the target NIC or the virtual adapter of the next-lower driver to which the caller is bound. If the underlying driver is a connection-oriented miniport driver, the protocol must call NdisCoSendPackets, rather than NdisSend.
Packet [in]
Pointer to the caller-supplied packet descriptor, allocated with NdisAllocatePacket, with chained buffer descriptors mapping buffers containing the data that the underlying NIC driver should transmit over the wire.

Return value

None

Remarks

Before calling NdisSend, a protocol driver can call NdisSetPacketFlags to set the flags in the private header (reserved for use by NDIS) of the packet descriptor 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 MiniportSend function 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_DATA block associated with each packet descriptor to communicate far more information than the packet flags can convey. Before calling NdisSend, a protocol can use the NDIS_SET_PACKET_TIME_TO_SEND and/or NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO macros to set up out-of-band information, if any, relevant to the underlying driver in the NDIS_PACKET_OOB_DATA block associated with the protocol-allocated packet descriptor.

When an underlying driver that is serialized has insufficient resources to transmit a valid send packet, it has two alternatives:

Its MiniportSend function 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 MiniportSend function can simply return control with NDIS_STATUS_RESOURCES.

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

In either of the preceding scenarios, NdisSend returns NDIS_STATUS_PENDING to the caller, and that driver's ProtocolSendComplete function is called when the packet has been transmitted. If the underlying driver is deserialized, every packet passed in calls to NdisSend is returned to the caller's ProtocolSendComplete function when the underlying deserialized miniport driver completes the send operation.

As soon as a protocol calls NdisSend, it relinquishes ownership of the packet descriptor at Packet, of all buffers mapped by buffer descriptors it chained to the packet, and of any out-of-band information 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 ProtocolSendComplete function is called.

When either occurs, the protocol can call NdisReinitializePacket to prepare the packet for reuse after saving the buffer descriptors chained to the packet descriptor with calls to an NdisUnchainBufferAtXxx function. Reusing such a packet descriptor yields better performance than returning the packet to driver-allocated packet pool with NdisFreePacket 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 driver with NdisSend(or NdisSendPackets).

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisSendNetBufferListsinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL