Función NdisAllocatePacketPoolEx (ndis.h)

  • Artículo

Nota NDIS 5. x está 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 Migración de controladores NDIS 5.x a 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 paquete NdisXXX a las que llama el controlador posteriormente.

[in] NumberOfDescriptors

Especifica el número de descriptores de paquetes que el grupo debe contener para un uso normal previsto. El número máximo de objetos NumberOfDescriptors que se pueden asignar es 0xFFFF. Si se intenta asignar más de esto, NdisAllocatePacketPoolEx devuelve un 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 todos los descriptores especificados por NumberOfDescriptors están en uso. Si la suma de este parámetro y NumberOfDescriptors supera 0xFFFF, NdisAllocatePacketPoolEx reduce el valor proporcionado como este parámetro para que el número total de 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

None

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 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 los objetos NumberOfDescriptors y volver a llamar 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 paquetes.

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 ya se han asignado los objetos NumberOfDescriptor especificados 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 para devolver un descriptor de paquete a la lista gratuita del grupo de paquetes. Cuando todavía 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 paquetes a la memoria del sistema, no al grupo.

El autor de la llamada de NdisAllocatePacketPoolEx debe establecer NumberOfDescriptors en el 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 acomodar 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, 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 paquetes, llama a [(nf-ndis-ndisfreepacketpool.md) para liberar el almacenamiento que asignó con NdisAllocatePacketPoolEx.

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

Requisitos

Requisito Valor
Header ndis.h
Library Ndis.lib
IRQL IRQL <= DISPATCH_LEVEL

Consulte también