Bagikan melalui

enumerasi WS_READ_OPTION (webservices.h)

  • Artikel

Menentukan apakah nilai diperlukan, dan bagaimana nilai harus dialokasikan.

Sintaks

typedef enum {
  WS_READ_REQUIRED_VALUE = 1,
  WS_READ_REQUIRED_POINTER = 2,
  WS_READ_OPTIONAL_POINTER = 3,
  WS_READ_NILLABLE_POINTER = 4,
  WS_READ_NILLABLE_VALUE = 5
} WS_READ_OPTION;

Konstanta

 
WS_READ_REQUIRED_VALUE
Nilai: 1
Opsi menentukan bahwa nilai harus ada dalam konten XML.


Pemanggil harus menentukan penyimpanan untuk membaca jenis tingkat atas ke dalamnya.


Ukuran penyimpanan yang ditentukan oleh pemanggil bervariasi menurut jenis
dideserialisasi, sebagai berikut:

  • Untuk primitif (seperti WS_INT32_TYPE), penyimpanan harus
    menjadi ukuran primitif. Dalam hal ini, tumpukan tidak perlu ditentukan.

  • Untuk struktur (apakah pengguna menentukan struktur yang menggunakan WS_STRUCT_TYPE,
    atau yang telah ditentukan sebelumnya seperti WS_STRING), penyimpanan harus
    ukuran struktur yang tepat.
    Perhatikan bahwa bidang struktur yang menunjuk ke data lain masih diperlukan untuk
    dialokasikan dari WS_HEAP. Jika tidak ada bidang untuk
    struktur tertentu, maka tumpukan tidak perlu ditentukan.




Jenis penunjuk (WS_WSZ_TYPE dan WS_XML_BUFFER_TYPE),
tidak dapat digunakan dengan WS_READ_REQUIRED_VALUE. WS_READ_REQUIRED_POINTER
nilai harus digunakan sebagai gantinya.


Jika nilai tidak ada dalam XML yang sedang dibaca,
kesalahan WS_E_INVALID_FORMAT akan dikembalikan.
(Lihat Nilai Pengembalian Windows Web Services.)
WS_READ_REQUIRED_POINTER
Nilai: 2
Opsi menentukan bahwa nilai harus ada dalam konten XML.


Nilai deserialisasi selalu dialokasikan pada WS_HEAP, terlepas dari ukurannya.
Penunjuk ke nilai deserialisasi dikembalikan. Saat menggunakan opsi ini,
penelepon harus meneruskan alamat penunjuk, dan ukuran penunjuk,
terlepas dari jenis yang dideserialisasi.


Jika nilai tidak ada, maka kesalahan akan dikembalikan.
NULL tidak akan pernah dikembalikan ketika opsi ini digunakan. Jika
nilai bersifat opsional, gunakan WS_READ_OPTIONAL_POINTER.
WS_READ_OPTIONAL_POINTER
Nilai: 3
Opsi menentukan bahwa nilai tidak perlu ada dalam konten XML.


Nilai deserialisasi selalu dialokasikan pada WS_HEAP, terlepas dari ukurannya.
Penunjuk ke nilai deserialisasi dikembalikan. Saat menggunakan opsi ini,
penelepon harus meneruskan alamat penunjuk, dan ukuran penunjuk,
terlepas dari jenis yang dideserialisasi.


Jika nilai tidak ada dalam XML yang dibaca, fungsi akan
berhasil dan NULL akan dikembalikan untuk nilai .


Aplikasi yang menggunakan opsi ini harus berhati-hati untuk memeriksa NULL sebelum mengakses nilai.
Jika nilai NULL tidak pernah diharapkan, gunakan WS_READ_REQUIRED_POINTER.
WS_READ_NILLABLE_POINTER
Nilai: 4
Opsi menentukan bahwa nilainya mungkin nihil atau hilang dalam konten XML.


Nilai deserialisasi selalu dialokasikan pada WS_HEAP, terlepas dari ukurannya.
Penunjuk ke nilai deserialisasi dikembalikan. Saat menggunakan opsi ini,
penelepon harus meneruskan alamat penunjuk, dan ukuran penunjuk,
terlepas dari jenis yang dideserialisasi.


Jika elemen nihil atau hilang dalam XML yang dibaca, fungsi akan berhasil dan
penunjuk NULL akan dikembalikan.
Jika elemen tidak nihil dalam XML yang dibaca, maka nilai dikembalikan secara normal.


Aplikasi yang menggunakan opsi ini harus berhati-hati untuk memeriksa NULL sebelum mengakses nilai.
Jika nilai NULL tidak pernah diharapkan, gunakan WS_READ_REQUIRED_POINTER.


Opsi ini tidak didukung dalam kombinasi dengan WS_TYPE_MAPPING di API
yang membaca XML, termasuk panggilan WsReadType dan WsReadElement .
WS_READ_NILLABLE_VALUE
Nilai: 5
Opsi menentukan bahwa nilainya mungkin nihil atau hilang dalam konten XML.


Pemanggil harus menentukan penyimpanan untuk membaca jenis tingkat atas ke dalamnya.


Jika elemen XML nihil atau hilang, maka nilai nihil dikembalikan. Jika elemen XML adalah
non-nihil, maka nilainya dideserialisasi secara normal.


Opsi ini tidak didukung dalam kombinasi dengan WS_TYPE_MAPPING di API
yang membaca XML, termasuk panggilan WsReadType dan WsReadElement .


Opsi ini hanya didukung untuk jenis berikut, tercantum di bawah ini,
yang memiliki cara intrinsik untuk mewakili nilai nihil. Lihat dokumentasi
untuk setiap jenis untuk informasi tentang bagaimana nihil diwakili.

Keterangan

Setiap WS_READ_OPTION membahas kapan objek WS_HEAP harus ditentukan. Tergantung pada fungsinya, mungkin masih mungkin untuk meneruskan parameter heap NULL dalam hal ini; lihat dokumentasi untuk fungsi tertentu untuk detail tentang apakah heap default digunakan jika parameter heap adalah NULL.

Berikut ini adalah hal-hal yang perlu dipertimbangkan saat mendeserialisasi nilai ke dalam objek heap (WS_HEAP):

  • Nilai yang dideserialisasi tetap dialokasikan sampai heap dikosongkan (WsFreeHeap) atau reset (WsResetHeap).
  • Setiap kali nilai dideserialisasi, nilai ditambahkan ke tumpukan (alih-alih mengganti nilai yang ada).
  • Jika kesalahan ditemui selama fungsi deserialisasi dan fungsi gagal, memori yang dialokasikan dari objek heap hingga kesalahan tidak akan dirilis.
  • Ukuran timbunan dapat digunakan untuk membatasi total alokasi yang dibuat selama deserialisasi. Ukuran maksimum tumpukan dapat ditentukan dengan cara berikut:
    • Tentukan ukuran maksimum, dalam byte, dari setiap nilai yang akan dialokasikan pada timbunan selama deserialisasi. Ingatlah untuk mempertimbangkan bahwa ukuran struktur data yang dideserialisasi dapat bervariasi menurut platform.
    • Setiap array dianggap sebagai satu nilai. Perhatikan bahwa ukuran aktual item dalam array dapat dipengaruhi oleh perataan item yang diperlukan.
    • Membulatkan ukuran maksimum setiap nilai ke batas 16 byte.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows 7 [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2008 R2 [aplikasi desktop | Aplikasi UWP]
Header webservices.h