JSON DOMインタフェース

17 JSON DOMインタフェース

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

JSON DOM関数

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

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

関数	概要
JsonDomGetRoot	3つのタイプのノードのいずれかであるDOMのルート・ノードを返します。
JsonDomSetRoot	指定されたノードをルートとして設定します。
JsonDomGetNumFields	オブジェクト内のフィールド数を返します。
JsonDomGetArraySize	配列内の要素の数を返します。
JsonDomGetElements	バッチ・インタフェース内の配列から一連の要素を返します。
JsonDomGetNodeType	ノードのタイプを返します。
JsonDomGetScalarInfoOci	スカラー・ノードから値情報を返します。
JsonDomCreateObject	新しい孤立DOMオブジェクト・ノードを作成します。
JsonDomCreateOCIInterval	OCIInterval型の新しい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	孤立ノードとそのすべての子孫を解放します。
JsonDomGetError	失敗したDOM操作のエラー・コードを戻します。
JsonDomClearError	DOMのエラー・コードをクリアします。
JsonDomGetErrorMessage	現行のDOMエラー・コードのレンダリングされたエラー・メッセージを戻します。

JsonDomGetRoot()

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

構文

JsonDomNode *JsonDomGetRoot(
      JsonDomDoc    *jdoc
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ

戻り値

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

ノート:

孤立ノードは、ツリーをルートから下位に向かって移動してアクセスすることはできません。
続行する前に、JsonDomGetGetError()をコールしてエラー・コードを確認します。

JsonDomSetRoot()

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

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

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

構文

void  JsonDomSetRoot(  
    JsonDomDoc     *jdoc,
    JsonDomNode    *root
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
root	IN	DOM内の孤立ノード

戻り値

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

ノート:

古いルートとすべての子孫が解放されます。
続行する前に、JsonDomGetGetError()をコールしてエラー・コードを確認します。

JsonDomGetNumFields()

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

構文

ub4 JsonDomGetNumFields(  
    JsonDomDoc     *jdoc,  
    JsonDomObject  *obj
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
obj	IN	DOM内のオブジェクト・ノード

戻り値

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

JsonDomGetArraySize()

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

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

構文

ub4 JsonDomGetArraySize(  
    JsonDomDoc *jdoc,
    JsonDomArray *ary
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
ary	IN	DOM内の配列ノード

戻り値

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

ノート:

ほとんどのDOMでは、フィールド名の重複は許可されません。
続行する前に、JsonDomGetGetError()をコールしてエラー・コードを確認します。

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配列により直接指定されるため、反復処理中に配列が変更された場合、このインタフェースは正しく機能しません。
続行する前に、JsonDomGetGetError()をコールしてエラー・コードを確認します。

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) ノードのタイプ(オブジェクト、配列、スカラー)。

ノート:

続行する前に、JsonDomGetGetError()をコールしてエラー・コードを確認します。

JsonDomGetScalarInfoOci()

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

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

構文

jsonerr  JsonDomGetScalarInfoOci(
  JsonDomDoc       *jdoc,
  JsonDomScalar    *nd,
  jznScalarVal     *val,
  JsonOCIVal       *aux
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
nd	IN	DOM内のスカラー・ノード
val	OUT	出力スカラー値
aux	OUT	補助出力構造

戻り値

(jsonerr) エラー・コード。JZNERR_OK (0)は、エラーがないことを示します。

ノート:

Oracleのネイティブ型は、JsonOCIVal*型の補助和集合で、固定解除されて構造化された形式で返されます。
続行する前に、JsonDomGetGetError()をコールしてエラー・コードを確認します。

JsonDomCreateObject()

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

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

構文

JsonDomObject *JsonDomCreateObject(
  JsonDomDoc    *jdoc
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ

戻り値

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

JsonDomCreateOCIInterval()

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

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

構文

JsonDomScalar *JsonDomCreateOCIInterval(
  JsonDomDoc     *jdoc,
  OCIInterval    *oinv
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
oinv	IN	OCIIntervalポインタ

戻り値

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

JsonDomCreateArray()

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

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

構文

JsonDomArray *JsonDomCreateArray(
  JsonDomDoc *jdoc
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ

戻り値

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

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のメモリー領域にコピーされます。

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のメモリー領域にコピーされます。

JsonDomCreateFloat()

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

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

構文

JsonDomScalar *JsonDomCreateFloat(
  JsonDomDoc      *jdoc,
  float            fval
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
fval	IN	浮動小数値

戻り値

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

JsonDomCreateDouble()

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

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

構文

JsonDomScalar *JsonDomCreateDouble(
  JsonDomDoc      *jdoc,
  double           dval
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
dval	IN	倍精度値

戻り値

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

JsonDomCreateBoolean()

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

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

構文

JsonDomScalar *JsonDomCreateBoolean(
  JsonDomDoc      *jdoc,
  boolean          bval
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
bval	IN	ブール値

戻り値

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

JsonDomCreateOCINumber()

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

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

構文

JsonDomScalar *JsonDomCreateOCINumber(
  JsonDomDoc      *jdoc,
  OCINumber       *onum
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
onum	IN	OCINumberポインタ

戻り値

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

JsonDomCreateOCIDate()

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

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

構文

JsonDomScalar *JsonDomCreateOCIDate(
  JsonDomDoc      *jdoc,
  OCIDate         *odate
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
odate	IN	OCIDateポインタ

戻り値

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

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スカラー・ノード

JsonDomCreateNull()

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

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

構文

JsonDomScalar *JsonDomCreateNull(
  JsonDomDoc      *jdoc
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ

戻り値

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

JsonDomSetField()

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

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

構文

jsonerr 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	フィールド値として設定する孤立ノード

戻り値

(jsonerr) エラー・コード。JZNERR_OK (0)は、エラーがないことを示します。

ノート:

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

JsonDomAppendElement()

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

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

構文

boolean JsonDomAppendElement(
  JsonDomDoc      *jdoc,
  JsonDomArray    *arr,
  JsonDomNode     *node
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
arr	IN	DOM内の配列
node	IN	要素値を設定する孤立ノード

戻り値

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

ノート:

続行する前に、JsonDomGetGetError()をコールしてエラー・コードを確認します。

JsonDomFreeNode()

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

構文

boolean JsonDomFreeNode(
  JsonDomDoc     *jdoc,
  JsonDomNode    *node
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
node	IN	DOM内で解放するノード

戻り値

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

ノート:

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

JsonDomGetError()

失敗したDOM操作のエラー・コードを戻します。

構文

jsonerr JsonDomGetError(
  JsonDomDoc     *jdoc
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ

戻り値

(jsonerr) エラー・コード。JZNERR_OK (0)は、エラーがないことを示します。

JsonDomGetErrorMessage()

現行のDOMエラー・コードのレンダリングされたエラー・メッセージを戻します。

構文

oratext *JsonDomGetErrorMessage(
  JsonDomDoc    *jdoc,
  jsonerr       *err,
  boolean        clear
);

現在のエラーがない場合は、空の文字列を戻します。オプションの<err>引数の現在のエラー・コードを戻します。<clear>がTRUEの場合、ドキュメント内の内部エラーはクリアされます。

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ
err	OUT	エラー・コードか、ない場合は`JZNERR_OK (0)`
clear	IN	`TRUE`を指定すると、読取り後にエラーがクリアされます

戻り値

(oratext *)エラー・メッセージ文字列。メモリー・エラーの場合はNULL。

JsonDomClearError()

DOMのエラー・コードをクリアします。

構文

void JsonDomClearError(
  JsonDomDoc     *jdoc
);

パラメータ	In/Out	説明
jdoc	IN	JSON DOMコンテナ

戻り値

(void)

定数

次の表に、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のレンダリング