RTVals のC++アプリからの利用¶

この節では RTVal を CAPI インタフェースを使いC++で書かれた Fabric Engine クライアントアプリからどのように扱うかについて説明します。

RTVal は参照によるコピー（Copy-by-Reference）¶

RTVal は C++中、 RTVal クラスのインタフェースとして表現されます。RTValはC++中では参照によるコピー（Copy-by-Reference）です。つまり、あるRTValを他のRTVal型の変数へ代入する場合、結果として2は同じRTValを指すことになります。RTValを<値によるコピー>するには、 RTVal::Construct() を呼びます。

一般的タスク¶

RTVal のコンストラクト¶

RTVal は以下のうちどれかにより作成します：

RTVal を RTVal クラスの Construct... メソッドを呼び、コンストラクト

RTVal クラスのメソッドを、既存のRTVal ――例えば構造体、オブジェクト、配列、辞書などの型―― メンバ（もしくは要素）の値を得るために呼ぶ。大抵の場合、戻りRTVal はメンバ（もしくは要素）データのコピーになります。

DGノード (もしくは他のDGContainer)のメンバの値を、 DGContainer::getMemberSliceValue() を呼び出し、得ます。

RTValのコピーをコンストラクトするには、 RTVal::Construct() メソッドを使用します。既存の RTVal を唯一の引数としてわたします。

注釈

これらの方法による RTVal のコンストラクトは、KLでのコピーコンストラクションと同じです。つまり参照渡し（pass-by-reference）では、可変長配列や辞書型は、RTValがそれらをコピーしようと、同じ通底するデータを参照したままとなります。データをコピーするのであれば、 RTVal::callMethod() を呼び出し、 clone メソッドを呼びます。

C++ で単純なRTValデータの同等物を得る¶

C++ での単純なRTValのデータに相当するものを取得するには、 RTVal クラスの get... メソッドを使います。 is.... メソッドによりその型があるか先にチェックするようにしましょう。さもないと例外が発生するかもしれません。

C++ の単純なデータの RTValへの設定¶

<メンバ、配列の要素、辞書>の値を RTVal クラスの set... メソッドを使い設定できます。

RTVal の文字列表現¶

デバッグのため、ある RTVal を人間可読な状態で得ることができると大変便利です。そのような場合 RTVal::getDesc() メソッドを使いましょう。

RTVal のメソッド呼び出し¶

RTVal::callMethod() 関数をつかい RTValのメソッドを呼びます。

配列との併用¶

ある RTVal型が配列型であれば、配列メソッドを適用できます：

RTVal::isArray()

RTVal::isVariableArray()

RTVal::getArraySize()

RTVal::getArrayElement()

RTVal::setArrayElement()

辞書との併用¶

ある RTVal型が辞書型であれば、辞書メソッドを適用できます：

RTVal::isDict()

RTVal::getDictSize()

RTVal::getDictElement()

RTVal::setDictElement()

構造体,オブジェクトとの併用¶

ある RTval型が構造体（あるいはオブジェクト）であれば、それらのメンバを使用できます：

RTVal::isStruct()

RTVal::isObject()

RTVal::maybeGetMember()

RTVal::maybeGetMemberRef()

オブジェクトの場合、 RTVal::isNullObject() をオブジェクトの参照が nullとなっていないかチェックできます。

Opaque データとの併用¶

Data 型のRTval であれば、opaque データポイントとして Core 外に渡すことができます。エクステンションに渡すなどに利用できます。

RTVal::isData()

RTVal::getData()

RTVal::setData()

Working with KL `RTVal`¶

You can use cpp RTVals of type KL RTVal to pass generic data in and out of the application.
cpp RTVals are not the cpp equivalent of a KL RTVal, there is no one to one correspondance.
Like other KL types, KL :kl-ref:`RTVal`s are contained within a cpp RTVals when accessed from C++.

Here is an example of how retrieve the wrapped value of a KL RTVal into a cpp RTVal:

