NdisCopyFromPacketToPacketSafe function
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.
NdisCopyFromPacketToPacketSafe copies a specified range of data from one packet to another.
Syntax
VOID NdisCopyFromPacketToPacketSafe(
_In_ PNDIS_PACKET Destination,
_In_ UINT DestinationOffset,
_In_ UINT BytesToCopy,
_In_ PNDIS_PACKET Source,
_In_ UINT SourceOffset,
_Out_ PUINT BytesCopied,
_In_ MM_PAGE_PRIORITY Priority
);
Parameters
Destination [in]
Pointer to the destination packet descriptor.DestinationOffset [in]
Specifies the byte offset within the destination packet at which to begin writing the copied data.BytesToCopy [in]
Specifies the number of bytes to copy.Source [in]
Pointer to the source packet descriptor.SourceOffset [in]
Specifies the byte offset within the source packet at which to begin copying the data.BytesCopied [out]
Pointer to the caller-supplied variable in which this function returns the number of bytes actually copied. This number can be less than the value of BytesToCopy if the source packet runs out of data, the destination packet runs out of space, or the system is low on resources.Priority [in]
Indicates the priority of the request as one of the following:LowPagePriority
Specifies a low priority. It is acceptable for NdisCopyFromPacketToPacketSafe to fail if system resources are low.NormalPagePriority
Specifies a normal priority. It is acceptable for NdisCopyFromPacketToPacketSafe to fail if system resources are low.HighPagePriority
Specifies a high priority. It is unacceptable for NdisCopyFromPacketToPacketSafe to fail unless system resources are exhausted. Since it can always recover from a failed copy operation, the miniport driver should never specify this priority.
Return value
None.
If the copy operation was successful, * BytesCopied is equal to BytesToCopy on the return of NdisCopyFromPacketToPacketSafe. If * BytesCopied is less than BytesToCopy on return from the function, the copy operation was not successful.
Remarks
NdisCopyFromPacketToPacketSafe is the safe version of NdisCopyFromPacketToPacket. Unlike NdisCopyFromPacketToPacket, NdisCopyFromPacketToPacketSafe does not cause a bug check if system resources are low or exhausted. Drivers should call NdisCopyFromPacketToPacketSafe instead of NdisCopyFromPacketToPacket. NDIS 5.1 driver must call NdisCopyFromPacketToPacketSafe instead of NdisCopyFromPacketToPacket.
The caller of NdisCopyFromPacketToPacketSafe allocates the destination packet, if not the source packet as well. The packet descriptor of the destination packet should specify enough buffer space to receive the data.
If the source packet runs out of data, the destination packet runs out of space before the specified number of bytes has been copied, or the system is low on resources, the copy operation stops. In either case, NdisCopyFromPacketToPacketSafe returns the number of bytes successfully copied from the source to the destination packet.
NdisCopyFromPacketToPacketSafe does not copy any out-of-band information associated with the given Source to the Destination. To copy this information, the driver can use pointers returned by NDIS_OOB_DATA_FROM_PACKET and then call NdisMoveMemory.
If Priority was set to LowPagePriority or NormalPagePriority, NdisCopyFromPacketToPacketSafe returns as soon as system resources become low or exhausted. If Priority was set to HighPagePriority, NdisCopyFromPacketToPacketSafe returns as soon as system resources are exhausted. Since miniport drivers can always recover from a failed copy operation, they should never call NdisCopyFromPacketToPacketSafe with Priority set to HighPagePriority. Setting Priority to HighPagePriority does not improve performance.
To determine whether the copy operation succeeded, the driver should compare BytesCopied with BytesToCopy after NdisCopyFromPacketToPacketSafe returns. If BytesCopied is equal to BytesToCopy, the copy operation succeeded. If BytesCopied is less than BytesToCopy, the source packet did not contained less data than BytesToCopy, the destination packet did not have enough buffer space to contain all the data to be copied, or the copy operation was aborted because system resources were low or exhausted.
Requirements
Target platform |
Universal |
Version |
Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisCopyFromNetBufferToNetBufferinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP. |
Header |
Ndis.h (include Ndis.h) |
Library |
Ndis.lib |
IRQL |
<= DISPATCH_LEVEL. |
See also