Struktur Data Berukuran Varian

Ketika struktur data berukuran varian digunakan untuk mengirimkan informasi antara TAPI dan aplikasi, aplikasi bertanggung jawab untuk mengalokasikan memori yang diperlukan. Jumlah memori yang dialokasikan harus setidaknya cukup besar untuk bagian tetap dari struktur data, dan diatur oleh aplikasi dalam dwTotalSize anggota struktur data. dwUsedSize dan dwNeededSize anggota diisi oleh TAPI. Jika dwTotalSize kurang dari ukuran bagian tetap, maka LINEERR/ PHONEERR_STRUCTURETOOSMALL dikembalikan. Jika fungsi mengembalikan keberhasilan, maka semua bidang dalam bagian tetap telah diisi. dwUsedSize dan dwNeedSize anggota dapat dibandingkan dengan menentukan apakah semua bagian variabel telah diisi, dan berapa banyak ruang yang diperlukan untuk mengisi semuanya.

Jika dwNeedSize sama dengan dwUsedSize, maka semua bagian tetap dan variabel telah diisi. Jika dwNeedSize lebih besar dari dwUsedSize, beberapa bagian variabel mungkin telah diisi, tetapi persis bidang berukuran bervariasi mana yang telah diisi tidak terdefinisi. Tidak ada bagian variabel yang pernah dipotong, dan bagian variabel yang akan dipotong karena ruang yang tidak mencukupi ditunjukkan dengan memiliki kedua bagian "Offset" dan "Ukuran" yang sesuai diatur ke nol. Jika ini bukan nol (dan tidak ada kesalahan yang dikembalikan), mereka menunjukkan offset dan ukuran data bagian variabel yang valid dan tidak terpotong.

Aplikasi selalu dapat menjamin bahwa semua bagian variabel diisi dengan mengalokasikan dan menunjukkan dwNeedSize byte untuk struktur dan memanggil fungsi "Get" lagi sampai fungsi mengembalikan keberhasilan dan dwNeedSize sama dengan dwUsedSize. Ini harus terjadi pada percobaan kedua kecuali untuk kondisi balapan yang menyebabkan perubahan ukuran bagian variabel antara panggilan, yang seharusnya jarang terjadi.

Nota

Semua string teks, terlepas dari pengodean, dalam struktur berukuran bervariasi harus NULL-dihentikan sesuai dengan konvensi penanganan string C normal.