atributo byte_count

Artículo
06/13/2023

El atributo ACF [byte_count] es un atributo de parámetro que asocia un tamaño, en bytes, con el área de memoria indicada por el puntero.

[ function-attribute-list ] function-name(
    [byte_count(length-variable-name)] parameter-name);
    ...);

Parámetros

function-attribute-list: Especifica cero o más atributos de función ACF.
nombre de función: Especifica el nombre de la función definida en el archivo IDL. Se requiere el nombre de la función.
length-variable-name: Especifica el nombre del parámetro [in]-only que especifica el tamaño, en bytes, del área de memoria a la que hace referencia parameter-name.
parameter-name: Especifica el nombre del parámetro de puntero [out]only definido en el archivo IDL.

Observaciones

El atributo ACF [byte_count] representa una extensión de Microsoft a DCE IDL. Por lo tanto, este atributo no está disponible cuando se usa el modificador del compilador MIDL /osf.

Nota

El atributo [recuento de bytes] ya no se admite en la sintaxis NDR64 debido a la dificultad de calcular el tamaño necesario para todos los parámetros [out].

La memoria a la que hace referencia el parámetro de puntero es contiguo y no la asignan ni liberan los códigos auxiliares del cliente. Esta característica del atributo [byte_count] permite crear un área de búfer persistente en la memoria del cliente que se puede reutilizar durante más de una llamada al procedimiento remoto.

La capacidad de desactivar la asignación de memoria de código auxiliar del cliente le permite optimizar la aplicación para mejorar la eficacia. Por ejemplo, las funciones del proveedor de servicios que usan Rpc de Microsoft pueden usar el atributo [byte_count ]. Cuando una aplicación de usuario llama a la API del proveedor de servicios y envía un puntero a un búfer, el proveedor de servicios puede pasar el puntero del búfer a la función remota. El proveedor de servicios puede reutilizar el búfer durante varias llamadas remotas sin forzar al usuario a reasignar el área de memoria.

El área de memoria puede contener estructuras de datos complejas que constan de varios punteros. Dado que el área de memoria es contiguo, la aplicación no tiene que realizar varias llamadas para liberar individualmente cada puntero y estructura. En su lugar, puede asignar o liberar el área de memoria con una llamada a la asignación de memoria o rutina libre.

El búfer debe ser un parámetro [out]-only, mientras que la longitud del búfer en bytes debe ser un parámetro [in]-only.

Especifique un búfer lo suficientemente grande como para contener todos los parámetros [out]. Debido al relleno oculto, use overestimates en lugar de recuentos exactos. Por ejemplo, los punteros de 4 bytes no están separados en un límite alineado de 4 bytes en plataformas de 32 bits y punteros de 8 bytes en un límite de 8 bytes en plataformas de 64 bits. Por lo tanto, el relleno de alineación que realizarán los códigos auxiliares debe tener en cuenta en el espacio del búfer. Además, los niveles de empaquetado utilizados durante la compilación del lenguaje C pueden variar. Use un valor de recuento de bytes que tenga en cuenta los bytes de empaquetado adicionales agregados para el nivel de empaquetado usado durante la compilación del lenguaje C. Una práctica segura que abarca las plataformas de 32 bits y las plataformas de 64 bits es suponer que cada objeto que entra en el bloque de memoria grande comienza en una dirección que es un múltiplo de 8.

Ejemplos

/* IDL file */ 
HRESULT proc1([in] unsigned long length, 
              [out] struct my_struct * pMyStruct); 
 
/* ACF file */ 
proc1([byte_count(length)] pMyStruct);

Vea también

Archivo de configuración de la aplicación (ACF)
En
length_is
/Osf
out
size_is