//Access the KL :kl-ref:`RTVal` containing the KL data we want.
RTVal klRTVal = getRTVal(....);

//Now, get the type of the KL data wrapped in the KL :kl-ref:`RTVal`.
const char * valType = klRTVal.callMethod("String", "type", 0, 0).getStringCString();

//Then, construct a new cpp RTVal containing the KL data.
RTVal cppRTVal = RTVal::Construct(client, valType, 1, &klRTVal);

API レファレンス¶

class RTVal¶

RTVal は C++ では RTVal クラスのインスタンスとして表します。

RTVal()¶: あたらしい RTVal を作成。RTVal は C++では「参照によるコピー（copy-by-reference）」です。そのため RTVal を後で代入するため先に変数を初期化することがよくあります。

RTVal(RTVal const &that)¶: RTVal のコピーコンストラクタ。RTVal は C++では「参照によるコピー（copy-by-reference）」です。そのためこのコピーコンストラクタは、同じ RTVal that への参照を作成します。

RTVal &operator=(RTVal const &that)¶: RTVal 代入演算子。RTVal は C++では「参照によるコピー（copy-by-reference）」です。そのためこの代入演算子は、 that と同じRTVal への参照を作成します。他の RTVal からのこのRTva への参照が切れるとこのRTVal は開放されます。

static RTVal Construct(Context const &context, char const *typeNameCString, uint32_t argCount, RTVal const *argRTVals)¶

static RTVal Construct(Client const &client, char const *typeNameCString, uint32_t argCount, RTVal const *argRTVals)¶

KLのコピーコンストラクタシンタックスを使用し、あたらしい RTValをコンストラクトします。ターゲットの型と、0個以上の他の RTValのリストを取り、とったRTValのコピーコンストラクションを呼びだそうとします。

注意点として、オブジェクトの型 < typeNameCString >を特定してのこのコンストラクトメソッドの呼び出しは、nullオブジェクト参照をつくります。かわりに Create メソッドと使い、あたらしいオブジェクトインスタンスを作成します。

内部的に、これは以下の KLコードにより RTVal を作成しています。

<TypeName> resultRTVal(arg1RTVal, arg2RTVal, ...);

static RTVal ConstructBoolean(Context const &context, bool value)¶
static RTVal ConstructBoolean(Client const &client, bool value)¶: Boolean 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructSInt8(Context const &context, int8_t value)¶
static RTVal ConstructSInt8(Client const &client, int8_t value)¶: SInt8 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructSInt16(Context const &context, int16_t value)¶
static RTVal ConstructSInt16(Client const &client, int16_t value)¶: SInt16 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructSInt32(Context const &context, int32_t value)¶
static RTVal ConstructSInt32(Client const &client, int32_t value)¶: SInt32 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructSInt64(Context const &context, int64_t value)¶
static RTVal ConstructSInt64(Client const &client, int64_t value)¶: SInt64 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructUInt8(Context const &context, uint8_t value)¶
static RTVal ConstructUInt8(Client const &client, uint8_t value)¶: UInt8 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructUInt16(Context const &context, uint16_t value)¶
static RTVal ConstructUInt16(Client const &client, uint16_t value)¶: UInt16 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructUInt32(Context const &context, uint32_t value)¶
static RTVal ConstructUInt32(Client const &client, uint32_t value)¶: UInt32 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructUInt64(Context const &context, uint64_t value)¶
static RTVal ConstructUInt64(Client const &client, uint64_t value)¶: UInt64 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructFloat32(Context const &context, float value)¶
static RTVal ConstructFloat32(Client const &client, float value)¶: Float32 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructFloat64(Context const &context, double value)¶
static RTVal ConstructFloat64(Client const &client, double value)¶: Float64 型の新しい RTVal をコンストラクトします。初期値は value パラメータの値で設定します。

