ホーム › Networking.WindowsWebServices › WS_READ_OPTION

WS_READ_OPTION

列挙型

基底型i4

メンバー 5

名前	10進	16進	説明
WS_READ_REQUIRED_VALUE	1	0x1	このオプションは、値が 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 Services の戻り値を参照してください。)
WS_READ_REQUIRED_POINTER	2	0x2	このオプションは、値が XML コンテンツ内に存在しなければならないことを指定します。逆シリアル化された値は、そのサイズにかかわらず常に WS_HEAP 上に割り当てられます。逆シリアル化された値へのポインターが返されます。このオプションを使用する場合、呼び出し元は逆シリアル化される型にかかわらず、ポインターのアドレスとポインターのサイズを渡してください。値が存在しない場合はエラーが返されます。このオプションを使用したときに NULL が返されることはありません。値が省略可能な場合は、WS_READ_OPTIONAL_POINTER を使用してください。
WS_READ_OPTIONAL_POINTER	3	0x3	このオプションは、値が XML コンテンツ内に存在しなくてもよいことを指定します。逆シリアル化された値は、そのサイズにかかわらず常に WS_HEAP 上に割り当てられます。逆シリアル化された値へのポインターが返されます。このオプションを使用する場合、呼び出し元は逆シリアル化される型にかかわらず、ポインターのアドレスとポインターのサイズを渡してください。読み取り対象の XML に値が存在しない場合、関数は成功し、値として NULL が返されます。このオプションを使用するアプリケーションは、値にアクセスする前に NULL かどうかを慎重に確認してください。NULL 値がまったく想定されない場合は、WS_READ_REQUIRED_POINTER を使用してください。
WS_READ_NILLABLE_POINTER	4	0x4	このオプションは、値が XML コンテンツ内で nil であるか、存在しない可能性があることを指定します。逆シリアル化された値は、そのサイズにかかわらず常に WS_HEAP 上に割り当てられます。逆シリアル化された値へのポインターが返されます。このオプションを使用する場合、呼び出し元は逆シリアル化される型にかかわらず、ポインターのアドレスとポインターのサイズを渡してください。読み取り対象の XML で要素が nil であるか存在しない場合、関数は成功し、NULL ポインターが返されます。読み取り対象の XML で要素が nil でない場合は、値が通常どおり返されます。このオプションを使用するアプリケーションは、値にアクセスする前に NULL かどうかを慎重に確認してください。NULL 値がまったく想定されない場合は、WS_READ_REQUIRED_POINTER を使用してください。このオプションは、WsReadType や WsReadElement の呼び出しを含む XML を読み取る API では、WS_TYPE_MAPPING との組み合わせはサポートされません。
WS_READ_NILLABLE_VALUE	5	0x5	このオプションは、値が XML コンテンツ内で nil であるか、存在しない可能性があることを指定します。呼び出し元は、最上位の型を読み取る先の記憶域を指定しなければなりません。 XML 要素が nil であるか存在しない場合は、nil 値が返されます。XML 要素が nil でない場合は、値が通常どおり逆シリアル化されます。このオプションは、WsReadType や WsReadElement の呼び出しを含む XML を読み取る API では、WS_TYPE_MAPPING との組み合わせはサポートされません。このオプションは、nil 値を表現する固有の手段を持つ次の型でのみサポートされます。nil がどのように表現されるかについては、各型のドキュメントを参照してください。 WS_STRING_TYPE WS_XML_STRING_TYPE WS_BYTES_TYPE

公式ドキュメント

値が必須かどうか、および値をどのように割り当てるかを指定します。

解説(Remarks)

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

ヒープオブジェクト (WS_HEAP) に値を逆シリアル化する際は、次の点を考慮してください。

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

列挙メンバーの定義。HSP タブは #define global(値は16進)。

typedef enum WS_READ_OPTION : int {
    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;

public enum WS_READ_OPTION : int
{
    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,
}

Public Enum WS_READ_OPTION As Integer
    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
End Enum

import enum

class WS_READ_OPTION(enum.IntEnum):
    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
pub const WS_READ_REQUIRED_VALUE: i32 = 1;
pub const WS_READ_REQUIRED_POINTER: i32 = 2;
pub const WS_READ_OPTIONAL_POINTER: i32 = 3;
pub const WS_READ_NILLABLE_POINTER: i32 = 4;
pub const WS_READ_NILLABLE_VALUE: i32 = 5;

// WS_READ_OPTION
const (
	WS_READ_REQUIRED_VALUE int32 = 1
	WS_READ_REQUIRED_POINTER int32 = 2
	WS_READ_OPTIONAL_POINTER int32 = 3
	WS_READ_NILLABLE_POINTER int32 = 4
	WS_READ_NILLABLE_VALUE int32 = 5
)

const
  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
pub const WS_READ_REQUIRED_VALUE: i32 = 1;
pub const WS_READ_REQUIRED_POINTER: i32 = 2;
pub const WS_READ_OPTIONAL_POINTER: i32 = 3;
pub const WS_READ_NILLABLE_POINTER: i32 = 4;
pub const WS_READ_NILLABLE_VALUE: i32 = 5;

const
  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

enum WS_READ_OPTION : int {
    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,
}

#define global WS_READ_REQUIRED_VALUE   0x1
#define global WS_READ_REQUIRED_POINTER 0x2
#define global WS_READ_OPTIONAL_POINTER 0x3
#define global WS_READ_NILLABLE_POINTER 0x4
#define global WS_READ_NILLABLE_VALUE   0x5