Alokasi Memori

Aplikasi harus mengalokasikan memori untuk data ini; TAPI dan penyedia layanan menyediakan data. Jika operasi tidak sinkron, data tidak tersedia sampai pesan balasan asinkron menunjukkan keberhasilan.

Semua struktur data yang digunakan untuk meneruskan data antara aplikasi dan TAPI diratakan. Artinya, struktur data tidak berisi pointer ke substruktur yang berisi komponen data berukuran bervariasi. Sebaliknya, struktur data yang digunakan untuk meneruskan jumlah variabel data kembali ke aplikasi harus memiliki metastruktur berikut:

  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>

Anggota dwTotalSize adalah ukuran, dalam byte, yang dialokasikan untuk struktur data ini. Ini menandai akhir struktur data dan diatur oleh aplikasi sebelum memanggil fungsi yang menggunakan struktur data ini. Fungsi ini tidak membaca atau menulis melebihi ukuran ini. Aplikasi harus mengatur anggota dwTotalSize untuk menunjukkan jumlah total byte yang dialokasikan untuk TAPI untuk mengembalikan konten struktur.

TAPI mengisi anggota dwNeedSize . Ini menunjukkan berapa banyak byte yang diperlukan untuk mengembalikan semua data yang diminta. Keberadaan bidang berukuran bervariasi sering kali membuatnya tidak mungkin bagi aplikasi untuk memperkirakan ukuran struktur data yang diperlukan untuk dialokasikan. Bidang ini mengembalikan jumlah byte yang benar-benar diperlukan untuk data. Angka ini bisa lebih kecil dari, sama dengan, atau lebih besar dari dwTotalSize, dan mencakup ruang untuk anggota dwTotalSize itu sendiri. Jika lebih besar, struktur yang dikembalikan hanya diisi sebagian. Jika bidang yang diperlukan aplikasi tersedia dalam struktur parsial, tidak ada lagi yang harus dilakukan. Jika tidak, aplikasi harus mengalokasikan struktur setidaknya ukuran dwNeedSize dan memanggil fungsi lagi. Biasanya, ruang yang cukup tersedia kali ini untuk mengembalikan semua informasi, meskipun ada kemungkinan ukurannya bisa meningkat lagi.

TAPI mengisi anggota dwUsedSize jika mengembalikan data ke aplikasi untuk menunjukkan ukuran aktual, dalam byte, dari bagian struktur data yang berisi data yang berguna. Jika, misalnya, struktur yang dialokasikan terlalu kecil dan bidang terpotong adalah bidang berukuran bervariasi, dwNeededSize lebih besar dari dwTotalSize, dan bidang terpotong dibiarkan kosong. Oleh karena itu , anggota dwUsedSize dapat lebih kecil dari dwTotalSize. Nilai bidang parsial tidak dikembalikan.

Mengikuti header ini adalah bagian tetap dari struktur data. Ini berisi bidang reguler dan pasangan ukuran/offset yang menjelaskan bidang ukuran aktual yang bervariasi. Bidang offset berisi offset dalam byte dari bidang berukuran bervariasi dari awal rekaman. Bidang ukuran berisi ukuran dalam byte dari bidang berukuran bervariasi. Jika bidang berukuran bervariasi kosong, maka bidang ukuran adalah nol dan offset diatur ke nol. Bidang berukuran bervariasi yang akan dipotong jika ukuran struktur total tidak mencukupi dibiarkan kosong. Artinya, bidang ukurannya diatur ke nol dan offset diatur ke nol. Bidang berukuran bervariasi mengikuti bidang tetap.

Jika penyedia layanan harus mengisi anggota variabel, TAPI menginisialisasi ukuran yang sesuai dan mengimbangi anggota ke nol. Jika penyedia layanan mengisi anggota variabel, penyedia layanan harus mengatur ukuran yang sesuai dan mengimbangi anggota ke nilai yang sesuai, termasuk dwUsedSize dan dwNeededSize jika menetapkan anggota variabel. Penyedia layanan tidak boleh memotong anggota variabel untuk membuatnya sesuai dengan ruang yang tersedia.

Penyedia layanan harus memulai anggota variabel segera setelah anggota tetap struktur, dan meninggalkan ruang tambahan di akhir memori yang dialokasikan sehingga TAPI dapat menggunakannya untuk anggota panjang variabel. Ini dapat menempatkan anggota variabel dalam urutan apa pun, tetapi anggota harus berdekatan.