LlLinksetDataWrite/ja

関数 | イベント | 型 | 演算子 | 定数 | 実行制御 | スクリプトライブラリ | カテゴリ別スクリプトライブラリ | チュートリアル

Summary: llLinksetDataWrite, llLinksetDataWriteProtected

llLinksetDataWrite および llLinksetDataWriteProtected 関数は、linkset データストア内の name:value ペアを作成または更新します。linkset データストアは、スクリプトが削除またはリセットされても（手動リセット、llResetScript、llResetOtherScript、またはオブジェクトのクローンを介して）、プリムのプロパティとして保持される半永久的なキー値ストアです。value が空の文字列の場合、ペアは削除されます。

この関数は成功時には0を、失敗時にはエラーコードを返します。

これらの関数が呼び出されると、linkset_data イベントが linkset 内で実行されているすべてのスクリプトで LINKSETDATA_UPDATE アクションでトリガーされ、ペアが削除される場合は LINKSETDATA_DELETE アクションでトリガーされます。

linkset データストアには最大で131072バイト（128 KiB）のデータを格納でき、関数とそれとやり取りするためのイベント以外のスクリプトメモリ使用量には影響しません。データストアに書き込まれる各ペアは、name の長さと value の長さに加えて、llLinksetDataWriteProtected を使用して書き込まれる場合は追加で32バイト消費します。

Function: integer llLinksetDataWrite( string name, string value );


0	Forced Delay
10.0	Energy

データストアから保護されていない name:value ペアを作成または更新します。
Returns an integer 成功時は0、失敗時はエラーコード。

• string	name	–	データストア内の name:value ペアのキー、更新または作成するもの。
• string	value	–	name:value ペアの value。

Function: integer llLinksetDataWriteProtected( string name, string value, string pass );


0.0	Forced Delay
10.0	Energy

データストアから保護された name:value ペアを作成または更新します。データストアから name:value ペアを読み取る、書き込む、または更新する場合は、これらの関数の保護バージョンを使用し、pass で指定された文字列を同じものとする必要があります。
Returns an integer 成功時は0、失敗時はエラーコード。

• string	name	–	データストア内の name:value ペアのキー、更新または作成するもの。
• string	value	–	name:value ペアの value。
• string	pass	–	name:value ペアを保護するために使用されるパスフレーズ。

Caveats

name:value ペアを保護すると、そのサイズが pass の長さにかかわらず追加で32バイト増加します。 pass の長さ自体はデータストアの制限に含まれません。
保護された名前を書き込むと、linkset_data イベントは通常通りトリガーされますが、value パラメータは空の文字列になります。

Constant		Description
LINKSETDATA_OK	0	The name:value pair was written to the datastore.
LINKSETDATA_EMEMORY	1	A name:value pair was too large to write to the linkset datastore.
LINKSETDATA_ENOKEY	2	The name supplied to llLinksetDataWrite was empty.
LINKSETDATA_EPROTECTED	3	The name:value pair has been protected from overwrite in the linkset's datastore.
LINKSETDATA_NOTFOUND	4	The named key could not be found in the linkset's datastore when attempting to delete it.
LINKSETDATA_NOUPDATE	5	The name:value stored in the linkset was not changed by the write operation because the value stored matches the value written.

Caveats

イベントは linkset データストアが変更された場合のみトリガーされます。
- 既存の値を name:value ペアに書き換えると LINKSETDATA_NOUPDATE が返されます。
- データストアに存在しない名前に空の文字列を書き込むと LINKSETDATA_NOTFOUND が返されます。
現在、別の linkset から linkset データストアに書き込みまたは読み込む方法はありません。
データストアは linkset 全体からアクセスできますが、単独で root prim のプロパティとして機能します。したがって、プリムのリンクおよびアンリンクを行うと次の結果が生じます。
- linkset を別の linkset にリンクする場合、結合された linkset データストアには両方のデータストアのすべてのペアが含まれます。
  - いくつかのペアで name が競合する場合、結合された linkset データストアは元の linkset からのペアを保持し、新しく追加されたプリムの競合するペアは無言で破棄されます。
  - 結合された linkset データストアが131072バイトを超える場合、新しく追加されたプリムからのペアが限界まで結合された linkset データストアに追加されます。現在のところ、どの順序でペアが追加されるかは不明なため、削除されるペアを予測する方法はありません。
