Alocação de memória

Os aplicativos devem alocar memória para esses dados; O TAPI e o provedor de serviços fornecem os dados. Se a operação for assíncrona, os dados não estarão disponíveis até que a mensagem de resposta assíncrona indique êxito.

Todas as estruturas de dados usadas para passar dados entre o aplicativo e o TAPI são niveladas. Ou seja, as estruturas de dados não contêm ponteiros para subestruturas que contêm componentes de dados de tamanho variado. Em vez disso, as estruturas de dados usadas para passar quantidades variáveis de dados de volta para o aplicativo devem ter a seguinte metastrutura:

  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>

O membro dwTotalSize é o tamanho, em bytes, alocado para essa estrutura de dados. Ele marca o final da estrutura de dados e é definido pelo aplicativo antes de invocar a função que usa essa estrutura de dados. A função não lê nem grava além desse tamanho. Um aplicativo deve definir o membro dwTotalSize para indicar o número total de bytes alocados para TAPI retornar o conteúdo da estrutura.

O TAPI preenche o membro dwNeedEdSize . Indica quantos bytes são necessários para retornar todos os dados solicitados. A existência de campos de tamanho variável geralmente torna impossível para o aplicativo estimar o tamanho da estrutura de dados necessário para alocar. Esse campo retorna o número de bytes realmente necessários para os dados. Esse número pode ser menor que, igual ou maior que dwTotalSize, e inclui espaço para o próprio membro dwTotalSize . Se maior, a estrutura retornada só será parcialmente preenchida. Se os campos necessários pelo aplicativo estiverem disponíveis na estrutura parcial, nada mais deverá ser feito. Caso contrário, o aplicativo deverá alocar uma estrutura pelo menos o tamanho de dwNeedSize e invocar a função novamente. Normalmente, há espaço suficiente disponível desta vez para retornar todas as informações, embora seja possível que o tamanho possa ter aumentado novamente.

O TAPI preencherá o membro dwUsedSize se ele retornar dados para o aplicativo para indicar o tamanho real, em bytes, da parte da estrutura de dados que contém dados úteis. Se, por exemplo, uma estrutura que foi alocada for muito pequena e o campo truncado for um campo de tamanho variável, dwNeededSize for maior que dwTotalSize e o campo truncado ficar vazio. Portanto, o membro dwUsedSize pode ser menor que dwTotalSize. Valores de campo parciais não são retornados.

Seguindo esse cabeçalho está a parte fixa da estrutura de dados. Ele contém campos regulares e pares de tamanho/deslocamento que descrevem os campos de tamanho variably reais. O campo de deslocamento contém o deslocamento em bytes do campo de tamanho variavelmente desde o início do registro. O campo de tamanho contém o tamanho em bytes do campo de tamanho variavelmente. Se um campo de tamanho variavelmente estiver vazio, o campo de tamanho será zero e o deslocamento será definido como zero. Campos de tamanho variável que seriam truncados se o tamanho total da estrutura for insuficiente serão deixados vazios. Ou seja, seu campo de tamanho é definido como zero e o deslocamento é definido como zero. Os campos de tamanho variável seguem os campos fixos.

Se o provedor de serviços precisar preencher um membro de variável, o TAPI inicializará o tamanho correspondente e os membros de deslocamento para zero. Se o provedor de serviços preencher o membro da variável, ele deverá definir o tamanho correspondente e os membros de deslocamento para os valores apropriados, incluindo dwUsedSize e dwNeededSize se definir membros variáveis. O provedor de serviços não deve truncar um membro de variável para que ele se ajuste ao espaço disponível.

O provedor de serviços deve iniciar membros variáveis imediatamente após os membros fixos da estrutura e deixar qualquer espaço extra no final da memória alocada para que o TAPI possa usá-lo para os membros de comprimento variável. Ele pode colocar os membros da variável em qualquer ordem, mas os membros devem ser contíguos.