Estruturas de dados de tamanho variável

Quando estruturas de dados de tamanho variável são usadas para transmitir informações entre TAPI e o aplicativo, o aplicativo é responsável por alocar a memória necessária. A quantidade de memória alocada deve ser pelo menos grande o suficiente para a parte fixa da estrutura de dados e é definida pelo aplicativo no dwTotalSize membro da estrutura de dados. Os dwUsedSize e dwNeededSize membros são preenchidos pela TAPI. Se dwTotalSize for menor que o tamanho da parte fixa, LINEERR/ PHONEERR_STRUCTURETOOSMALL será retornado. Se uma função retornar sucesso, todos os campos na parte fixa foram preenchidos. Os dwUsedSize e dwNeededSize membros podem ser comparados para determinar se todas as partes variáveis foram preenchidas e quanto espaço seria necessário para preenchê-las todas.

Se dwNeededSize for igual a dwUsedSize, todas as partes fixas e variáveis foram preenchidas. Se dwNeededSize for maior do que dwUsedSize, algumas partes variáveis podem ter sido preenchidas, mas exatamente quais campos de tamanho variável foram preenchidos não está definido. Nenhuma parte variável é truncada, e as partes variáveis que teriam sido truncadas devido ao espaço insuficiente são indicadas por ter ambas as partes correspondentes "Deslocamento" e "Tamanho" definidas como zero. Se ambos não forem zero (e nenhum erro foi retornado), eles indicam o deslocamento e o tamanho dos dados de parte variável válidos e não truncados.

Um aplicativo sempre pode garantir que todas as partes variáveis sejam preenchidas alocando e indicando dwNeededSize bytes para a estrutura e chamando a função "Get" novamente até que a função retorne success e dwNeededSize seja igual a dwUsedSize. Isso deve acontecer na segunda tentativa, exceto para condições de corrida que causam mudanças no tamanho de partes variáveis entre chamadas, o que deve ser uma ocorrência rara.

Observação

Todas as cadeias de texto, independentemente da codificação, em estruturas de tamanho variável devem ser NULL-terminadas de acordo com as convenções normais de manipulação de cadeias de caracteres C.