Convenciones de los métodos de la API de generación de perfiles
En este tema se describen los valores devueltos de devolución de llamada del generador de perfiles y los búferes asignados por el llamador.
Valores devueltos de devolución de llamada
Un generador de perfiles devuelve un valor de estado como un HRESULT para cada notificación que inicie Common Language Runtime (CLR). Este valor de estado puede ser S_OK o E_FAIL. Actualmente, el motor en tiempo de ejecución omite el valor de estado en cada devolución de llamada salvo el método ICorProfilerCallback::ObjectReferences.
Búferes asignados por el llamador
Los métodos ICorProfilerInfo que admiten búferes asignados por el llamador, como el método GetAppDomainInfo, suelen atenerse a la firma siguiente:
HRESULT GetBuffer
(
[in] /* Some query information (for example, a name).*/,
[in] ULONG32 cBufferSizeStart,
[out] ULONG32 *pcBufferMax,
[out] /* TYPE */ InfoBuffer[]
);
Estos métodos siempre se comportan de la manera siguiente:
El parámetro cBufferSizeStart especifica el número de elementos asignado en el búfer. Este valor representa el tamaño del búfer, que es asignado por el llamador de este método.
El parámetro pcBufferMax está establecido en el número total de elementos disponibles. Una vez que el método vuelve, pcBufferMax está establecido en el número máximo de elementos que se pudieron devolver en lugar del número de elementos que realmente se devolvieron. En consecuencia, pcBufferMax es independiente del tamaño real del búfer asignado por el llamador.
El parámetro InfoBuffer especifica el búfer asignado por el llamador. Lo crea el llamador de este método. cBufferSizeStart especifica su tamaño. Una vez que el método vuelve, este búfer se habrá llenado con tantos elementos como sea posible. Puede haber más elementos disponibles que los que caben en el búfer. Si InfoBuffer es null, cBufferSizeStart debe ser 0. Si se devuelve algún elemento, el método devuelve S_OK y establece pcBufferMax en el número total de elementos disponibles.
Hay dos maneras de trabajar con búferes asignados por el llamador:
Método de paso único: asigne un búfer que espere que sea lo bastante grande como para contener todos los elementos devueltos. Prepárese para reasignar el búfer si resulta ser demasiado pequeño. De lo contrario, los datos pueden truncarse.
Método de doble paso: como alternativa, llame al método dos veces. En primer lugar, llame con un parámetro InfoBuffer de longitud cero para obtener el tamaño de búfer correcto. A continuación, establezca el tamaño del búfer en el valor devuelto en pcBufferMax y llame de nuevo a la función.
El primer método es más rápido y evita la asignación dinámica. No obstante, es posible que necesite reasignar el búfer si no es lo bastante grande para contener la información.
El segundo método es más lento porque implica dos llamadas y asignación dinámica. Por ejemplo, supongamos que la información de la consulta solicitada fue para el nombre de un dominio de aplicación. Cuando vuelva este método, debe comprobar que el búfer InfoBuffer fuera lo bastante grande para contener el nombre completo del dominio de aplicación. Para ello, compare el valor al que señala pcBufferMax con el valor del parámetro cBufferSizeStart. Si pcBufferMax señala a un valor mayor que cBufferSizeStart, asigne un búfer de InfoBuffer mayor, actualice cBufferSizeStart con el nuevo tamaño y llame de nuevo al método.
Parámetros de salida opcionales
En la API de generación de perfiles, todos los parámetros de salida (especificados por [out] en la sintaxis del método) son opcionales, a menos que un método tenga solamente un parámetro de salida. Un generador de perfiles pasa null para cualquier parámetro de salida que no le interese. El generador de perfiles también debe pasar valores coherentes para cualquier parámetro de entrada que esté asociado al parámetro de salida. Por ejemplo, si un parámetro de salida nulo representa un búfer que se va llenar de datos, el parámetro de entrada que especifica el tamaño del búfer debe establecerse en 0.