package com_maroontress_libcgi_db

class Box

#define com_maroontress_libcgi_db_Box_IMPORT
#include <com/maroontress/libcgi/db/Box.h>

ツリーを参照するためのボックスです。

ボックスは変数を複数保持しています。それぞれの変数には型があり、整数または文字列の値をもちます。

Struct Summary

struct Box
ボックスの実体となる構造体です。

Enum Summary

enum Box_Type 変数の型を表す列挙型です。
Box_Type_INT 整数を表します。
Box_Type_STRING 文字列を表します。

Method Summary

struct Box *	Box_create(const char * key, const void * data, size_t size) ボックスを生成します。
int	Box_getInt(struct Box * box, const char * name, (out) int * value) 変数に設定されている整数を取得します。
int	Box_getString(struct Box * box, const char * name, (out) char ** value) 変数に設定されている文字列の参照を取得します。
char *	Box_getKey(struct Box * box) キーを取得します。
int	Box_getType(struct Box * box, const char * name, enum Box_Type * type) 変数の型を取得します。
char **	Box_getNames(struct Box * box) 変数名の一覧を取得します。
void	Box_free(struct Box * box) ボックスを解放します。
int	Box_writeKeyXMLEscapedToTub(struct Box * box, struct com_maroontress_libcgi_util_Tub * tub) キーをXML向けにエスケープしてタブに出力します。
int	Box_writeToTub(struct Box * box, const char * name, struct com_maroontress_libcgi_util_Tub * tub) 指定した変数の値をタブに出力します。
int	Box_writeXMLEscapedToTub(struct Box * box, const char * name, struct com_maroontress_libcgi_util_Tub * tub) 指定した変数の値をXML向けにエスケープしてタブに出力します。
int	Box_writeXMLElementToTub(struct Box * box, struct com_maroontress_libcgi_util_Tub * tub, const char * elementName, ...) 指定した変数の値をXMLの要素としてタブに出力します。
int	Box_writeXMLElementWithKeyToTub(struct Box * box, struct com_maroontress_libcgi_util_Tub * tub, const char * elementName, const char * keyAttrName, ...) キーと指定した変数の値をXMLの要素としてタブに出力します。
char *	Box_createXMLElement(struct Box * box, const char * elementName, ...) 指定した変数を属性にもつXMLの要素となる文字列を生成します。
char *	Box_createXMLElementWithKey(struct Box * box, const char * elementName, const char * keyAttrName, ...) キーと指定した変数を属性にもつXMLの要素となる文字列を生成します。

Struct Detail

struct Box

ボックスの実体となる構造体です。

型の詳細は隠蔽されています。

Enum Detail

enum Box_Type

変数の型を表す列挙型です。

See:: Box_getType()

Box_Type_INT

整数を表します。

Box_Type_STRING

文字列を表します。

Method Detail

Box_create

struct Box * Box_create(	const char * key,
	const void * data,
	size_t size)

ボックスを生成します。

シリアライズされたデータからkeyをキーとするボックスを生成します。

戻り値が参照するオブジェクトはBox_free()で解放しなければなりません。

生成できない場合はNULLを返します。

このメソッドは実装上の都合で公開されているので、アプリケーションは呼び出さないでください。

Parameters:

key - キー
data - シリアライズされたデータ
size - dataのサイズ

Returns:

ボックス、またはNULL

Box_getInt

int Box_getInt(	struct Box * box,
	const char * name,
	(out) int * value)

変数に設定されている整数を取得します。

Parameters:

box - ボックス
name - 変数名
value - 整数の格納先

Returns:

成功した場合は0、そうでなければ−1

Box_getString

int Box_getString(	struct Box * box,
	const char * name,
	(out) char ** value)

変数に設定されている文字列の参照を取得します。

成功した場合、*valueが参照するオブジェクトはboxを解放するまで有効です。戻り値が参照するオブジェクトを変更、修正してはなりません。

Parameters:

box - ボックス
name - 変数名
value - 文字列の参照の格納先

Returns:

成功した場合は0、そうでなければ−1

Box_getKey

char * Box_getKey(

struct Box * box)

キーを取得します。

戻り値が参照するオブジェクトはboxを解放するまで有効です。戻り値が参照するオブジェクトを変更、修正してはなりません。

Parameters:

box - ボックス

Returns:

キー

Box_getType

int Box_getType(	struct Box * box,
	const char * name,
	enum Box_Type * type)

変数の型を取得します。

変数名がnameの変数の型を取得します。

Parameters:

box - ボックス
name - 変数名
type - 型の格納先

Returns:

成功した場合は0、そうでなければ−1

Box_getNames

char ** Box_getNames(

struct Box * box)

変数名の一覧を取得します。

戻り値が参照する配列オブジェクトとその要素のオブジェクトはboxを解放するまで有効です。それらのオブジェクトを変更、修正してはなりません。

取得できない場合はNULLを返します。

使用例を次に示します。

char **names, **p;

if ((names = Box_getNames(box)) == NULL) {
    errx(1, "Box_getNames() failed.");
}
for (p = names; *p != NULL; ++p) {
    printf("name: %s\n", *p);
}