static RTVal ConstructString(Context const &context, char const *data, uint32_t length)¶
static RTVal ConstructString(Client const &client, char const *data, uint32_t length)¶: String 型の新しい RTVal をコンストラクトします。初期値は data と length によって与えられた文字バイト列より設定。nullバイトが含まれる可能性に注意。

static RTVal ConstructString(Context const &context, char const *cString)¶
static RTVal ConstructString(Client const &client, char const *cString)¶: String 型の新しい RTVal をコンストラクトします。初期値は cString に与えられた null終端文字列バイト（C-style）によって設定。

static RTVal ConstructData(Context const &context, void *data)¶
static RTVal ConstructData(Client const &client, void *data)¶: Data 型の新しい RTVal をコンストラクトします。初期値は data に渡すポインタによって設定。Fabric core からエクステンションに opaque データをポインタを渡すことで受け渡す一番簡単な方法です。

static RTVal ConstructFixedArray(Context const &context, char const *elementTypeCString, uint32_t size)¶
static RTVal ConstructFixedArray(Client const &client, char const *elementTypeCString, uint32_t size)¶: 決められた要素の型とサイズな固定長配列の新しい RTVal をコンストラクトします。配列要素の初期値は与えられた型のディフォルト値です。

static RTVal ConstructVariableArray(Context const &context, char const *elementTypeCString)¶
static RTVal ConstructVariableArray(Client const &client, char const *elementTypeCString)¶: 与えられた要素の型の可変長配列の新しい RTVal をコンストラクトします。初期長さは 0。（つまり空）

static RTVal ConstructExternalArray(Context const &context, char const *elementTypeCString, uint32_t size, void *data)¶
static RTVal ConstructExternalArray(Client const &client, char const *elementTypeCString, uint32_t size, void *data)¶: 与えられた型のデータを参照する外挿配列の新しい RTVal をコンストラクトします。 size and data パラメータにこの配列が参照する配列のデータをただしくポイントします。

static RTVal ConstructDict(Context const &context, char const *keyTypeCString, char const *valueTypeCString)¶
static RTVal ConstructDict(Client const &client, char const *keyTypeCString, char const *valueTypeCString)¶: 与えられた keyの型と値の型から辞書型の新しい RTVal をコンストラクトします。初期値は空です。

static RTVal Create(Context const &context, char const *typeNameCString, uint32_t argCount, RTVal const *argRTVals)¶

static RTVal Create(Client const &client, char const *typeNameCString, uint32_t argCount, RTVal const *argRTVals)¶

与えられた型の新しい KLオブジェクトを作成し、結果を新しい RTVal へ代入。 typeNameCString がオブジェクトや型でない場合、例外を投げます

オブジェクト型 typeNameCString を特定しての Construct メソッドの呼び出しは、nullオブジェクト参照を作成します。新しいオブジェクトインスタンスを作成するのであればこちらのメソッドを使用しましょう。

内部的に、これは以下の KLコードにより RTVal を作成しています。

<TypeName> resultRTVal = TypeName(arg1RTVal, arg2RTVal, ...);

bool getBoolean()¶: Boolean 型の RTVal の値を返す. RTVal が Boolean 型でない場合例外が発生.

uint8_t getUInt8()¶: UInt8 型の RTVal の値を返す. RTVal が UInt8 型でない場合例外が発生.

uint16_t getUInt16()¶: UInt16 型の RTVal の値を返す. RTVal が UInt16 型でない場合例外が発生.

uint32_t getUInt32()¶: UInt32 型の RTVal の値を返す. RTVal が UInt32 型でない場合例外が発生.

uint64_t getUInt64()¶: UInt64 型の RTVal の値を返す. RTVal が UInt64 型でない場合例外が発生.

int8_t getSInt8()¶: SInt8 型の RTVal の値を返す. RTVal が SInt8 型でない場合例外が発生.

int16_t getSInt16()¶: SInt16 型の RTVal の値を返す. RTVal が SInt16 型でない場合例外が発生.

