WS_READ_OPTION webservices.h) (列舉

  • 發行項

指定是否需要值，以及應該如何配置值。

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;

常數

 
WS_READ_REQUIRED_VALUE
值： 1
選項會指定值必須存在於 XML 內容中。


呼叫端必須指定要讀取最上層類型的記憶體。


呼叫端所指定的記憶體大小會因類型而異
正在還原串行化，如下所示：

  • 對於基本類型 (，例如 WS_INT32_TYPE) ，記憶體應該
    是基本類型的大小。 在此情況下，不需要指定堆積。

  • 針對結構， (用戶定義使用 WS_STRUCT_TYPE的使用者定義結構，
    或預先定義的WS_STRING ) ，記憶體應該是
    結構的確切大小。
    請注意，指向其他數據的結構欄位仍然需要
    可從 WS_HEAP配置。 如果 不存在的欄位
    特定結構，則不需要指定堆積。




指標類型 (WS_WSZ_TYPE 和 WS_XML_BUFFER_TYPE) ，
不能與 WS_READ_REQUIRED_VALUE搭配使用。 WS_READ_REQUIRED_POINTER
應該改用 value。


如果值不存在於所讀取的 XML 中，
將會傳回 WS_E_INVALID_FORMAT 錯誤。
(請參閱 Windows Web 服務傳回值。)
WS_READ_REQUIRED_POINTER
值： 2
選項會指定值必須存在於 XML 內容中。


不論其大小為何，還原串行化值一律配置在 WS_HEAP上。
會傳回還原串行化值的指標。 使用此選項時，
呼叫端應該傳遞指標的位址，以及指標的大小。
不論要還原串行化的類型為何。


如果值不存在，則會傳回錯誤。
使用此選項時，永遠不會傳回 NULL。 如果裝置上無法使用
值是選擇性的，請使用 WS_READ_OPTIONAL_POINTER。
WS_READ_OPTIONAL_POINTER
值： 3
選項會指定值不需要存在於 XML 內容中。


不論其大小為何，還原串行化值一律配置在 WS_HEAP上。
會傳回還原串行化值的指標。 使用此選項時，
呼叫端應該傳遞指標的位址，以及指標的大小。
不論要還原串行化的類型為何。


如果正在讀取的 XML 中沒有值，函式將會
成功並傳回 NULL 值。


使用此選項的應用程式應該先小心檢查 NULL ，再存取值。
如果從未預期 NULL 值，請使用 WS_READ_REQUIRED_POINTER。
WS_READ_NILLABLE_POINTER
值： 4
選項會指定值在 XML 內容中可能是 nil 或遺漏。


不論其大小為何，還原串行化值一律配置在 WS_HEAP上。
會傳回還原串行化值的指標。 使用此選項時，
呼叫端應該傳遞指標的位址，以及指標的大小。
不論要還原串行化的類型為何。


如果正在讀取的 XML 中元素為 nil 或遺失，則函式將會成功且
將會傳回 NULL 指標。
如果正在讀取的 XML 中元素不是 nil，則會正常傳回值。


使用此選項的應用程式應該先小心檢查 NULL ，再存取值。
如果從未預期 NULL 值，請使用 WS_READ_REQUIRED_POINTER。


此選項與 API 中的 WS_TYPE_MAPPING 不支援
會讀取 XML，包括 WsReadType 和 WsReadElement 呼叫。
WS_READ_NILLABLE_VALUE
值： 5
選項會指定值在 XML 內容中可能是 nil 或遺漏。


呼叫端必須指定要讀取最上層類型的記憶體。


如果 XML 元素為 nil 或遺失，則會傳回 nil 值。 如果 XML 元素為
非 nil，則此值會正常還原串行化。


此選項與 API 中的 WS_TYPE_MAPPING 不支援
會讀取 XML，包括 WsReadType 和 WsReadElement 呼叫。


此選項僅支援下列類型，如下所示。
具有代表 nil 值的內建方式。 請參閱檔
針對每個類型，以取得 nil 表示方式的相關信息。

備註

每個 WS_READ_OPTION 討論何時必須指定 WS_HEAP 物件。 視函式而定，在此案例中仍可能傳遞 NULL 堆積參數;如需是否使用預設堆積的詳細資訊，請參閱特定函式的檔，以了解堆積參數是否為 NULL。

以下是將值還原串行化為堆積物件時要考慮的事項， (WS_HEAP) ：

  • 還原串行化值會維持配置，直到將堆積釋放 (WsFreeHeap) 或重設 (WsResetHeap) 為止。
  • 每次還原串行化值時，它們都會附加至堆積 (，而不是取代現有值) 。
  • 如果在還原串行化函式期間遇到錯誤，且函式失敗，則從堆積物件配置到錯誤為止的記憶體將不會釋放。
  • 堆積的大小可用來限制還原串行化期間所做的總配置。 堆積的大小上限可以透過下列方式決定：
    • 決定在還原串行化期間將配置於堆積上之每個值的大小上限，以位元組為單位。 請記住，還原串行化數據結構的大小可能會因平臺而有所不同。
    • 每個數位都會被視為一個值。 請注意，陣列中項目的實際大小可能會受到專案所需對齊的影響。
    • 將每個值的大小上限四捨五入為16位元組界限。

規格需求

需求 值
最低支援的用戶端 Windows 7 [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 R2 [傳統型應用程式 |UWP 應用程式]
標頭 webservices.h