- linkset から子プリムをアンリンクすると、データストアは元の linkset に残り、子プリム（現在は独自の root prim）は空のデータストアを持ちます。
  - データストアがアンリンク後に書き換えるためにスクリプトにキャッシュするには、データストアが元の linkset から子プリムに移動するためのカスタムメソッドを考案する必要があるかもしれません。
- linkset から root prim をアンリンクすると、データストアは新しくアンリンクされた root prim に残り、元の linkset の残りのプリムは空のデータストアを持ちます。
value のサイズにはデータストアの合計制限以外の制限はありませんので、非常に大きな値を書き込むと他のスクリプトを linkset_data 経由でクラッシュさせる可能性があるため注意が必要です。
- スクリプトが linkset_data イベントを定義していない場合、データストアが書き込まれたときにメモリにイベントパラメータをロードしないため、スクリプトは他のスクリプトからのデータストアへの書き込みからクラッシュするべきではありません。
- これが可能なリスクである場合は、静的な pass を使用した llLinksetDataWriteProtected を考慮してください。
シミュレータのロールバックを介して復元されるオブジェクト、またはログアウト時に正しくサーバーに保存されないアタッチメント内のデータストアにデータがロールバックされる可能性があります。
- ビューアのクラッシュによりアタッチメントの状態が保存されないことがありますので、アタッチメントでこれらの関数を使用する場合はデータストアのロールバックが発生する可能性があります。

Examples

<syntaxhighlight lang="lsl2"> default {

   touch_start(integer num_detected)
   {
       llLinksetDataWrite("test-name", "See you on the other side!");
       llResetScript();
   }
   state_entry()
   {
       llOwnerSay(llLinksetDataRead("test-name")); // Should print "See you on the other side!" to the owner
   }

}

</syntaxhighlight>

Useful Snippets

Securing Against Tampering

<syntaxhighlight lang="lsl2"> // While there is no "standard" for names, it's a good idea to take some steps to prevent against other scripts accidentally overwriting your data. // Since the datastore is shared among the entire linkset, one way to avoid name conflicts is to include the prim's UUID in the data pair's name. // This example also monitors for llLinksetDataReset/unlinks and refreshes the datastore in response, which is usually good practice if you want to keep your data!

key this_uuid; string lsd_data;

default {

   state_entry()
   {
       this_uuid = llGetKey(); // Save the current key into this_uuid for checking later
       lsd_data = "bar"; // Store the data locally so it can be rewritten if the datastore gets erased for whatever reason
       llLinksetDataWrite((string)llGetKey() + "-foo", lsd_data); // Write the data
   }
   on_rez(integer start_param)
   {
       if (llGetKey() != this_uuid)
       {
           // Prim UUID has changed!
           // This should always be the case when on_rez is called, but is included here for clarity.
           llLinksetDataWrite((string)llGetKey() + "-foo", llLinksetDataRead((string)this_uuid + "-foo")); // Read the data from the last prim UUID's pair and write it into this prim UUID's pair
           // Note that you could also just write the lsd_data string instead of calling llLinksetDataRead, but this method is theoretically a little more robust if you expect other scripts to manipulate the data.
           llLinksetDataDelete((string)this_uuid + "-foo"); // Erase the original data to free up memory
           this_uuid = llGetKey(); // Update the UUID variable to the new UUID
       }
   }
   linkset_data(integer action, string name, string value)
   {
       if (action == LINKSETDATA_UPDATE

Notes

Linkset データストアの操作は同期的であり、通常は1つのサーバーフレーム内で処理されます。したがって、llMessageLinked を使わずにデータストアだけを使用して複数のスクリプト間で変数を同期させることが可能であり、また、非常に大きなデータセットで作業する必要がある特定のワークロードに対してデータストアを直接拡張メモリとして使用することもできます。

Deep Notes

Signature
function integer llLinksetDataWrite( string name, string value ); function integer llLinksetDataWriteProtected( string name, string value, string pass );

LlLinksetDataWrite/ja

Contents

Summary