1. XML C APIリファレンス
  2. JSON DOMインタフェース

17 JSON DOMインタフェース

DOM C APIのJSONインタフェースは、次のセクションにグループ化されています。

17.1 JSON DOM関数

次の表に、C用のDOM APIのJSONインタフェースで使用できるメソッドの概要を示します。

表17-1 JSON C実装のDOMメソッドの概要

関数 概要

JsonDomGetRoot

3つのタイプのノードのいずれかであるDOMのルート・ノードを返します。

JsonDomSetRoot

指定されたノードをルートとして設定します。

JsonDomGetNumFields

オブジェクト内のフィールド数を返します。

JsonDomGetArraySize

配列内の要素の数を返します。

JsonDomGetElements

バッチ・インタフェース内の配列から一連の要素を返します。

JsonDomGetNodeType

ノードのタイプを返します。

JsonDomGetScalarInfoOci

スカラー・ノードから値情報を返します。

JsonDomCreateObject

新しい孤立DOMオブジェクト・ノードを作成します。

JsonDomCreateArray

新しい孤立DOM配列ノードを作成します。

JsonDomCreateString

文字列型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomCreateBinary

バイナリ型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomCreateFloat

浮動小数型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomCreateDouble

倍精度型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomCreateBoolean

ブール型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomCreateOCINumber

OCINumber入力からNUMBER型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomCreateOCIDate

日付型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomCreateOCIDateTime

OCIDateTime型から、DATE、TIMESTAMPまたはTIMESTAMP WITH TIME ZONE型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomCreateNull

null型の新しい孤立DOMスカラー・ノードを作成します。

JsonDomSetField

指定されたフィールドの値をDOM内の指定されたオブジェクトに設定します。

JsonDomAppendElement

孤立ノードを、配列内の新しい要素として配列内の最後の位置に追加します。

JsonDomFreeNode

孤立ノードとそのすべての子孫を解放します。

17.1.1 JsonDomGetRoot()

DOMのルート・ノードの3つのタイプのノードのいずれかを返します(まれですが、子のないスカラーはRFCに従った有効なJSONドキュメントです)。

構文

JsonDomNode *JsonDomGetRoot(
      JsonDomDoc    *jdoc
    );
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

戻り値

DOMの(JsonDomNode *)ルート・ノード(設定されていない場合はNULL)。

注意:

孤立ノードは、ツリーをルートから下位に向かって移動してアクセスすることはできません。

17.1.2 JsonDomSetRoot()

指定されたノードをルートとして設定します。

新しいノードはNULLである可能性があります。新しいルートは孤立ノードである必要があります。つまり、古いルートがある場合に、それから下位に向かうツリー内に存在するノードにはできません。

孤立ノードは、コンストラクタ、別のDOMドキュメントからのノードのコピー、またはDOMツリーからのリンク解除によって作成されます。

構文

