Compartir a través de

Función NdisAllocatePacketPoolEx (ndis.h)

  • Artículo

Nota NDIS 5. x ha quedado en desuso y se sustituye por NDIS 6. x. Para el nuevo desarrollo de controladores NDIS, consulte Controladores de red a partir de Windows Vista. Para obtener información sobre cómo migrar NDIS 5. controladores x a NDIS 6. x, consulte Porting NDIS 5.x Drivers to NDIS 6.0.

Esta función asigna e inicializa un bloque de almacenamiento para un grupo de descriptores de paquetes.

Sintaxis

void NdisAllocatePacketPoolEx(
  [out] PNDIS_STATUS Status,
  [out] PNDIS_HANDLE PoolHandle,
  [in]  UINT         NumberOfDescriptors,
  [in]  UINT         NumberOfOverflowDescriptors,
  [in]  UINT         ProtocolReservedLength
);

Parámetros

[out] Status

Apunta a una variable proporcionada por el autor de la llamada en la que esta función devuelve el estado de la asignación del grupo de paquetes.

[out] PoolHandle

Apunta a una variable proporcionada por el autor de la llamada en la que esta función devuelve un identificador al grupo de paquetes. Este identificador es un parámetro necesario para las funciones de NdisXXXPacket a las que llama el controlador posteriormente.

[in] NumberOfDescriptors

Especifica el número de descriptores de paquete que el grupo debe contener para un uso normal previsto. El numberOfDescriptors máximo que se puede asignar es 0xFFFF. Si se intenta asignar más de esto, NdisAllocatePacketPoolEx devuelve una Estado de NDIS_STATUS_RESOURCES.

[in] NumberOfOverflowDescriptors

Especifica el número de descriptores de paquete reservados para una situación de desbordamiento, es decir, cuando se usan todos los descriptores especificados por NumberOfDescriptors. Si la suma de este parámetro y numberOfDescriptors supera 0xFFFF, NdisAllocatePacketPoolEx reduce el valor proporcionado como este parámetro para que los numberOfDescriptors y NumberOfOverflowDescriptors sea igual a 0xFFFF.

[in] ProtocolReservedLength

Especifica el número de bytes que se asignarán para la matriz ProtocolReserved de cada descriptor de paquete. Para que los descriptores de paquete se usen en indicaciones de recepción, este parámetro es de 4*tamaño (PVOID).

Valor devuelto

Ninguno

Observaciones

En la tabla siguiente se muestran los posibles valores devueltos para esta función.

Estado Descripción
NDIS_STATUS_SUCCESS El controlador puede realizar llamadas a NdisAllocatePacket cuando necesita descriptores de paquetes para realizar indicaciones hasta controladores de nivel superior o para enviar paquetes a controladores de nivel inferior.
NDIS_STATUS_RESOURCES Error al intentar asignar el grupo de paquetes, posiblemente debido a una escasez de memoria. Esta devolución no significa necesariamente que se produzca un error en una llamada posterior. Sin embargo, el autor de la llamada podría intentar reducir el NumberOfDescriptors y llamar de nuevo inmediatamente.

Una llamada correcta a NdisAllocatePacketPoolEx devuelve un identificador al grupo de paquetes, que el autor de la llamada debe guardar. Normalmente, el controlador llama a NdisAllocatePacket una o varias veces con este identificador para asignar un conjunto de descriptores de paquete.

NdisAllocatePacketPoolEx asigna estáticamente solo suficiente memoria para dar cabida al número de descriptores de paquete especificados por NumberOfDescriptors. El número total de descriptores de paquete que se pueden asignar desde el grupo con llamadas a NdisAllocatePacket es el menor de 0xFFFF o la suma de NumberOfDescriptors y NumberOfOverflowDescriptors originalmente pasados a NdisAllocatePacketPoolEx. Los descriptores de desbordamiento solo se asignan dinámicamente durante una situación de desbordamiento; es decir, cuando los numberOfDescriptors especificados ya se han asignado y siguen en uso.

La suma de numberOfDescriptors y NumberOfOverflowDescriptors es el límite efectivo en el número de veces que el controlador puede llamar a NdisAllocatePacket antes de que deba llamar a NdisFreePacket devolver un descriptor de paquete a la lista gratuita del grupo de paquetes. Cuando aún no se ha asignado ningún descriptor de desbordamiento, NdisFreePacket devuelve el descriptor de paquete al grupo asignado estáticamente. Si ya se han asignado uno o varios descriptores de desbordamiento, NdisFreePacket devuelve el descriptor de paquete a la memoria del sistema, no al grupo.

El autor de la llamada de NdisAllocatePacketPoolEx debe establecer NumberOfDescriptors al número de descriptores de paquete necesarios para cargas normales previstas. El controlador debe establecer NumberOfOverflowDescriptors en el número de descriptores adicionales necesarios para dar cabida a las cargas máximas previstas. Si el número total posible de descriptores de paquete (NumberOfDescriptors más NumberOfOverflowDescriptors) se ha asignado desde el grupo, se ha asignado una llamada a NdisAllocatePacket devuelve NDIS_STATUS_RESOURCES.

A medida que los paquetes enviados o indicados se devuelven al controlador de asignación, puede reutilizar cada descriptor de paquetes después de llamar a NdisReinitializePacket y configurarlo de nuevo con una cadena de descriptores de búfer, o el controlador puede llamar a NdisFreePacket para devolver ese paquete a la lista gratuita. Reinicializar y reutilizar paquetes asignados desde el grupo de paquetes es mucho más rápido que liberarlos y, a continuación, tener que reasignarlos de nuevo. Antes de que un controlador llame a NdisReinitializePacket con un descriptor de paquete, debe guardar los punteros a descriptores de búfer que están encadenados al descriptor de paquetes, ya que NdisReinitializePacket establece el encabezado de la cadena de búfer en NULL.

Cuando un controlador ya no necesita descriptores de paquete, llama a [(nf-ndis-ndisfreepacketpool.md) para liberar el almacenamiento asignado con NdisAllocatePacketPoolEx.

versiones del sistema operativo: Windows CE .NET 4.0 y versiones posteriores.

Requisitos

Requisito Valor
encabezado de ndis.h
biblioteca de Ndis.lib
irQL IRQL <= DISPATCH_LEVEL

Consulte también