enumerazione WS_READ_OPTION (webservices.h)

Articolo
03/08/2023

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. WS_STRING_TYPE WS_XML_STRING_TYPE WS_BYTES_TYPE

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

Condividi tramite