Parameters:

box - ボックス

Returns:

成功した場合は変数名を表す文字列の参照の配列（最後の要素はNULL）、そうでなければNULL

Box_free

void Box_free(

struct Box * box)

ボックスを解放します。

呼び出し後はboxが参照するオブジェクトを参照してはなりません。

このメソッドは実装上の都合で公開されているので、アプリケーションは呼び出さないでください。

Parameters:

box - ボックス

Box_writeKeyXMLEscapedToTub

int Box_writeKeyXMLEscapedToTub(	struct Box * box,
	struct com_maroontress_libcgi_util_Tub * tub)

キーをXML向けにエスケープしてタブに出力します。

Parameters:

box - ボックス
tub - タブ

Returns:

成功した場合は0、そうでなければ−1

Box_writeToTub

int Box_writeToTub(	struct Box * box,
	const char * name,
	struct com_maroontress_libcgi_util_Tub * tub)

指定した変数の値をタブに出力します。

変数の型が整数の場合は、その整数を表す文字列をタブに出力します。

Parameters:

box - ボックス
name - 変数名
tub - タブ

Returns:

成功した場合は0、そうでなければ−1

Box_writeXMLEscapedToTub

int Box_writeXMLEscapedToTub(	struct Box * box,
	const char * name,
	struct com_maroontress_libcgi_util_Tub * tub)

指定した変数の値をXML向けにエスケープしてタブに出力します。

変数の型が整数の場合は、その整数を表す文字列をタブに出力します。

Parameters:

box - ボックス
name - 変数名
tub - タブ

Returns:

成功した場合は0、そうでなければ−1

Box_writeXMLElementToTub

int Box_writeXMLElementToTub(	struct Box * box,
	struct com_maroontress_libcgi_util_Tub * tub,
	const char * elementName,
	...)

指定した変数の値をXMLの要素としてタブに出力します。

XMLの要素をタブに出力します。要素の名前はelementNameになります。その要素の属性にボックスの指定した変数を設定します。

可変長引数にはボックスの変数名を列挙します。最後の引数はNULLでなければなりません。属性の名前は変数の名前に、属性の値は変数の値をXML向けにエスケープしたものになります。

使用例は次のようになります。

Box_writeXMLElementToTub(box, tub, "element", "name1", "name2", NULL);
/*
  タブへの出力は次のようになる:
  <element name1="値1" name2="値2" />
*/

Parameters:

box - ボックス
tub - タブ
elementName - 要素名

Returns:

成功した場合は0、そうでなければ−1

Box_writeXMLElementWithKeyToTub

int Box_writeXMLElementWithKeyToTub(	struct Box * box,
	struct com_maroontress_libcgi_util_Tub * tub,
	const char * elementName,
	const char * keyAttrName,
	...)

キーと指定した変数の値をXMLの要素としてタブに出力します。

XMLの要素をタブに出力します。要素の名前はelementNameになります。その要素の属性にボックスのキーと指定した変数を設定します。

使用例は次のようになります。

Box_writeXMLElementWithKeyToTub(box, tub, "element", "key", "name1", "name2", NULL);
/*
  タブへの出力は次のようになる:
  <element key="キー" name1="値1" name2="値2" />
*/

Parameters:

box - ボックス
tub - タブ
elementName - 要素名
keyAttrName - キーを値とする属性の名前

Returns:

成功した場合は0、そうでなければ−1

Box_createXMLElement

char * Box_createXMLElement(	struct Box * box,
	const char * elementName,
	...)

指定した変数を属性にもつXMLの要素となる文字列を生成します。

XMLの要素となる文字列を生成して返します。要素の名前はelementNameになります。その要素の属性にボックスの指定した変数を設定します。

生成に失敗した場合はNULLを返します。

成功した場合、戻り値が参照するオブジェクトはfree(3)で解放しなければなりません。

使用例は次のようになります。

char *s = Box_createXMLElement(box, "element", "name1", "name2", NULL);
/*
  sが参照する文字列は次のようになる:
  <element name1="name1の値" name2="name2の値" />
*/

Parameters:

box - ボックス
elementName - 要素名

Returns:

XMLの要素となる文字列、またはNULL

Box_createXMLElementWithKey

char * Box_createXMLElementWithKey(	struct Box * box,
	const char * elementName,
	const char * keyAttrName,
	...)

キーと指定した変数を属性にもつXMLの要素となる文字列を生成します。

XMLの要素となる文字列を生成して返します。要素の名前はelementNameになります。その要素の属性にボックスのキーと指定した変数を設定します。

生成に失敗した場合はNULLを返します。

成功した場合、戻り値が参照するオブジェクトはfree(3)で解放しなければなりません。

使用例は次のようになります。

char *s = Box_createXMLElementWithKey(box, "element", "key", "name1", "name2", NULL);
/*
  sが参照する文字列は次のようになる:
  <element key="キー" name1="値1" name2="値2" />
*/

Parameters:

box - ボックス
elementName - 要素名
keyAttrName - キーを値とする属性の名前

Returns:

XMLの要素となる文字列、またはNULL