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

See also

NdisAllocateBuffer

NdisAllocatePacket

NdisCopyFromPacketToPacket

NdisMoveMemory

NDIS_OOB_DATA_FROM_PACKET

NDIS_PACKET_OOB_DATA

Send comments about this topic to Microsoft