int32_t getSInt32()¶: SInt32 型の RTVal の値を返す. RTVal が SInt32 型でない場合例外が発生.

int64_t getSInt64()¶: SInt64 型の RTVal の値を返す. RTVal が SInt64 型でない場合例外が発生.

float getFloat32()¶: Float32 型の RTVal の値を返す. RTVal が Float32 型でない場合例外が発生.

void setFloat32(float value)¶: Float32 型の RTVal の値を value に設定. RTValが Float32 型でない場合例外が発生

double getFloat64()¶: Float64 型の RTVal の値を返す. RTVal が Float64 型でない場合例外が発生.

char const *getStringCString()¶: String 型の RTVal の値を C-string として返す. RTVal が String 型でない場合例外が発生.

uint32_t getStringLength()¶: String 型の RTVal の値の文字列の長さを返す. RTVal が String 型でない場合例外が発生.

void *getData()¶: Return the value of the RTVal that is of type Data as a void pointer. If the RTVal is not of type Data an exception will be thrown.

void setData(void *data)¶: Data 型の RTVal の値を voidポインタの値 Data (struct) に設定. RTValが Data 型でない場合例外が発生

bool isNullObject() const¶: あるオブジェクトの型のRTVal の値が null かどうかを返す. RTVal がオブジェクトの型でない場合例外が発生.

bool isArray() const¶: Return whether the RTVal that is of a type that is a fixed, variable or external array of some other type. Used to check if it’s safe to perform array length and indexing calls.

bool isVariableArray() const¶: Return whether the RTVal is a variable array of some other type. Used to check if it’s safe to perform array resizing calls.

bool isDict() const¶: RTVal が辞書型かどうかを返す.

bool isStruct() const¶: RTVal が構造体型かどうかを返す.

bool isObject() const¶: RTVal がオブジェクト型かどうかを返す.

bool isData() const¶: RTVal が Data 型かどうかを返す.

bool isInterface() const¶: RTVal がインタフェース型かどうかを返す.

uint32_t getArraySize() const¶: 配列型な RTVal の長さを返す. RTVal が配列型でない場合例外が発生.

void setArraySize(uint32_t newSize)¶: 可変長配列な型の RTVal をリサイズする. RTVal が可変長配列型でない場合例外が発生.

RTVal getArrayElement(uint32_t index) const¶: 配列型の要素のコピーである新しい RTVal を返す. RTVal が配列型でない, あるいはインデックスが配列境界外である場合例外が発生.

void setArrayElement(uint32_t index, RTVal const &value)¶: 配列型の RTVal のインデックスで指定した要素を設定する. value パラメータは配列要素の型へとキャスト可能な RTVal でなければならない. RTVal が配列型でない, あるいはインデックスが配列境界外である場合例外が発生.

uint32_t getDictSize() const¶: 辞書型である RTVal のサイズ（ <キーと値> のペアの数）を取得. RTVal が辞書型でない場合例外が発生.

RTVal getDictElement(RTVal const &key) const¶: 辞書型の RTVal に含まれる与えられたキーに対応する値のコピーである新規 RTVal を返す. key は辞書型のキーの型にキャスト可能な RTVal でなければならない. RTVal が辞書型でない,あるいはキーに対応した要素が存在しない場合例外が発生.

void setDictElement(RTVal const &key, RTVal const &value)¶: 辞書型の RTVal の与えられたキーに対応する値を設定する. key は辞書のキーの型にキャスト可能な RTVal でなければならない. RTVal が辞書型でない場合例外が発生.

RTVal maybeGetMember(char const *memberNameCString) const¶: 構造体,あるいはオブジェクト型の RTVal に含まれる名前付きメンバのコピーである RTVal を新規に返す. RTVal が構造体やオブジェクト型でない場合例外が発生. memberNameCString 名のメンバが存在しない場合, null RTVal を返す.

