WS_READ_OPTION列挙 (webservices.h)

  • [アーティクル]

値が必要かどうかを指定し、値を割り当てる方法を指定します。

構文

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
値は代わりに使用する必要があります。


値が読み取られる XML に存在しない場合は、
WS_E_INVALID_FORMATエラーが返されます。
( 「Windows Web サービスの戻り値」を参照してください)。
WS_READ_REQUIRED_POINTER
値: 2
オプションは、値が XML コンテンツに存在する必要があることを指定します。


逆シリアル化された値は、サイズに関係なく、 常にWS_HEAPに割り当てられます。
逆シリアル化された値へのポインターが返されます。 このオプションを使用する場合は、次の操作を行います。
呼び出し元はポインターのアドレスとポインターのサイズを渡す必要があります。
逆シリアル化される型に関係なく。


値が存在しない場合は、エラーが返されます。
このオプションを使用すると、NULL は返されません。 取得するオブジェクトで
value は省略可能です。 WS_READ_OPTIONAL_POINTERを使用します。
WS_READ_OPTIONAL_POINTER
値: 3
オプションは、値が XML コンテンツに存在する必要がないように指定します。


逆シリアル化された値は、サイズに関係なく、 常にWS_HEAPに割り当てられます。
逆シリアル化された値へのポインターが返されます。 このオプションを使用する場合は、次の操作を行います。
呼び出し元はポインターのアドレスとポインターのサイズを渡す必要があります。
逆シリアル化される型に関係なく。


値が読み取られる XML に存在しない場合、関数は
succeed と NULL が値に対して返されます。


このオプションを使用するアプリケーションでは、値にアクセスする前に NULL をチェックするように注意する必要があります。
NULL 値が予期されない場合は、WS_READ_REQUIRED_POINTERを使用します。
WS_READ_NILLABLE_POINTER
値: 4
オプションは、XML コンテンツに値が存在しないか、または欠落している可能性があることを指定します。


逆シリアル化された値は、サイズに関係なく、 常にWS_HEAPに割り当てられます。
逆シリアル化された値へのポインターが返されます。 このオプションを使用する場合は、次の操作を行います。
呼び出し元はポインターのアドレスとポインターのサイズを渡す必要があります。
逆シリアル化される型に関係なく。


要素が読み取られる XML で nil または不足している場合、関数は成功し、
NULL ポインターが返されます。
読み取る XML で 要素が nil でない場合、値は通常どおりに返されます。


このオプションを使用するアプリケーションでは、値にアクセスする前に NULL をチェックするように注意する必要があります。
NULL 値が予期されない場合は、WS_READ_REQUIRED_POINTERを使用します。


このオプションは、API の WS_TYPE_MAPPING と組み合わせてサポートされていません
WsReadType 呼び出しや WsReadElement 呼び出しを含む XML を読み取る。
WS_READ_NILLABLE_VALUE
値: 5
オプションは、XML コンテンツに値が存在しないか、または欠落している可能性があることを指定します。


呼び出し元は、最上位レベルの型を読み取るストレージを指定する必要があります。


XML 要素が nil または不足している場合は、nil 値が返されます。 XML 要素が
非 nil の場合、値は通常どおりに逆シリアル化されます。


このオプションは、API の WS_TYPE_MAPPING と組み合わせてサポートされていません
WsReadType 呼び出しや WsReadElement 呼び出しを含む XML を読み取る。


このオプションは、以下に示す種類でのみサポートされます。
には、nil 値を表す組み込み方法があります。 ドキュメントを参照してください
nil の表現方法に関する情報については、各型に対して を指定します。

注釈

各 WS_READ_OPTION では、 WS_HEAP オブジェクトを指定する必要がある場合について説明します。 関数によっては、この場合も NULL ヒープ パラメーターを渡すことができます。ヒープ パラメーターが NULL の場合に既定のヒープが使用されるかどうかの詳細については、特定の関数のドキュメントを参照してください。

値をヒープ オブジェクト (WS_HEAP) に逆シリアル化する場合は、次の点を考慮する必要があります。

  • 逆シリアル化された値は、ヒープが解放されるまで (WsFreeHeap) またはリセット (WsResetHeap) まで割り当てられたままになります。
  • 値が逆シリアル化されるたびに、(既存の値を置き換える代わりに) ヒープに追加されます。
  • 逆シリアル化関数中にエラーが発生し、関数が失敗した場合、ヒープ オブジェクトから割り当てられたメモリは、エラーが解放されません。
  • ヒープのサイズを使用して、逆シリアル化中に行われる割り当ての合計を制限できます。 ヒープの最大サイズは、次の方法で決定できます。
    • 逆シリアル化中にヒープに割り当てられる各値の最大サイズをバイト単位で決定します。 逆シリアル化されたデータ構造のサイズはプラットフォームによって異なる可能性があることを考慮してください。
    • 各配列は 1 つの値と見なされます。 配列内の項目の実際のサイズは、項目の必要な配置の影響を受ける可能性があることに注意してください。
    • 各値の最大サイズを 16 バイトの境界に丸めます。

要件

要件 値
サポートされている最小のクライアント Windows 7 [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2008 R2 [デスクトップ アプリ |UWP アプリ]
Header webservices.h