Alocação de memória

Os aplicativos devem alocar memória para esses dados; A TAPI e o prestador 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 variável. Em vez disso, as estruturas de dados usadas para passar quantidades variáveis de dados de volta para o aplicativo devem ter a seguinte metaestrutura:

  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 dwTotalSize membro é o tamanho, em bytes, alocado para essa estrutura de dados. Ele marca o fim 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 escreve para além deste tamanho. Um aplicativo deve definir o dwTotalSize membro para indicar o número total de bytes alocados para TAPI retornar o conteúdo da estrutura.

TAPI preenche o dwNeededSize membro. Ele indica quantos bytes são necessários para retornar todos os dados solicitados. A existência de campos de tamanho variável muitas vezes torna impossível para o aplicativo estimar o tamanho da estrutura de dados necessário para alocar. Este campo devolve o número de bytes realmente necessários para os dados. Esse número pode ser menor, igual ou maior que dwTotalSizee inclui espaço para o dwTotalSize membro em si. Se maior, a estrutura retornada é apenas parcialmente preenchida. Se os campos exigidos pelo aplicativo estiverem disponíveis na estrutura parcial, nada mais deve ser feito. Caso contrário, o aplicativo deve alocar uma estrutura pelo menos do tamanho de dwNeededSize 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.

TAPI preenche o dwUsedSize membro 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 era muito pequena e o campo truncado é um campo de tamanho variável, dwNeededSize é maior do que dwTotalSizee o campo truncado é deixado vazio. O dwUsedSize membro pode, portanto, ser menor do que dwTotalSize. Os valores de campo parciais não são retornados.

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

Se o provedor de serviços precisar preencher um membro variável, a TAPI inicializará o tamanho correspondente e deslocará os membros para zero. Se o provedor de serviços preencher o membro variável, ele deverá definir o tamanho correspondente e os membros de deslocamento para valores apropriados, incluindo dwUsedSize e dwNeededSize se definir membros variáveis. O provedor de serviços não deve truncar um membro variável para que ele caiba no 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 a TAPI possa usá-lo para os membros de comprimento variável. Ele pode colocar os membros variáveis em qualquer ordem, mas os membros devem ser contíguos.