This structure defines the packet descriptors with chained buffer descriptors for which pointers are passed to many NdisXXX, MiniportXXX, and ProtocolXXX functions.
| Header file: | Ndis.h |
| Windows CE versions: | 2.0 and later |
typedef struct _NDIS_PACKET {
NDIS_PACKET_PRIVATE Private;
union {
struct {
UCHAR MiniportReserved[8];
UCHAR WrapperReserved[8];
}; struct {
UCHAR MacReserved[16];
};
};
UCHAR ProtocolReserved[1];
} NDIS_PACKET, *PNDIS_PACKET, **PPNDIS_PACKET;
NDIS drivers must call the NdisAllocatePacket function to allocate all packet descriptors that they use to indicate receives to higher-level drivers with the NdisMIndicateReceivePacket function. NDIS drivers must call NdisAllocatePacket to allocate all packet descriptors that they use for sends to underlying drivers with the NdisSend function, as well as packet descriptors that they pass to the NdisTransferData function.
Chained to each packet descriptor are one or more buffer descriptors mapping buffers that contain network packet data, either received or to be transmitted. NIC drivers and intermediate drivers can allocate packet descriptors with, at most, 16 bytes of ProtocolReserved space for receive indications.
Any buffers allocated by lower-level NDIS drivers must be mapped by buffer descriptors that were allocated from a buffer pool with the NdisAllocateBuffer function. Only highest-level Windows NT protocols can use MDLs set up by still higher-level drivers as substitutes for NDIS_BUFFER-type descriptors.
NDIS drivers typically use their respective XXXReserved areas to maintain per-packet state about outstanding transfers. For example, a protocol might store a pointer to a protocol-allocated buffer containing look-ahead data, which its ProtocolReceive function has already copied, in the ProtocolReserved area of a packet descriptor that the protocol allocates for a call to NdisTransferData.
While a particular packet descriptor is being used in a transfer operation, a single driver can use the MiniportReserved area and a single driver can use the ProtocolReserved. Consequently, NDIS intermediate drivers, which have both MiniportXXX and ProtocolXXX functions, cannot use these areas in incoming packet descriptors for their own purposes.
Instead, NDIS intermediate drivers must repackage each incoming packet in a fresh packet descriptor before it passes the transfer request down to an underlying driver or up to a higher-level driver.
This strategy ensures that the NDIS intermediate driver and the underlying driver each have a MiniportReserved area to use, that the intermediate driver and overlying protocol each have a ProtocolReserved area to use, and that the intermediate driver has a convenient and economical way to maintain per-packet state information about all current transfers. This also ensures that NDIS has correct information in the Private portion of each packet descriptor.
Drivers that supply and consume out-of-band data on network transfers and drivers that support multipacket receives and/or sends must use the member-specific NDIS_GET/SET_XXX macros or the NDIS_OOB_DATA_FROM_PACKET macro to access the NDIS_PACKET_OOB_DATA structure associated with each packet descriptor.
When a protocol driver calls the NdisSend function with a packet descriptor, it relinquishes ownership of the following until that packet descriptor is returned to its ProtocolSendComplete function:
NdisAllocateBuffer, NdisAllocatePacket, NdisChainBufferAtBack, NdisChainBufferAtFront, NdisCopyFromPacketToPacket, NdisFreePacket, NdisGetFirstBufferFromPacket, NdisGetPacketFlags, NdisMSendComplete, NdisMTransferDataComplete, NDIS_PACKET_OOB_DATA, NdisQueryPacket, NdisRecalculatePacketCounts, NdisReinitializePacket, NdisReturnPackets, NdisSend, NdisSetPacketFlags, NdisTransferData, NdisUnchainBufferAtBack, NdisUnchainBufferAtFront