Condividi tramite

enumerazione WS_READ_OPTION (webservices.h)

  • Articolo

Specifica se è necessario un valore e la modalità di allocazione del valore.

Sintassi

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;

Costanti

 
WS_READ_REQUIRED_VALUE
Valore: 1
L'opzione specifica che il valore deve esistere nel contenuto XML.


Il chiamante deve specificare lo spazio di archiviazione in cui leggere il tipo di primo livello.


Le dimensioni dello spazio di archiviazione specificato dal chiamante variano in base al tipo
deserializzato, come indicato di seguito:

  • Per le primitive (ad esempio WS_INT32_TYPE), lo spazio di archiviazione deve
    essere la dimensione della primitiva. In questo caso, non è necessario specificare l'heap.

  • Per le strutture (se quelle definite dall'utente che usano WS_STRUCT_TYPE,
    o quelli predefiniti come WS_STRING), lo spazio di archiviazione deve essere il
    dimensioni esatte della struttura.
    Si noti che i campi della struttura che puntano ad altri dati sono ancora necessari per
    essere allocati dal WS_HEAP. Se non esistono campi per l'oggetto
    struttura specifica, non è necessario specificare l'heap.




Tipi di puntatore (WS_WSZ_TYPE e WS_XML_BUFFER_TYPE),
non può essere utilizzato con WS_READ_REQUIRED_VALUE. Il WS_READ_REQUIRED_POINTER
è consigliabile usare invece il valore .


Se il valore non è presente nel codice XML letto,
verrà restituito un errore di WS_E_INVALID_FORMAT .
Vedere Valori restituiti di Servizi Web Windows.
WS_READ_REQUIRED_POINTER
Valore: 2
L'opzione specifica che il valore deve esistere nel contenuto XML.


Il valore deserializzato viene sempre allocato nel WS_HEAP, indipendentemente dalle dimensioni.
Viene restituito il puntatore al valore deserializzato. Quando si usa questa opzione,
il chiamante deve passare l'indirizzo di un puntatore e le dimensioni di un puntatore,
indipendentemente dal tipo da deserializzare.


Se il valore non è presente, verrà restituito un errore.
NULL non verrà mai restituito quando viene usata questa opzione. Se il parametro
value è facoltativo, usare WS_READ_OPTIONAL_POINTER.
WS_READ_OPTIONAL_POINTER
Valore: 3
L'opzione specifica che il valore non deve esistere nel contenuto XML.


Il valore deserializzato viene sempre allocato nel WS_HEAP, indipendentemente dalle dimensioni.
Viene restituito il puntatore al valore deserializzato. Quando si usa questa opzione,
il chiamante deve passare l'indirizzo di un puntatore e le dimensioni di un puntatore,
indipendentemente dal tipo da deserializzare.


Se il valore non è presente nel codice XML letto, la funzione
succeed e NULL verranno restituiti per il valore .


Un'applicazione che usa questa opzione deve prestare attenzione a verificare la presenza di NULL prima di accedere al valore.
Se non è mai previsto un valore NULL , usare WS_READ_REQUIRED_POINTER.
WS_READ_NILLABLE_POINTER
Valore: 4
L'opzione specifica che il valore può essere nullo o mancante nel contenuto XML.


Il valore deserializzato viene sempre allocato nel WS_HEAP, indipendentemente dalle dimensioni.
Viene restituito il puntatore al valore deserializzato. Quando si usa questa opzione,
il chiamante deve passare l'indirizzo di un puntatore e le dimensioni di un puntatore,
indipendentemente dal tipo da deserializzare.


Se l'elemento è nil o mancante nel codice XML letto, la funzione avrà esito positivo e
verrà restituito un puntatore NULL .
Se l'elemento non è nullo nel codice XML letto, il valore viene restituito normalmente.


Un'applicazione che usa questa opzione deve prestare attenzione a verificare la presenza di NULL prima di accedere al valore.
Se non è mai previsto un valore NULL , usare WS_READ_REQUIRED_POINTER.


Questa opzione non è supportata in combinazione con WS_TYPE_MAPPING nelle API
che leggono codice XML, incluse le chiamate WsReadType e WsReadElement .
WS_READ_NILLABLE_VALUE
Valore: 5
L'opzione specifica che il valore può essere nullo o mancante nel contenuto XML.


Il chiamante deve specificare lo spazio di archiviazione in cui leggere il tipo di primo livello.


Se l'elemento XML è nil o mancante, viene restituito un valore nil. Se l'elemento XML è
non-nil, quindi il valore viene deserializzato normalmente.


Questa opzione non è supportata in combinazione con WS_TYPE_MAPPING nelle API
che leggono codice XML, incluse le chiamate WsReadType e WsReadElement .


Questa opzione è supportata solo per i tipi seguenti, elencati di seguito.
che hanno un modo intrinseco per rappresentare un valore nullo. Vedere la documentazione
per ogni tipo per informazioni su come viene rappresentato nil.

Commenti

Ogni WS_READ_OPTION illustra quando è necessario specificare un oggetto WS_HEAP . A seconda della funzione, potrebbe comunque essere possibile passare un parametro heap NULL in questo caso; vedere la documentazione relativa alla funzione specifica per informazioni dettagliate sull'uso di un heap predefinito se il parametro heap è NULL.

Di seguito sono riportati alcuni aspetti da considerare durante la deserializzazione dei valori in un oggetto heap (WS_HEAP):

  • I valori deserializzati rimangono allocati fino a quando l'heap non viene liberato (WsFreeHeap) o reimpostato (WsResetHeap).
  • Ogni volta che i valori vengono deserializzati, vengono aggiunti all'heap (anziché sostituire i valori esistenti).
  • Se si verificano errori durante la funzione di deserializzazione e la funzione ha esito negativo, la memoria allocata dall'oggetto heap fino a quando l'errore non verrà rilasciato.
  • Le dimensioni dell'heap possono essere usate per limitare le allocazioni totali effettuate durante la deserializzazione. Le dimensioni massime dell'heap possono essere determinate nel modo seguente:
    • Determinare le dimensioni massime, in byte, di ogni valore che verrà allocato nell'heap durante la deserializzazione. Tenere presente che le dimensioni delle strutture di dati deserializzate possono variare in base alla piattaforma.
    • Ogni matrice è considerata un valore. Si noti che le dimensioni effettive di un elemento nella matrice possono essere influenzate dall'allineamento richiesto dell'elemento.
    • Arrotondare le dimensioni massime di ogni valore a un limite di 16 byte.

Requisiti

Requisito Valore
Client minimo supportato Windows 7 [app desktop | App UWP]
Server minimo supportato Windows Server 2008 R2 [app desktop | App UWP]
Intestazione webservices.h