Estruturas de dados de tamanho variably

Quando estruturas de dados de tamanho variado 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 membro dwTotalSize da estrutura de dados. Os membros dwUsedSize e dwNeededSize são preenchidos pelo TAPI. Se dwTotalSize for menor que o tamanho da parte fixa, PHONEERR_STRUCTURETOOSMALL/LINEERR será retornado. Se uma função retornar êxito, todos os campos na parte fixa serão preenchidos. Os membros dwUsedSize e dwNeedSize podem ser comparados para determinar se todas as partes variáveis foram preenchidas e quanto espaço seria necessário para preenchê-las.

Se dwNeedSize for igual a dwUsedSize, todas as partes fixas e variáveis foram preenchidas. Se dwNeedSize for maior que dwUsedSize, algumas partes variáveis poderão ter sido preenchidas, mas exatamente quais campos de tamanho variavelmente foram preenchidos não serão definidos. Nenhuma parte variável é truncada e as partes variáveis que teriam sido truncadas devido ao espaço insuficiente são indicadas por terem as partes correspondentes "Deslocamento" e "Tamanho" definidas como zero. Se não forem zero (e nenhum erro foi retornado), eles indicarão o deslocamento e o tamanho dos dados válidos e não estruturados de parte variável.

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

Observação

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