Asignación de memoria

Las aplicaciones deben asignar memoria para estos datos; TAPI y el proveedor de servicios proporcionan los datos. Si la operación es asincrónica, los datos no están disponibles hasta que el mensaje de respuesta asincrónico indica que se ha realizado correctamente.

Todas las estructuras de datos usadas para pasar datos entre la aplicación y tapi se aplanan. Es decir, las estructuras de datos no contienen punteros a subestructuras que contienen componentes de datos de tamaño variable. En su lugar, las estructuras de datos usadas para devolver cantidades variables de datos a la aplicación deben tener la siguiente metaestructura:

  DWORD  dwTotalSize;
  DWORD  dwNeededSize;
  DWORD  dwUsedSize; 
    <fixed size fields> 
  DWORD  dw<VarSizeField1>Size;
  DWORD  dw<VarSizeField1>Offset; 
    <fixed size fields> 
  DWORD  dw<VarSizeField2>Size;
  DWORD  dw<VarSizeField2>Offset; 
    <common extensions> 
    <var sized field1> 
    <var sized field2>

El miembro dwTotalSize es el tamaño, en bytes, asignado a esta estructura de datos. Marca el final de la estructura de datos y lo establece la aplicación antes de invocar la función que usa esta estructura de datos. La función no lee ni escribe más allá de este tamaño. Una aplicación debe establecer el miembro dwTotalSize para indicar el número total de bytes asignados para TAPI para devolver el contenido de la estructura.

TAPI rellena el miembro dwNeededSize . Indica cuántos bytes se necesitan para devolver todos los datos solicitados. La existencia de campos de tamaño variable a menudo hace imposible que la aplicación calcule el tamaño de la estructura de datos necesario para asignar. Este campo devuelve el número de bytes realmente necesarios para los datos. Este número podría ser menor, igual o mayor que dwTotalSize, e incluye espacio para el propio miembro dwTotalSize . Si es mayor, la estructura devuelta solo se rellena parcialmente. Si los campos que requiere la aplicación están disponibles en la estructura parcial, no se debe hacer nada más. De lo contrario, la aplicación debe asignar una estructura al menos el tamaño de dwNeededSize e invocar la función de nuevo. Normalmente, hay suficiente espacio disponible esta vez para devolver toda la información, aunque es posible que el tamaño haya vuelto a aumentar.

TAPI rellena el miembro dwUsedSize si devuelve datos a la aplicación para indicar el tamaño real, en bytes, de la parte de la estructura de datos que contiene datos útiles. Si, por ejemplo, una estructura que se asignó era demasiado pequeña y el campo truncado es un campo de tamaño variable, dwNeededSize es mayor que dwTotalSize y el campo truncado se deja vacío. Por lo tanto, el miembro dwUsedSize podría ser menor que dwTotalSize. No se devuelven valores de campo parciales.

Después de este encabezado se encuentra la parte fija de la estructura de datos. Contiene campos regulares y pares de tamaño/desplazamiento que describen los campos de tamaño variable reales. El campo offset contiene el desplazamiento en bytes del campo de tamaño variable desde el principio del registro. El campo size contiene el tamaño en bytes del campo de tamaño variable. Si un campo de tamaño variable está vacío, el campo de tamaño es cero y el desplazamiento se establece en cero. Los campos de tamaño variable que se truncarían si el tamaño total de la estructura no es suficiente se dejan vacíos. Es decir, su campo de tamaño se establece en cero y el desplazamiento se establece en cero. Los campos de tamaño variable siguen los campos fijos.

Si el proveedor de servicios debe rellenar un miembro variable, TAPI inicializa el tamaño y los miembros de desplazamiento correspondientes en cero. Si el proveedor de servicios rellena el miembro de variable, debe establecer los miembros de tamaño y desplazamiento correspondientes en los valores adecuados, incluidos dwUsedSize y dwNeededSize si establece miembros de variable. El proveedor de servicios no debe truncar un miembro de variable para que se ajuste al espacio disponible.

El proveedor de servicios debe iniciar miembros variables inmediatamente después de los miembros fijos de la estructura y dejar cualquier espacio adicional al final de la memoria asignada para que TAPI pueda usarlo para los miembros de longitud variable. Puede colocar los miembros de la variable en cualquier orden, pero los miembros deben ser contiguos.