void  JsonDomSetRoot(  
    JsonDomDoc     *jdoc,
    JsonDomNode    *root
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
root
 
IN

DOM内の孤立ノード

戻り値

(void)

注意:

古いルートとすべての子孫が解放されます。

17.1.3 JsonDomGetNumFields()

オブジェクト内のフィールド数を返します。

構文

ub4 JsonDomGetNumFields(  
    JsonDomDoc     *jdoc,  
    JsonDomObject  *obj
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
obj
 
IN

DOM内のオブジェクト・ノード

戻り値

(ub4) このオブジェクト内のフィールド数。

17.1.4 JsonDomGetArraySize()

配列内の要素の数を返します。

孤立ノードは、コンストラクタ、別のDOMドキュメントからのノードのコピー、またはDOMツリーからのリンク解除によって作成されます。

構文

ub4 JsonDomGetArraySize(  
    JsonDomDoc *jdoc,
    JsonDomArray *ary
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
ary
 
IN

DOM内の配列ノード

戻り値

(ub4) この配列内の要素数。

17.1.5 JsonDomGetElements()

バッチ・インタフェース内の配列から一連の要素を返します。

これにより、コール元が固定サイズの配列を使用してその要素を反復処理する一方で、さらに複数の要素を一括取得できます。

構文

ub4 JsonDomGetElements(
  JsonDomDoc      *jdoc,
  JsonDomArray    *ary,
  ub4              startPos,
  ub4              fetchSz,
  JsonDomNode     *ndary[]
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
ary
 
IN

DOM内の配列ノード

 
startPos
 
IN

開始位置(0から始まる)

 
fetchSz
 
IN

取得する要素の数

 
ndary
 
OUT

配列からノードを返します

戻り値

(ub4) 出力ノード配列に返される要素数。

注意:

開始位置が0の最初の要素。反復はDOM配列により直接指定されるため、反復処理中に配列が変更された場合、このインタフェースは正しく機能しません。

17.1.6 JsonDomGetNodeType()

ノードのタイプを戻します。

可能な戻り値は次のとおりです。

  • JZNDOM_SCALAR
  • JZNDOM_ARRAY
  • JZNDOM_OBJECT

ノードは、サブクラス・タイプに安全にキャストできます。たとえば、戻り値がJZNDOM_SCALARの場合、ノードは(JsonDomScalar *)にキャストできます。

構文

jznnodetype JsonDomGetNodeType(
  JsonDomDoc     *jdoc,
  JsonDomNode    *node
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
node
 
IN

DOM内のノード

戻り値

(jznnodetype) ノードのタイプ(オブジェクト、配列、スカラー)。

17.1.7 JsonDomGetScalarInfoOci()

コール元が適用する必要があるval構造体のスカラー値を返します。これは多くの場合、呼出しコードのローカル変数を指すポインタです。

返される構造は区別された共用体です。値のスカラー・サブタイプ(たとえばJZNVAL_NUMBER)を最初のメンバーとして使用でき、スカラーの実際の値を適切な共有体メンバーから読み取ることができます。

構文

void  JsonDomGetScalarInfoOci(
  JsonDomDoc       *jdoc,
  JsonDomScalar    *nd,
  jznScalarVal     *val,
  JsonOCIVal       *aux
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
nd
 
IN

DOM内のスカラー・ノード

 
val
 
OUT

出力スカラー値

 
aux
 
OUT

補助出力構造

戻り値

(void)

注意:

Oracleのネイティブ型は、JsonOCIVal*型の補助和集合で、固定解除されて構造化された形式で返されます。

17.1.8 JsonDomCreateObject()

新しいDOMオブジェクト・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。

構文

JsonDomObject *JsonDomCreateObject(
  JsonDomDoc    *jdoc
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

戻り値

(JsonDomObject *) 新しい孤立DOMオブジェクト・ノード。

17.1.9 JsonDomCreateArray()

新しいDOM配列ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。

構文

JsonDomArray *JsonDomCreateArray(
  JsonDomDoc *jdoc
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

戻り値

(JsonDomArray *) 新しい孤立DOM配列ノード。

17.1.10 JsonDomCreateString()

文字列型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。スカラーは、文字列引数svalの値(長さがslen)に設定されます。

構文

JsonDomScalar *JsonDomCreateString(
  JsonDomDoc      *jdoc,
  oratext         *sval,
  ub4              slen
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
sval
 
IN

文字列バッファ・ポインタ

 
slen
 
IN

文字列バッファの長さ(バイト)

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

注意:

文字列はDOMのメモリー領域にコピーされます。

17.1.11 JsonDomCreateBinary()

バイナリ型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。スカラーは、長さがblenのバイト配列bvalの内容に設定されます。

構文

JsonDomScalar *JsonDomCreateBinary(
  JsonDomDoc      *jdoc,
  oratext         *bval,
  ub4              blen
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
bval
 
IN

バイナリ・バッファ・ポインタ

 
blen
 
IN

バイナリ・バッファの長さ

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

注意:

バイナリ値はDOMのメモリー領域にコピーされます。

17.1.12 JsonDomCreateFloat()

浮動小数型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。スカラーは、浮動小数値fvalに設定されます。

構文

JsonDomScalar *JsonDomCreateFloat(
  JsonDomDoc      *jdoc,
  float            fval
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
fval
 
IN

浮動小数値

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

17.1.13 JsonDomCreateDouble()

倍精度型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。スカラー値は、倍精度値dvalに設定されます。

構文

JsonDomScalar *JsonDomCreateDouble(
  JsonDomDoc      *jdoc,
  double           dval
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
dval
 
IN

倍精度値

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

17.1.14 JsonDomCreateBoolean()

ブール型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。

構文

JsonDomScalar *JsonDomCreateBoolean(
  JsonDomDoc      *jdoc,
  boolean          bval
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
bval
 
IN

ブール値

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

17.1.15 JsonDomCreateOCINumber()

OCINumberからNUMBER型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。

構文

JsonDomScalar *JsonDomCreateOCINumber(
  JsonDomDoc      *jdoc,
  OCINumber       *onum
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
onum
 
IN

OCINumberポインタ

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

17.1.16 JsonDomCreateOCIDate()

OCIDateからDATE型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。

構文

JsonDomScalar *JsonDomCreateOCIDate(
  JsonDomDoc      *jdoc,
  OCIDate         *odate
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
odate
 
IN

OCIDateポインタ

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

17.1.17 JsonDomCreateOCIDateTime()

OCIDateTimeからDATE、TIMESTAMPまたはTIMESTAMP WITH TIME ZONE型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。

構文

JsonDomScalar *JsonDomCreateOCIDateTime(
  JsonDomDoc      *jdoc,
  OCIDateTime     *odtime
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
odtime
 
IN

OCIDateTimeポインタ

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

17.1.18 JsonDomCreateNull()

JSON null型の新しいDOMスカラー・ノードを作成します。

新しいノードは、ルート・ノードから下位に向かうDOMツリーに連結されていない孤立ノードです。

構文

JsonDomScalar *JsonDomCreateNull(
  JsonDomDoc      *jdoc
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

戻り値

(JsonDomScalar *) 新しい孤立DOMスカラー・ノード

17.1.19 JsonDomSetField()

指定されたフィールドの値をDOM内の指定されたオブジェクトに設定します。

このフィールドが存在しない場合は作成され、存在する場合は古い値が置き換えられます。

構文

void JsonDomSetField(
  JsonDomDoc       *jdoc,
  JsonDomObject    *obj,
  oratext          *name,
  ub2               namelen,
  JsonDomNode      *node);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
obj
 
IN

DOM内のオブジェクト

 
name
 
IN

作成または置換するフィールド名を含む文字列

 
namelen
 
IN

フィールド名文字列の長さ

 
node
 
IN

フィールド値として設定する孤立ノード

戻り値

(void)

注意:

古いフィールド値が存在する場合は、すべての子孫とともに解放されます。

17.1.20 JsonDomAppendElement()

孤立ノードを、配列内の新しい要素として配列内の最後の位置に追加します。

この関数は、JsonDomAddElementを呼び出し、配列のサイズを挿入位置として指定することと同等です。

構文

boolean JsonDomAppendElement(
  JsonDomDoc      *jdoc,
  JsonDomArray    *arr,
  JsonDomNode     *node
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
arr
 
IN

DOM内の配列

 
node
 
IN

要素値を設定する孤立ノード

戻り値

(boolean)。TRUE 要素が追加された場合。それ以外の場合はFALSE。

17.1.21 JsonDomFreeNode()

孤立ノードとすべての子孫を解放します。

構文

boolean JsonDomFreeNode(
  JsonDomDoc     *jdoc,
  JsonDomNode    *node
);
パラメータ In/Out 説明 
jdoc
 
IN

JSON DOMコンテナ

 
node
 
IN

DOM内で解放するノード

戻り値

(boolean)。TRUE 解放された場合。孤立でない場合はFALSE。

注意:

古いフィールド値が存在する場合は、すべての子孫とともに解放されます。

17.2 定数

次の表に、JSONの様々な型の定数を示します。

DOMノード・タイプの定数

定数 説明 
JZNDOM_OBJECT

DOMノードがオブジェクト型であることを示します

 
JZNDOM_ARRAY

DOMノードが配列型であることを示します

 
JZNDOM_SCALAR

DOMノードがスカラー型であることを示します

スカラー値タイプの定数

定数 JSON値タイプ 
JZNVAL_STRING

String

 
JZNVAL_ORA_NUMBER

Number

 
JZNVAL_TRUE

Boolean true

 
JZNVAL_FALSE

Boolean false

 
JZNVAL_BINARY

Binary

 
JZNVAL_DOUBLE

Double

 
JZNVAL_FLOAT

Float

 
JZNVAL_ORA_DATE

Date

 
JZNVAL_ORA_TIMESTAMP

Timestamp

 
JZNVAL_ORA_DAYSECOND_DUR

日単位の秒間隔

 
JZNVAL_ORA_YEARMONTH_DUR

年月時間隔

 
JZNVAL_ORA_TIMESTAMPTZ

タイム・ゾーン付きのタイムスタンプ

 
JZNVAL_NULL

JSON null

注意:

定数JZNVAL_DOUBLEおよびJZNVAL_FLOATは、それぞれIEEE FLOATおよびDOUBLEにマップされており、プログラミング言語で最もよく使用されます。

JSON検証定数

定数 説明 
JZN_ALLOW_NONE

JSON仕様への厳密な準拠。

 
JZN_ALLOW_UNQUOTED_NAMES

オブジェクト・フィールド名は、二重引用符で囲まずに表示できます。例: {a: 123}

 
JZN_ALLOW_SINGLE_QUOTES

フィールド名と文字列アイテムは、必要に応じて一重引用符で囲むことができます。例: {'a': 'cat'}

 
JZN_ALLOW_UNQUOTED_UNICODE

ASCII以外の文字を引用符なしのフィールド名に表示できるようにします。

 
JZN_ALLOW_NUMERIC_QUIRKS

JSON仕様に厳密に準拠していない一般的な数値形式を許可します。例: +.123

 
JZN_ALLOW_CONTROLS_WHITESPACE
 重要でない空白が許可されている場所にASCII制御文字が表示されるようにします(通常はタブ、改行、キャリッジ・リターンのみ)。例: フォームフィード文字 
JZN_ALLOW_TRAILING_COMMAS

後続の項目またはフィールドと値のペアを含まないコンテナに後続のカンマを含めることができます。例: [1,2,3,]

 
JZN_ALLOW_MIXEDCASE_KEYWORDS

キーワードを大小文字を区別せずに表示できます。通常、小文字である必要があります。例: NULL, True

 
JZN_ALLOW_SCALAR_DOCUMENTS

単一のスカラー・アイテムを有効なJSONドキュメントとみなすことができます。古いRFCでは、ドキュメントは2つのコンテナ・タイプのいずれかである必要がありました。新しいRFCでは、スカラーを含む任意のアイテムが許可されます。

 
JZN_ALLOW_LEADING_BOM

バイト順序マークを、ドキュメントがUTF-8でエンコードされている場合でも、JSONドキュメントの先頭文字として表示されるようにします。通常はUTF-16ドキュメントのみに限定されます。

 
JZN_ALLOW_ALL

前述のすべてのフラグをオンにします。

注意:

JSON検証定数はビット・フラグであり、組み合せて使用できます。

JSONエンコーディング定数

定数 説明 
JZN_INPUT_UTF8

入力はUTF-8エンコーディングです

 
JZN_INPUT_DETECT

入力のエンコーディングを検出する必要があります

 
JZN_INPUT_CONVERT

入力には文字セット変換が必要です

JSON印刷定数

定数 説明 
JZNU_PRINT_PRETTY

テキスト形式のJSON表示出力のレンダリング

 
JZNU_PRINT_ASCII

エスケープ付きネイティブASCIIを使用したテキスト形式のJSONのレンダリング

 
JZNU_PRINT_NUMFORMAT

標準出力番号を含むテキスト形式のJSONのレンダリング