WS_READ_OPTION-Enumeration (webservices.h)

  • Artikel

Gibt an, ob ein Wert erforderlich ist und wie der Wert zugeordnet werden soll.

Syntax

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;

Konstanten

 
WS_READ_REQUIRED_VALUE
Wert: 1
Die Option gibt an, dass der Wert im XML-Inhalt vorhanden sein muss.


Der Aufrufer muss den Speicher angeben, in den der Typ der obersten Ebene gelesen werden soll.


Die Größe des vom Aufrufer angegebenen Speichers variiert je nach Typ.
wird wie folgt deserialisiert:

  • Für Grundtypen (z. B. WS_INT32_TYPE) sollte der Speicher
    die Größe des Grundtyps festlegen. In diesem Fall muss der Heap nicht angegeben werden.

  • Für Strukturen (unabhängig davon, ob benutzerdefinierte Strukturen , die WS_STRUCT_TYPE verwenden,
    oder vordefinierte Wie z. B. WS_STRING), sollte der Speicher die
    genaue Größe der Struktur.
    Beachten Sie, dass Felder der Struktur, die auf andere Daten verweisen, weiterhin erforderlich sind.
    aus dem WS_HEAP zugeordnet werden. Wenn keine Felder für die vorhanden sind
    Eine bestimmte Struktur, dann muss der Heap nicht angegeben werden.




Zeigertypen (WS_WSZ_TYPE und WS_XML_BUFFER_TYPE),
darf nicht mit WS_READ_REQUIRED_VALUE verwendet werden. Die WS_READ_REQUIRED_POINTER
-Wert sollte stattdessen verwendet werden.


Wenn der Wert im zu lesenden XML-Code nicht vorhanden ist,
ein WS_E_INVALID_FORMAT Fehler wird zurückgegeben.
(Siehe Rückgabewerte für Windows-Webdienste.)
WS_READ_REQUIRED_POINTER
Wert: 2
Die Option gibt an, dass der Wert im XML-Inhalt vorhanden sein muss.


Der deserialisierte Wert wird immer auf der WS_HEAP zugeordnet, unabhängig von seiner Größe.
Der Zeiger auf den deserialisierten Wert wird zurückgegeben. Wenn Sie diese Option verwenden,
Der Aufrufer sollte die Adresse eines Zeigers und die Größe eines Zeigers übergeben,
Unabhängig vom Typ, der deserialisiert wird.


Wenn der Wert nicht vorhanden ist, wird ein Fehler zurückgegeben.
NULL wird nie zurückgegeben, wenn diese Option verwendet wird. Wird der
value ist optional, verwenden Sie WS_READ_OPTIONAL_POINTER.
WS_READ_OPTIONAL_POINTER
Wert: 3
Die Option gibt an, dass der Wert nicht im XML-Inhalt vorhanden sein muss.


Der deserialisierte Wert wird immer auf der WS_HEAP zugeordnet, unabhängig von seiner Größe.
Der Zeiger auf den deserialisierten Wert wird zurückgegeben. Wenn Sie diese Option verwenden,
Der Aufrufer sollte die Adresse eines Zeigers und die Größe eines Zeigers übergeben,
Unabhängig vom Typ, der deserialisiert wird.


Wenn der Wert im zu lesenden XML-Code nicht vorhanden ist, wird die Funktion
"succeed" und "NULL " werden für den Wert zurückgegeben.


Eine Anwendung, die diese Option verwendet, sollte darauf achten, vor dem Zugriff auf den Wert auf NULL zu überprüfen.
Wenn nie ein NULL-Wert erwartet wird, verwenden Sie WS_READ_REQUIRED_POINTER.
WS_READ_NILLABLE_POINTER
Wert: 4
Die Option gibt an, dass der Wert null sein kann oder im XML-Inhalt fehlt.