RTVal maybeGetMemberRef(char const *memberNameCString) const¶: 構造体,あるいはオブジェクト型の RTVal に含まれる名前付きメンバの参照である RTVal を返す. RTVal が構造体あるいはオブジェクト型でない場合, あるいは memberNameCString メンバが存在しない場合例外が発生.

注釈
参照するものが構造体の生存と合わなくなることにより起こることに対しての責任は呼び出し側にあります。

void setMember(char const *memberNameCString, RTVal const &value)¶: 構造体あるいはオブジェクト型の RTVal に含まれる名前付きメンバを設定. value はメンバの型へとキャスト可能な RTVal でなければならない. RTVal が構造体あるいはオブジェクトでない場合, あるいは memberNameCString メンバが存在しない場合, 例外が発生.

RTVal callMethod(char const *resultTypeCString, char const *methodNameCString, uint32_t argCount, RTVal *argRTVals)¶

RTVal のメソッドを呼ぶ. resultTypeCString はメソッド呼び出しの結果の型でなければならない; methodNameCString は呼び出すメソッドの名前でなければならない; argCount and argRTVals は呼び出しの引数を指定する.

メソッドが値を返さないのであれば, resultTypeCString には空文字列を指定; この場合 null RTVal が返る. それ以外はメソッド呼び出しの戻り値である新規の RTVal が返る.

与えられた名前, 引数の型, 戻り値の型へとキャスト可能な型に対応したメソッドが存在しない場合, 例外が発生.

RTVal getDesc() const¶: RTVal の description を表す String 型の新規の RTVal を返す.

RTVal getTypeName() const¶: RTVal の型の名前を表す, 新規の String 型の RTVal を返す.

RTVal getJSON() const¶: JSON形式の値の description を表す新規の String 型の RTVal を返す.

注釈
全ての型で動作するわけではありません！

void setJSON(RTVal const &jsonVal)¶: getJSON メソッドで取得できる RTVal の JSON description の値を設定.

注釈
全ての型で動作するわけではありません！

class DGContainer¶

DGContainer クラスのメソッドのうち RTVal に対して機能するものがある. これらのメソッドは DGNodes の値のメンバのコピーである RTVal を得る. 以下例：

RTVal getMemberSliceValue(char const *memberCString, uint32_t index)¶: 与えられた slice のメンバデータのコピーを RTVal として返す.

void setMemberSliceValue(char const *memberCString, uint32_t index, RTVal const &rtVal)¶: 与えられた slice のメンバデータを RTVal で設定する. RTVal がメンバの型へとキャスト不可能な場合, 例外が発生.

RTVal getJSONStringValue()¶: String 型の RTval としてJSON description を得る.

void setJSONStringValue(RTVal const &stringRTVal)¶: DGContainer::getJSONStringValue() により取得する事のできる、JSON形式の RTVal 文字列によってコンテナのコンテンツを設定.

RTVals のC++アプリからの利用¶

RTVal は参照によるコピー（Copy-by-Reference）¶

一般的タスク¶

RTVal のコンストラクト¶

C++ で単純なRTValデータの同等物を得る¶

C++ の単純なデータの RTValへの設定¶

RTVal の文字列表現¶

RTVal のメソッド呼び出し¶

配列との併用¶

辞書との併用¶

構造体,オブジェクトとの併用¶

Opaque データとの併用¶

Working with KL `RTVal`¶

API レファレンス¶

目次

前のトピックへ

次のトピックへ

このページ

RTVals のC++アプリからの利用¶

RTVal は参照によるコピー（Copy-by-Reference）¶

一般的タスク¶

RTVal のコンストラクト¶

C++ で 単純なRTValデータの同等物を得る¶

C++ の単純なデータの RTValへの設定¶

RTVal の文字列表現¶

RTVal のメソッド呼び出し¶

配列との併用¶

辞書との併用¶

構造体,オブジェクトとの併用¶

Opaque データとの併用¶

Working with KL RTVal¶

API レファレンス¶

C++ で単純なRTValデータの同等物を得る¶

Working with KL `RTVal`¶