Der deserialisierte Wert wird immer auf der WS_HEAP zugeordnet, unabhängig von seiner Größe.
Der Zeiger auf den deserialisierten Wert wird zurückgegeben. Wenn Sie diese Option verwenden,
Der Aufrufer sollte die Adresse eines Zeigers und die Größe eines Zeigers übergeben,
Unabhängig vom Typ, der deserialisiert wird.


Wenn das Element null ist oder in der zu lesenden XML fehlt, ist die Funktion erfolgreich und
Ein NULL-Zeiger wird zurückgegeben.
Wenn das Element im zu lesenden XML-Code nicht null ist, wird der Wert normal zurückgegeben.


Eine Anwendung, die diese Option verwendet, sollte darauf achten, vor dem Zugriff auf den Wert auf NULL zu überprüfen.
Wenn nie ein NULL-Wert erwartet wird, verwenden Sie WS_READ_REQUIRED_POINTER.


Diese Option wird in Kombination mit WS_TYPE_MAPPING in APIs nicht unterstützt.
die XML lesen, einschließlich WsReadType - und WsReadElement-Aufrufen .
WS_READ_NILLABLE_VALUE
Wert: 5
Die Option gibt an, dass der Wert null sein kann oder im XML-Inhalt fehlt.


Der Aufrufer muss den Speicher angeben, in den der Typ der obersten Ebene gelesen werden soll.


Wenn das XML-Element null ist oder fehlt, wird ein Nullwert zurückgegeben. Wenn das XML-Element
non-nil, dann wird der Wert normal deserialisiert.


Diese Option wird in Kombination mit WS_TYPE_MAPPING in APIs nicht unterstützt.
die XML lesen, einschließlich WsReadType - und WsReadElement-Aufrufen .


Diese Option wird nur für die unten aufgeführten Typen unterstützt:
die über eine systeminterne Darstellung eines Nullwerts verfügen. Weitere Informationen finden Sie in der Dokumentation.
für jeden Typ, um Informationen darüber zu finden, wie null dargestellt wird.

Hinweise

In jedem WS_READ_OPTION wird erläutert, wann ein WS_HEAP-Objekt angegeben werden muss. Abhängig von der Funktion kann es in diesem Fall weiterhin möglich sein, einen NULL-Heapparameter zu übergeben. Weitere Informationen dazu, ob ein Standardheap verwendet wird, wenn der Heapparameter NULL ist, finden Sie in der Dokumentation für die jeweilige Funktion.

Die folgenden Punkte sollten beim Deserialisieren von Werten in ein Heapobjekt (WS_HEAP) berücksichtigt werden:

  • Deserialisierte Werte bleiben zugeordnet, bis der Heap freigegeben (WsFreeHeap) oder zurückgesetzt wird (WsResetHeap).
  • Jedes Mal, wenn Werte deserialisiert werden, werden sie an den Heap angefügt (anstatt vorhandene Werte zu ersetzen).
  • Wenn während der Deserialisierungsfunktion Fehler auftreten und die Funktion fehlschlägt, wird der vom Heapobjekt zugeordnete Arbeitsspeicher bis zum Auftreten des Fehlers nicht freigegeben.
  • Die Größe des Heaps kann verwendet werden, um die während der Deserialisierung vorgenommenen Gesamtzuordnungen zu begrenzen. Die maximale Größe des Heaps kann wie folgt bestimmt werden:
    • Bestimmen Sie die maximale Größe jedes Werts in Bytes, der während der Deserialisierung auf dem Heap zugeordnet wird. Beachten Sie, dass die Größen von deserialisierten Datenstrukturen je nach Plattform variieren können.
    • Jedes Array wird als ein Wert betrachtet. Beachten Sie, dass die tatsächliche Größe eines Elements im Array von der erforderlichen Ausrichtung des Elements beeinflusst werden kann.
    • Runden Sie die maximale Größe jedes Werts auf eine Grenze von 16 Byte.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 7 [Desktop-Apps | UWP-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 R2 [Desktop-Apps | UWP-Apps]
Kopfzeile webservices.h