OpenSimulator - User contributions [en]

Feature Proposals/Dispatcher

2014-12-21T04:31:43Z

Cmickeyb: Template copies

=Date=

Date of this proposal.

= Status (draft, in progress, done or abandoned) =

Status of the proposal. No set form as of yet, but could be draft/in progress/done/abandoned.

= Proposers =

The names of the people proposing this feature.

= Introduction =

A summary of what this feature is about.

= Proposal =

The text of the proposal.

Feature Proposals

2014-12-21T04:31:25Z

Cmickeyb: /* Present */

==Feature Proposals==
If you want to propose a feature, you should do so on the opensim-dev mailing list. If there is interest or if you plan to write the code yourself, you can create a page here. Please do not propose features in the Mantis bug tracker. Please do not propose features if you don't have a clear idea of how they would work on a technical level. Please do not propose features expecting other people to do the implementation work without convincing them first - this will not happen.

Feature proposals must be created in conjunction with a post to the opensim-dev mailing list - if they are just created here then it's possible they will not get seen by other developers.

If you're adding a proposal here, please do it with a page name of Feature_Proposals/<name of service>. For example Feature_Proposals/AutoBackup.

=== Templates ===

* [[Feature Proposal Template]] - Use this template for your document.

=== Present ===

* [[Feature Proposals/Dispatcher]]
* [[Feature Proposals/OsGetRegionSize]]
* [[Feature Proposals/Dynamic Attributes in Scene Objects]]
* [[Feature Proposals/Deduplicating Asset Service]]
* [[Feature Proposals/Improve Groups Service]]
* [[Feature Proposals/BulletSim_OpenCL]]
* [[IntegrationService]]
* [[RemoteAdmin:RemoteAdmin_Proposals]] - proposals for additional [[RemoteAdmin]] external methods.

=== Past ===

* [[Feature Proposals/Multi-Region OARs]]
* [[Feature Proposals/AutoBackup|AutoBackup]]
* [[Statistics Server]] - Proposal for a statistics server in OpenSimulator.
* [[OpenID]] - Proposal for using OpenID in OpenSimulator
* [[AssetServerProposal]] - Proposal for a distributed asset server
* [[A better SimCrossing]] - A work in progress about implementing a smooth simcrossing
* [[Creating profiles not used for login]] - RFC for alternative ways of creating profiles that will never be used for login
* [[OpenSim Profile Anchors]] - a mechanism for retaining creator information for offline item transfers
* [[Explicit Object Serialization]] - a proposal to explicitly serialize scene objects rather than using automatic .NET XML serialization
* [[Opensim: 0.5 Release Target Discussion]]
* [[Opensim: 0.6 Release Target Discussion]]
* [[Opensim: Future Release Discussion]]
* [[OpenWiredux: Taking the next step]]

[[Category:Development]]
[[Category:Proposal]]

JsonStore Module

2014-02-10T03:34:17Z

Cmickeyb:

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists or 0 if it does not. Used to test if a shared store has been created.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

<source lang="lsl">
state create
{
touch_start(integer i)
{
// Rez the object "reztest" from the current object's inventory, give it the json
// fragment "{ 'start' : 'abc" }" as a start parameter in its object store
string sparam = "{ 'start' : 'abc' }"
reqID = JsonRezAtRoot("reztest", llGetPos() + <0.0, 0.0, 5.0>, ZERO_VECTOR, llGetRot(), sparam);
}

link_message(integer sender, integer result, string objectid, key id)
{
if (sender != -1)
return;

if (id == reqID)
llOwnerSay("created object " + msg);
}
}
</source>

And the new object could have use the following code to extract the value from the object store:

<source lang="lsl">
default
{
// ---------------------------------------------
state_entry()
{
if (JsonTestStore(llGetKey()))
{
llOwnerSay("pulling start parameters from object store");
llOwnerSay("start parameters are " + JsonGetJson(llGetKey(), "."));
}
}

// ---------------------------------------------
on_rez(integer p)
{
llResetScript();
}
}
</source>

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetJson(storeID, "Hello");

llOwnerSay("Result " + res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetJson(key storeID, string path, string jsonvalue) ===

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetJson(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

* JsonList2Path
* JsonGetNodeType
* JsonGetValueType

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

=== int nodetype = JsonGetNodeType(key storeid, string path) ===

Return the type of node identified by the specified path. The following node types could be returned:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

=== int valuetype = JsonGetValueType(key storeid, string path) ===

For nodes in the store that specify values, return the type of value stored. Note that currently only string values can be set or returned through the JsonGetValue and JsonSetValue script functions. However, other values can be specified inside Json fragments in notecards or using the JsonSetJson or JsonGetJson functions.

The following value types could be returned:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:27:14Z

Cmickeyb: /* key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists or 0 if it does not. Used to test if a shared store has been created.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetJson(storeID, "Hello");

llOwnerSay("Result " + res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetJson(key storeID, string path, string jsonvalue) ===

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetJson(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

* JsonList2Path
* JsonGetNodeType
* JsonGetValueType

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

=== int nodetype = JsonGetNodeType(key storeid, string path) ===

Return the type of node identified by the specified path. The following node types could be returned:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

=== int valuetype = JsonGetValueType(key storeid, string path) ===

For nodes in the store that specify values, return the type of value stored. Note that currently only string values can be set or returned through the JsonGetValue and JsonSetValue script functions. However, other values can be specified inside Json fragments in notecards or using the JsonSetJson or JsonGetJson functions.

The following value types could be returned:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:24:10Z

Cmickeyb: /* Helper Functions */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists or 0 if it does not. Used to test if a shared store has been created.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetJson(storeID, "Hello");

llOwnerSay("Result " + res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetJson(key storeID, string path, string jsonvalue) ===

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetJson(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

* JsonList2Path
* JsonGetNodeType
* JsonGetValueType

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

=== int nodetype = JsonGetNodeType(key storeid, string path) ===

Return the type of node identified by the specified path. The following node types could be returned:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

=== int valuetype = JsonGetValueType(key storeid, string path) ===

For nodes in the store that specify values, return the type of value stored. Note that currently only string values can be set or returned through the JsonGetValue and JsonSetValue script functions. However, other values can be specified inside Json fragments in notecards or using the JsonSetJson or JsonGetJson functions.

The following value types could be returned:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:23:08Z

Cmickeyb: /* Helper Functions */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists or 0 if it does not. Used to test if a shared store has been created.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetJson(storeID, "Hello");

llOwnerSay("Result " + res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetJson(key storeID, string path, string jsonvalue) ===

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetJson(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

* JsonList2Path
* JsonGetNodeType
* JsonGetValueType

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

=== int nodetype = JsonGetNodeType(key storeid, string path) ===

Return the type of node identified by the specified path. The following node types could be returned:

=== int valuetype = JsonGetValueType(key storeid, string path) ===

For nodes in the store that specify values, return the type of value stored. Note that currently only string values can be set or returned through the JsonGetValue and JsonSetValue script functions. However, other values can be specified inside Json fragments in notecards or using the JsonSetJson or JsonGetJson functions.

The following value types could be returned:

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:16:24Z

Cmickeyb: /* integer status = JsonDestroyStore(key storeID) */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists or 0 if it does not. Used to test if a shared store has been created.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetJson(storeID, "Hello");

llOwnerSay("Result " + res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetJson(key storeID, string path, string jsonvalue) ===

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetJson(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:15:46Z

Cmickeyb: /* integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists or 0 if it does not. Used to test if a shared store has been created.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetJson(storeID, "Hello");

llOwnerSay("Result " + res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetJson(key storeID, string path, string jsonvalue) ===

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetJson(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:14:34Z

Cmickeyb: /* string jsonvalue = JsonGetValueJson(key storeID, string path) */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists or 0 if it does not. Used to test if a shared store has been created.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetJson(storeID, "Hello");

llOwnerSay("Result " + res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetValue(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:12:57Z

Cmickeyb: /* integer status = JsonTestStore(key storeID) */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists or 0 if it does not. Used to test if a shared store has been created.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetValueJson(key storeID, string path) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Return the value identified by the path. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello");

llOwnerSay("Result " + res); // res will be 'Today' (note the single quotes in the string itself).

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetValue(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:12:26Z

Cmickeyb: /* integer status = JsonDestroyStore() */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonAttachObjectStore() ===

Ensure that a store is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetValueJson(key storeID, string path) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Return the value identified by the path. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello");

llOwnerSay("Result " + res); // res will be 'Today' (note the single quotes in the string itself).

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetValue(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T03:11:35Z

Cmickeyb: /* Basic Functions */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Constants ==

The JsonStore module provides functions to interrogate the store to test for node and value types. The following constants are returned by the JsonGetNodeType function:

* JSON_NODETYPE_UNDEF - the node type is unknown or the node does not exist
* JSON_NODETYPE_OBJECT - the node is a key-accessed dictionary
* JSON_NODETYPE_ARRAY - the node is an index-accessed array
* JSON_NODETYPE_VALUE - the node is a value

And the following constants describe the value types of a JSON_NODETYPE_VALUE node:

* JSON_VALUETYPE_UNDEF - the value is unknown or the node is not a value
* JSON_VALUETYPE_BOOLEAN - the value of the node is a boolean
* JSON_VALUETYPE_INTEGER - the node has an integer value
* JSON_VALUETYPE_FLOAT - the node has a float value
* JSON_VALUEYTYPE_STRING - the node has a string value

Note that all accessors on a JsonStore currently return a string that can be cast to another value type.

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonAttachObjectStore
*JsonDestroyStore
*JsonTestStore
*JsonRezAtRoot
*JsonReadNotecard
*JsonWriteNotecard
*JsonList2Path
*JsonGetNodeType/JsonGetValueType
*JsonGetValue/JsonGetJson
*JsonSetValue/JsonSetJson
*JsonRemoveValue
*JsonGetArrayLength
*JsonTakeValue/JsonTakeJson
*JsonReadValue/JsonReadJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonDestroyStore() ===

Ensure that a JsonStore is associated with the object (create the store if it doesn't already exist). The store identifier will be the same as the object identifier in which the script is running.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonTestStore(key storeID) ===

Returns 1 if the identified store exists.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== key request = JsonRezAtRoot(string item, vector pos, vector velocity, rotation rot, string param) ===

This function is very similar to llRezAtRoot except for two differences. The first is that the string "param" is parsed as JSON and placed into a store identified by the newly created objects identifier. The second is that a link_message event is generated for each of the objects created. The integer parameter is the number of objects remaining to be created (for coalesced objects), the string parameter is the identifier of the newly created object, and the key parameter is the request identifier returned by the call to JsonRezAtRoot.

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetValueJson(key storeID, string path) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Return the value identified by the path. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello");

llOwnerSay("Result " + res); // res will be 'Today' (note the single quotes in the string itself).

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetValue(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T02:51:54Z

Cmickeyb: /* JsonStore Region Module API */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public enum JsonStoreNodeType
{
Undefined = 0,
Object = 1,
Array = 2,
Value = 3
}

public enum JsonStoreValueType
{
Undefined = 0,
Boolean = 1,
Integer = 2,
Float = 3,
String = 4,
UUID = 5
}

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);

JsonStoreNodeType GetNodeType(UUID storeID, string path);
JsonStoreValueType GetValueType(UUID storeID, string path);

bool TestStore(UUID storeID);

bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);

int GetArrayLength(UUID storeID, string path);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonDestroyStore
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonSetValue/JsonSetValueJson
*JsonReadNotecard
*JsonWriteNotecard
*JsonGetArrayLength

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetValueJson(key storeID, string path) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Return the value identified by the path. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello");

llOwnerSay("Result " + res); // res will be 'Today' (note the single quotes in the string itself).

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetValue(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T02:49:19Z

Cmickeyb: /* JsonStore Path Syntax */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

The function JsonList2Path can be used to convert a list of tokens into a JsonStore path. This is particularly useful if you want to iterate through arrays in the store.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);
bool TestStore(UUID storeID);
bool TestPath(UUID storeID, string path, bool useJson);
bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonDestroyStore
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonSetValue/JsonSetValueJson
*JsonReadNotecard
*JsonWriteNotecard
*JsonGetArrayLength

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetValueJson(key storeID, string path) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Return the value identified by the path. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello");

llOwnerSay("Result " + res); // res will be 'Today' (note the single quotes in the string itself).

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetValue(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T02:46:48Z

Cmickeyb: /* General Points */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. However, stores created by a script will be garbage collected when the script is deleted or reset. This can affect other scripts if they have access to a shared store.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetPathJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);
bool TestStore(UUID storeID);
bool TestPath(UUID storeID, string path, bool useJson);
bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonDestroyStore
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonSetValue/JsonSetValueJson
*JsonReadNotecard
*JsonWriteNotecard
*JsonGetArrayLength

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetValueJson(key storeID, string path) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Return the value identified by the path. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello");

llOwnerSay("Result " + res); // res will be 'Today' (note the single quotes in the string itself).

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetValue(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2014-02-10T02:44:51Z

Cmickeyb: /* Introduction */

= Introduction =

The JsonStore module enables scripts and region modules to share structured data. Please be aware that it is currently experimental and subject to change which may make older scripts fail to work or work slightly differently.

Nodes are currently restricted to array, object and string. If JSON is added (via JsonCreateStore(), JsonSetJson() or other such methods) that contains raw number values, then these can still be retrieved but only as strings.

= Enabling the Module =

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = true
</pre>

If you want to access JsonStore via script methods, you will also need to enable permission for MOD functions to run, if you have not done so already:
<pre>
[XEngine]
AllowMODFunctions = true
</pre>

= General Points =

* The module works by allow scripts to create their own stores for JSON data. JSON can either be written directly, read in from a notecard or added via some other means (such as a separate request to fetch data from an external server).

* Stores are referenced via a key. This key can be passed to other scripts so that they can share the same store.

* Stores are not persisted. Once the simulator is reset the data will disappear if other steps aren't taken to store it (such as within notecards).

* If you have finished with a store, you should remove it with the JsonDestroyStore() function. If this is not done then it will continue to occupy memory until the simulator is reset.

* If you want to see the whole contents of a store via script for debugging purposes, then a good way to do this is to print the serialized JsonStore with the script line

<source lang="lsl">
llOwnerSay(JsonGetValueJson(storeID, "."));
</source>

= JsonStore Path Syntax =

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

== Formal Syntax ==

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

== Examples ==

<pre>
// reference the root node, as used in calls such as JsonGetPathJson(storeId, ".")
// to serialize the whole store
"."

// reference an element
"elem"

// reference an array item
"[0]"

// reference an array item where elem is the key. This is a shortcut for elem.[0]
"elem[0]"

// reference an array item where elem is the key.
"elem.[0]"

// reference an array item where elem is the key and elem itself
// contains braces {}, brackets [] or periods .
"{elem}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo.bar}.[0]"

// this is a two token path with the identifier "foo.bar" and array reference "0"
// and foo or bar contain elements that need to be delineated.
"{foo}.{bar}.[0]"

// this is a four token path: [{foo}, {bar}, [0], {goof}]
"foo.bar[0].goof"
</pre>

= JsonStore Value Syntax =

= JsonStore Region Module API =

Methods for manipulating the region store are made accessible via the IJsonStore interface in the Interfaces directory of OpenSim.Region.Framework.dll. These methods are

<source lang="csharp">

public delegate void TakeValueCallback(string s);

public interface IJsonStoreModule
{
bool AttachObjectStore(UUID objectID);
bool CreateStore(string value, ref UUID result);
bool DestroyStore(UUID storeID);
bool TestStore(UUID storeID);
bool TestPath(UUID storeID, string path, bool useJson);
bool SetValue(UUID storeID, string path, string value, bool useJson);
bool RemoveValue(UUID storeID, string path);
bool GetValue(UUID storeID, string path, bool useJson, out string value);

void TakeValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
void ReadValue(UUID storeID, string path, bool useJson, TakeValueCallback cback);
}
</source>

'''TODO: Documentation on these methods. At this point, you will need to refer to the comparable script functions below.'''

= JsonStore Script Functions =

== Basic Functions ==

These functions allow you to manipulate stores, set get and test values and read and write JSON to notecards.

*JsonCreateStore
*JsonDestroyStore
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonSetValue/JsonSetValueJson
*JsonReadNotecard
*JsonWriteNotecard
*JsonGetArrayLength

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key 'Hello' point towards the string 'World'
// and a key 'Event' pointing to an array with two values '1, 2'
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. You should call this whenever you're finished with a JsonStore.

(In next release). Returns 1 if the operation is successful. Returns 0 if the operation was not successful or the store does not exist.

(In OpenSimulator 0.7.5). Return 1 if the operation is successful or if the store did not exit. Returns 0 if the operation was unsuccessful.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");
integer res = JsonDestroyStore(storeID);

llOwnerSay("Result " + (string)res);

JsonDestroyStore(storeID);
}
}
</source>

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
key requestID;

default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

requestID = JsonWriteNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
llOwnerSay("Notecard written");

JsonDestroyStore(storeID);
}
}
}
</source>

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

This example presumes that the prim contains the "nc1" notecard saved in the JsonWriteNotecard() example.

<source lang="lsl">
key storeID;
key requestID;

default
{
touch_start(integer n)
{
storeID = JsonCreateStore("{}");
requestID = JsonReadNotecard(storeID, "", "nc1");
}

link_message(integer sender, integer ival, string sval, key id)
{
if (sender != -1) return;

if (id == requestID)
{
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));

JsonDestroyStore(storeID);
}
}
}
</source>

=== string value = JsonGetValue(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. If the value exists then it is returned. If the value does not exist or the store does not exist then an empty string is returned.

The raw string is returned. If you want a string token that you could then use with JsonSetValueJson() then you will need to use JsonGetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello.World");

llOwnerSay("Result " + res); // res will be Today

JsonDestroyStore(storeID);
}
}
</source>

=== string jsonvalue = JsonGetValueJson(key storeID, string path) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Return the value identified by the path. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary. If the value does not exist or the store does not exist then an empty string is returned.

Please note that if the value is a string (i.e. a leaf-node), then it will be returned as a token surrounded by single quotes (') instead of as a raw string. This can then be used in JsonSetValueJson().

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : 'Today' } }");
string res = JsonGetValue(storeID, "Hello");

llOwnerSay("Result " + res); // res will be 'Today' (note the single quotes in the string itself).

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValue(key storeID, string path, string value) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonSetValue(storeID, "Pancake.Banana", "Apple");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Pancake.Banana");
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonSetValueJson(key storeID, string path, string jsonvalue) ===

'''From git master commit 61f18d1 (Fri Feb 15 00:38:07 2013), post OpenSimulator 0.7.5, this will become JsonGetJson()'''

Save the JSON at the location identified by the path in the store. Any data currently at the location will be replaced. The value given must be a JSON encoded string. If you want to specify a string leaf-node, then this must be surrounded by single quotes (').

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World'");

integer intRes = JsonSetValue(storeID, "Hello.World", "'Apple'");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Hello.World"); // returns Apple
llOwnerSay("Get result " + stringRes);

intRes = JsonSetValue(storeID, ".", "{'Event' : ['1', '2']}");
llOwnerSay("Set result " + (string)intRes);

string stringRes = JsonGetValue(storeID, "Event[0]"); // returns 1
llOwnerSay("Get result " + stringRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

(In OpenSimulator 0.7.5). Returns 1 if the value was removed or the value did not exist. Returns 0 if the store does not exist.

(In next release). Returns 1 if value was removed. Returns 0 if the path does not exist or the store does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : 'World', 'Event' : ['1', '2']}");

integer intRes = JsonRemoveValue(storeID, "Hello");
llOwnerSay("Remove result " + (string)intRes);

intRes = JsonTestPath(storeID, "Hello");
llOwnerSay("TestPath result " + (string)intRes);

JsonDestroyStore(storeID);
}
}
</source>

=== integer res = JsonGetArrayLength(key storeID, string path) ===

'''Current development code only (will be released in OpenSimulator 0.7.6).

Get the length of the array at the given path. Returns -1 if

* The path does not exist
* The node at the path is not an array
* The JsonStore for the storeID does not exist.

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : { 'World' : ['1', '2'] } }");

integer res= JsonGetArrayLength(storeID, "Hello.World");
llOwnerSay("Result " + (integer)res); // should be 2

JsonDestroyStore(storeID);
}
}
</source>

== Helper Functions ==

These are functions to help with manipulating JSON or using the store.

Currently there is only one helper function

* JsonList2Path

=== string path = JsonList2Path(list components) ===

Convert the given list of components to a path. Components can be strings or integers. Strings are used as ordinary path name components. Integers are used as index components to arrays.

This method exists chiefly to make it easier to iterate through arrays. For example

<source lang="lsl">
default
{
touch_start(integer n)
{
key storeID = JsonCreateStore("{'Hello' : {'World' : [{'name' : 'pete'}, {'name' : 'tom'}, {'name' : 'wilma'}]}}");

integer i;
string path;
string name;
for (i = 0; i < JsonGetArrayLength(storeID, "Hello.World"); i++)
{
path = JsonList2Path(["Hello.World", i, "name"]);
name = JsonGetValue(storeID, path);
llOwnerSay(path + " is '" + name + "'");
}

JsonDestroyStore(storeID);
}
}
</source>

== Advanced Functions ==

These are functions that allow scripts to receive notifications of values when they become available. This is useful for signalling between scripts or between scripts and region modules.

*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson

=== key requestID = JsonTakeValue(key storeID, string path) key requestID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key requestID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

= Examples =

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

Appearance Troubleshooting

2013-04-22T19:58:03Z

Cmickeyb: /* Establishing avatar appearance on login */

= Introduction =

Avatar appearance is a particularly complex issue in current OpenSimulator since it involves a complex interaction between a user's viewer (where the texture is actually created) and the simulator (which needs to send appearance information to the viewer, receive the baked textures and distribute those to other viewers). Moreover, the exact steps of this interaction vary depending on whether the user is freshly logging in or region crossing/teleporting to another region on the same or a different simulator.

This document currently describes only the classic viewer-side texture baking. Server-side baking would do most if not all of these steps (especially the baking itself) in OpenSimulator instead. However, this is not yet implemented by OpenSimulator.

= Steps =

== Establishing avatar appearance on login ==

Making an avatar appearance available in a simulator on login currently involves a large number of steps.

# On login, the viewer asks the simulator what body parts and clothing it is wearing (AgentWearablesRequest UDP packet)
# The simulator replies (AgentWearablesUpdate UDP packet).
# The viewer confirms some appearance information to the server (AgentSetAppearance UDP packets). This includes visual parameters (nose length, etc.).
# The viewer asks the simulator if its appearance is already cached (AgentCachedTexture UDP packet).
# The simulator currently always responds that no data is cached (AgentCachedTextureResponse UDP packet).
# The viewer sends further appearance information the server detailing the baked texture UUIDs it is about to upload (AgentSetAppearance UDP packets).
# The viewer creates the appearance textures from the wearables (bakes them).
# The viewer uploads these new baked textures to the simulator via the UploadBakedTexture HTTP capability.
# The simulator stores this asset data in the simulator cache but does not send it to the asset service.
# The simulator tells other viewers that can see that avatar (either because they are in the same region or neighbouring regions) about the UUIDs of the baked textures uploaded for that avatar (AvatarAppearance UDP packets).
# These other viewers then request the baked textures for these UUIDs.
# When a viewer has received all the baked textures for such an avatar, then it is displayed instead of remaining as a cloud.



As you can imagine there are many points at which this process can go wrong on, in the simulator, the sending viewer, the receiving viewer and at the network in between. If it does go wrong, you will often end up with a gas cloud instead of an avatar. The text below lists the various ways in which avatar appearance can go wrong, diagnosis commands and some suggestions for trying to fix the situation.

NOTE: The PersistBakeTextures flag in the Appearance section of the ini file allows you to persist baked textures among simulators and over login sessions. On establishment of a scene presence (through login or teleport) the simulator checks the asset service for copies of the baked textures and sends that information to the viewer. On login, this means that textures are not rebaked. While this behavior can lead to a large number of baked textures in the asset service, the only time textures will be re-baked is when 1) the user explicit requests it, 2) the set of wearables changes, or 3) the connection to the asset service is broken. There are some timing issues that come into play as well, though these will simply trigger an unnecessary rebake.

== Establishing avatar appearance on teleport/region cross to another region on the same simulator ==

In this case, the baked textures are already in the simulator's asset cache. Hence, the steps are

# The simulator tells both the uploading viewer and the other viewers that can see that avatar (either because they are in the same region or neighbouring regions) about the UUIDs of the baked textures it already has for that avatar.
# These other viewers then request the baked textures for these UUIDs if they don't already have them cached.
# When a viewer has received all the baked textures for such an avatar, then it is displayed instead of remaining as a cloud.

== Establishing avatar appearance on region cross to another region on a different simulator ==
'''Todo: Need to fill out this section. This should be the same as for teleport, but in current git master (as of 2012-02-21) there may be an issue where the avatar does not send AgentSetAppearance on entering the new region, which means that the rebake request is never triggered.'''

== Establishing avatar appearance on teleport to another region on a different simulator ==
# On completing the teleport, the viewer sends an visual parameters and the UUIDs of the baked textures it previously uploaded to the server (via the AgentSetAppearance UDP packet).
# Because these textures are not in the asset service (see earlier), OpenSimulator sends a rebake request for each texture (RebakeAvatarTextures UDP packet).
# The simulator tells other viewers that can see that avatar (either because they are in the same region or neighbouring regions) about the UUIDs of the baked textures uploaded for that avatar (AvatarAppearance UDP packets).
# These other viewers then request the baked textures for these UUIDs.
# When a viewer has received all the baked textures for such an avatar, then it is displayed instead of remaining as a cloud.

= Useful commands =

These commands are in OpenSimulator 0.7.4 and later and some will be in 0.7.3.1 and 0.7.3.

== appearance show ==

Usage

appearance show [<first-name> <last-name>]

e.g.

appearance show Lord Lucan

This will show the asset UUID for each baked texture uploaded by the viewer for that user. For instance, a properly baked user may have something like

<pre>
(test one)# appearance show Lord Lucan
For Lord Lucan in test one
Bake Type UUID
Head fd783d4a-b1d2-4bdc-89c7-88578b429ccc (uploaded)
UpperBody d147b1f5-b99d-49d4-8492-6cd4c7da905e (uploaded)
LowerBody e8aae819-e04b-4894-983a-15bd2d354b71 (uploaded)
Eyes ae8fe60d-9d20-440d-989a-869d2ee1ed3d (uploaded)
Skirt not set
Hair 4e354649-f880-4204-987a-8d744f531469 (uploaded)
Lord Lucan baked appearance texture is OK
</pre>

The textures may be listed as (not found) if they have been uploaded by the viewer but can't be found in the asset cache. Or they may be listed as (not set) if the viewer has never uploaded this data.

If no name is given then summary data for all users is displayed.

== appearance send ==

Usage

appearance send [<first-name> <last-name>]

e.g.

appearance send Lord Lucan

Send appearance baked texture IDs to other avatars in the scene. In theory, this should trigger other avatars to request those textures if they need them. This will have no effect if the original viewer never uploaded the texture IDs in the first place (i.e. if avatars are appearing as clouds). If avatars are grey instead, then this command may help. There is also a ResendAppearanceUpdates config which can periodically resend this data. We will discuss this later on.

If no name is given then all avatars resend their appearance texture UUIDs to all other avatars.

== appearance rebake ==

Usage

appearance rebake <first-name> <last-name>

e.g.

appearance rebake Lord Lucan

Now, this sounds like it should be an enormously useful command. Unfortunately, it will only have any effect if the viewer has already successfully uploaded some baked texture data, even if that turned out to be corrupt. The viewer will very probably ignore any requests to rebake textures if it has not managed to perform an initial successful bake.

== j2k decode ==

Usage

j2k decode <id>

e.g.

j2k decode ae8fe60d-9d20-440d-989a-869d2ee1ed3d

Attempt a JPEG2000 decode of the given asset. All baked textures are JPEG2000 files, so this can be useful to assess whether a given upload is corrupt or not. If the decode succeeds then it will tell you how many the number of layers and components in the JPEG2000 texture.

== dump asset ==

Usage

dump asset <id>

e.g.

dump asset ae8fe60d-9d20-440d-989a-869d2ee1ed3d

Dumps an asset to a file with the same name as the ID given. Can be useful for taking a closer look at textures in an external program (e.g. jiv on Linux) if they have been apparently successfully uploaded.

= Problems and resolutions =

== General ==

* In all these situations, one can force the client to attempt a rebake using the ctrl+alt+r key combination. This is always worth trying.
* Remember, it's possible that the viewer has successfully baked but for some reason the upload of the textures to the simulator has failed, or the simulator has failed to redistribute them to other viewers. In this case, a viewer rebake may work.
* Another general tip is to try clearing the viewer cache and logging back in.
* One should also try a different viewer, either an old viewer such as Imprudence or a newer viewer such as Kokua or Firestorm. Different viewers may have different ways of baking textures or may have issues with bugs.
* If possible, one should also try a different simulator. Even if simulators are running exactly the same version of OpenSimulator, they can be running on a different software stack (e.g. Mono rather than Windows .NET) or different hardware. There may be differences in behaviour that stem from this.
* Try a quiet region. Regions with a lot of avatars and objects may be dealing with a lot of traffic that may cause appearance issues. To test this, you could go to a quieter region or ideally even a local installation of OpenSimulator.
* If you use the same name in the same viewer for multiple different grids, try using a different installation of the viewer instead. On some viewers, it may be possible to get confused between different inventories on different grids where the avatar has the same name. This is especially true in the case of viewers which were not explicitly written to access different grids (though historically the Linden viewer seems to have been okay in this respect).

'''This is probably only a small selection of issues. Please add more as you encounter them if you know of workarounds or fixes.'''

== Cloudy avatars ==

=== The avatar does not have sufficient clothing or body-parts to bake textures ===

There is a minimum set of body parts and clothing a viewer requires to bake an appearance texture. There are the shape, hair, skin and eyes body parts, and the shirt and trousers clothing. Without these, the viewer will never attempt to bake a texture.

==== Solution ====

Make sure your avatar has this minimum set of body parts and clothing.

=== One of the assets for a bodypart/clothing is corrupt or missing ===

Sometimes the necessary data to perform the bake may be corrupt or missing.

==== Solution ====

Try switching to a different set of clothing and body parts (e.g. using the "replace outfit" option), or create the minimum set from scratch and see if wearing these helps.

=== The required clothing or bodypart inventory has not downloaded ===

Sometimes the required clothing or bodypart items for your appearance may not have downloaded, especially on a busy sim where you have a very large inventory and a viewer that aggressively requests inventory data.

==== Solutions ====

* Try a quieter region. As above, these have less traffic that may crowd out your appearance information (this is a diagnostic test rather than a long term solution).
* You may also want to try a viewer which is less aggressive about downloading all inventory information on login.
* Try turning off or on HTTP inventory if your viewer supports this option. Newer viewers (version 2, 3 and associated third party viewers) download inventory information using HTTP inventory capabilities rather than via UDP. In principle, this should result in a much better experience since large inventories do not crowd out other UDP messages (avatar movement, object updates, etc.). However, it may be worth changing this setting to see if it helps.

=== The viewer graphics code is failing to successfully bake textures ===

We've seen some graphics drivers fail to successfully bake textures. Sometimes this depends on where the baking is done (e.g. if the viewer is on a second screen).

==== Solution ====

Update your graphics drivers. Attempt a bake with a simple set of body parts/clothing and on your main screen.

=== An external OpenSimulator configuration system is not fully creating the necessary bodypart/clothing entries ===

This can be a problem with older configuration systems which are not viewer 2 aware, where it was enough to create inventory and avatar entries but item links in the "Current Outfit" folder are necessary. One would only expect to see this with initial avatar setup.

==== Solution ====

Try an avatar created using the "create user" ROBUST or simulator console command (if running in standalone mode). On OpenSimulator 0.7.4 this will by default create the minimum clothing and inventory links to display an avatar. On OpenSimulator 0.7.3.1 you will need to set CreateDefaultAvatarEntries = true in the [UserAccountService] section of Robust.ini or Robust.HG.ini (it is still set true by default on standalone).

== Grey avatars ==

Sometimes avatars may appear grey rather than cloudy.

=== The message containing appearance information has been lost ===

For some reason, the packet containing appearance information is sometimes ignored by the viewer. The "appearance send" command above may help diagnose this.

==== Solution ====

Try setting ResendAppearanceUpdates = true setting in the [Appearance] section of OpenSim.ini. This will resend appearance data every 60 seconds. This will probably not help if avatars are clouds, since this usually signals a failure to upload the data in the first place.

In OpenSimulator 0.7.4 this setting is not on by default (it is not present in OpenSimulator 0.7.3.1 and before). In OpenSimulator 0.7.5 it will be on by default.

JsonStore Module

2013-01-30T17:31:06Z

Cmickeyb: /* Examples */

== Introduction ==

The JsonStore module enables scripts and region modules to share structured data among themselves.

== Enabling the Module ==

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = True
</pre>

== JsonStore Path Syntax ==

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

=== Formal Syntax ===

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

=== Examples ===

<pre>
"elem"
"[0]"
"elem[0]"
"elem.[0]"
"{elem}.[0]"
"{foo.bar}.[0]" // this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo}.{bar}.[0]"
"foo.bar[0].goof" // this is a four token path: [{foo}, {bar}, [0], {goof}]
</pre>

== JsonStore Value Syntax ==

== JsonStore Script Functions ==

*JsonCreateStore
*JsonDestroyStore
*JsonReadNotecard
*JsonWriteNotecard
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson
*JsonSetValue/JsonSetValueJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key pointing to an array with two values
storeID = JsonCreateStore("{'Event' : ['1', '2']}");
</source>

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. Return 1 if the operation is successful.

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonReadNotecard(storeID,"Event[0]",notecardID);
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));
}
}
</source>

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== int status = JsonTestPath(key storeID, string path) int status = JsonTestPathJson(key storeID, string path) ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

=== string value = JsonGetValue(key storeID, string path) string jsonvalue = JsonGetValueJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary.

=== key requestID = JsonTakeValue(key storeID, string path) key reqeustID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key reqeustID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

=== int status = JsonSetValue(key storeID, string path, string value) int status = JsonSetValue(key storeID, string path, string jsonvalue) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string. JsonSetValueJson() assumes that the value is a Json encoded string.

=== int status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

== Examples ==

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2013-01-30T17:28:09Z

Cmickeyb: /* JsonStore Path Syntax */

== Introduction ==

The JsonStore module enables scripts and region modules to share structured data among themselves.

== Enabling the Module ==

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = True
</pre>

== JsonStore Path Syntax ==

A JsonStore path is a '.' separated string of tokens that reference elements of the Json store. Path tokens are either strings (for structure access) or array references. The '+' token refers to the end of the array and is used to append values to an array. Strings are quoted with "{" and "}" characters. Array references are quoted with "[" and "]". When there is no ambiguity, the '.' separator can be dropped.

=== Formal Syntax ===

<pre>
Path --> Token | Path '.' Token
Token --> '[' Index ']' | '{' Identifier '}' | SimpleIdentifier
Index --> '+' | [0-9]+
Identifier --> [^}]+
SimpleIdentifier --> [a-zA-Z]+
</pre>

=== Examples ===

<pre>
"elem"
"[0]"
"elem[0]"
"elem.[0]"
"{elem}.[0]"
"{foo.bar}.[0]" -- this is a two token path with the identifier "foo.bar" and array reference "0"
"{foo}.{bar}.[0]"
"foo.bar[0].goof"
</pre>

== JsonStore Value Syntax ==

== JsonStore Script Functions ==

*JsonCreateStore
*JsonDestroyStore
*JsonReadNotecard
*JsonWriteNotecard
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson
*JsonSetValue/JsonSetValueJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key pointing to an array with two values
storeID = JsonCreateStore("{'Event' : ['1', '2']}");
</source>

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. Return 1 if the operation is successful.

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonReadNotecard(storeID,"Event[0]",notecardID);
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));
}
}
</source>

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== int status = JsonTestPath(key storeID, string path) int status = JsonTestPathJson(key storeID, string path) ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

=== string value = JsonGetValue(key storeID, string path) string jsonvalue = JsonGetValueJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary.

=== key requestID = JsonTakeValue(key storeID, string path) key reqeustID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key reqeustID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

=== int status = JsonSetValue(key storeID, string path, string value) int status = JsonSetValue(key storeID, string path, string jsonvalue) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string. JsonSetValueJson() assumes that the value is a Json encoded string.

=== int status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

== Examples ==

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

OSSL Script Library/ModInvoke

2012-08-06T16:24:54Z

Cmickeyb: Adding constants example

== Introduction ==

You can invoke functions defined in a region module from a script using the modInvoke() family of functions.

This functionality current only exists in OpenSimulator development code (0.7.4-dev).

== Enabling modInvoke() ==

The first thing is to enable modSendCommand() in OpenSim.ini. Make sure the line

<pre>
AllowMODFunctions = true
</pre>

is set to true and uncommented.

== The Region Module ==

Here's the region module that implements several functions to be provided to scripts in the region.

<source lang = "csharp">
using Mono.Addins;

using System;
using System.Reflection;
using System.Threading;
using System.Text;
using System.Net;
using System.Net.Sockets;
using log4net;
using Nini.Config;
using OpenMetaverse;
using OpenMetaverse.StructuredData;
using OpenSim.Framework;
using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes;
using System.Collections.Generic;
using System.Text.RegularExpressions;

[assembly: Addin("ModInvokeTest", "0.1")]
[assembly: AddinDependency("OpenSim", "0.5")]

namespace ModInvokeTest
{
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule")]

public class ModInvokeTestModule : INonSharedRegionModule
{
private static readonly ILog m_log =
LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);

private IConfig m_config = null;
private bool m_enabled = true;
private Scene m_scene = null;

private IScriptModuleComms m_comms;

#region IRegionModule Members

public string Name
{
get { return this.GetType().Name; }
}

public void Initialise(IConfigSource config)
{
m_log.WarnFormat("[ModInvoke] start configuration");

try
{
if ((m_config = config.Configs["ModInvoke"]) != null)
m_enabled = m_config.GetBoolean("Enabled", m_enabled);
}
catch (Exception e)
{
m_log.ErrorFormat("[ModInvoke] initialization error: {0}",e.Message);
return;
}

m_log.ErrorFormat("[ModInvoke] module {0} enabled",(m_enabled ? "is" : "is not"));
}

public void PostInitialise()
{
if (m_enabled) {}
}

public void Close() { }
public void AddRegion(Scene scene) { }
public void RemoveRegion(Scene scene) { }

public void RegionLoaded(Scene scene)
{
if (m_enabled)
{
m_scene = scene;
m_comms = m_scene.RequestModuleInterface<IScriptModuleComms>();
if (m_comms == null)
{
m_log.WarnFormat("[ModInvoke] ScriptModuleComms interface not defined");
m_enabled = false;

return;
}

m_comms.RegisterScriptInvocation(this,"ModTest0");
m_comms.RegisterScriptInvocation(this,"ModTest1");
m_comms.RegisterScriptInvocation(this,"ModTest2");
m_comms.RegisterScriptInvocation(this,"ModTest3");
m_comms.RegisterScriptInvocation(this,"ModTest4");
m_comms.RegisterScriptInvocation(this,"ModTest5");
m_comms.RegisterScriptInvocation(this,"ModTest6");
m_comms.RegisterScriptInvocation(this,"ModTest7");
m_comms.RegisterScriptInvocation(this,"ModTest8");

// Register some constants as well
m_comms.RegisterConstant("ModConstantInt1",25);
m_comms.RegisterConstant("ModConstantFloat1",25.000f);
m_comms.RegisterConstant("ModConstantString1","abcdefg");
}
}

public Type ReplaceableInterface
{
get { return null; }
}

#endregion

#region ScriptInvocationInteface
public string ModTest0(UUID hostID, UUID scriptID)
{
m_log.WarnFormat("[ModInvoke] ModTest0 parameter");
return "";
}

public string ModTest1(UUID hostID, UUID scriptID, string value)
{
m_log.WarnFormat("[ModInvoke] ModTest1 parameter: {0}",value);
return value;
}

public int ModTest2(UUID hostID, UUID scriptID, int value)
{
m_log.WarnFormat("[ModInvoke] ModTest2 parameter: {0}",value);
return value;
}

public float ModTest3(UUID hostID, UUID scriptID, float value)
{
m_log.WarnFormat("[ModInvoke] ModTest3 parameter: {0}",value);
return value;
}

public UUID ModTest4(UUID hostID, UUID scriptID, UUID value)
{
m_log.WarnFormat("[ModInvoke] ModTest4 parameter: {0}",value.ToString());
return value;
}

public OpenMetaverse.Vector3 ModTest5(UUID hostID, UUID scriptID, OpenMetaverse.Vector3 value)
{
m_log.WarnFormat("[ModInvoke] ModTest5 parameter: {0}",value.ToString());
return value;
}

public OpenMetaverse.Quaternion ModTest6(UUID hostID, UUID scriptID, OpenMetaverse.Quaternion value)
{
m_log.WarnFormat("[ModInvoke] ModTest6 parameter: {0}",value.ToString());
return value;
}

public object[] ModTest7(UUID hostID, UUID scriptID, int count, string val)
{
object[] result = new object[count];
for (int i = 0; i < count; i++)
result[i] = val;

return result;
}

public object[] ModTest8(UUID hostID, UUID scriptID, object[] lparm)
{
object[] result = new object[lparm.Length];

for (int i = 0; i < lparm.Length; i++)
result[lparm.Length - i - 1] = lparm[i];

return result;
}

#endregion
}
}
</source>

The module registers functions through the IScriptModuleComms RegisterScriptInvocation() method. This method takes the name of the function, an invocation delegate, an array of types used to validate parameters to the function, and a return type.

The functions in the region module can assume that the parameters passed through the argument array match the signature that was registered. That is, the function in the region module does not need to perform any kind of type checking.

== The In-world Script ==

Here's the in-world script that calls the functions defined in the region module.

<source lang="lsl">
default
{
state_entry()
{
llSay(0, "Script running");
llOwnerSay("ModTest0: " + ModTest0());
llOwnerSay("ModTest1: " + ModTest1("one"));

integer v2 = ModTest2(2) + 2;
llOwnerSay("ModTest2: " + (string)v2);

float v3 = ModTest3(3.14) + 4.56;
llOwnerSay("ModTest3: " + (string)v3);

key v4 = ModTest4(llGetKey());
llOwnerSay("ModTest4: " + (string)v4);

vector v5 = ModTest5(llGetPos());
llOwnerSay("ModTest5: " + (string)v5);

rotation v6 = ModTest6(llGetRot());
llOwnerSay("ModTest6: " + (string)v6);

list v7 = ModTest7(5,"hello");
llOwnerSay("ModTest7: " + (string)llGetListLength(v7));
llOwnerSay("ModTest7: " + llList2CSV(v7));

list v8 = ["a", 1, llGetKey(), llGetPos(), llGetRot()];
list v9 = ModTest8(v8);
llOwnerSay("ModTest8: " + (string)llGetListLength(v9));
llOwnerSay("ModTest8: " + llList2CSV(v9));

}
}
</source>

== Notes ==

One thing to note regarding parameter and return types: the LSL_Types are not available in the region module; however, all of the OpenMetaverse types are. Use UUID for a key and string, int, OpenMetaverse.Vector3, etc for other types.

[[Category:Scripts]]

OSSL Script Library/ModInvoke

2012-07-17T16:13:43Z

Cmickeyb:

== Introduction ==

You can invoke functions defined in a region module from a script using the modInvoke() family of functions.

This functionality current only exists in OpenSimulator development code (0.7.4-dev).

== Enabling modInvoke() ==

The first thing is to enable modSendCommand() in OpenSim.ini. Make sure the line

<pre>
AllowMODFunctions = true
</pre>

is set to true and uncommented.

== The Region Module ==

Here's the region module that implements several functions to be provided to scripts in the region.

<source lang = "csharp">
using Mono.Addins;

using System;
using System.Reflection;
using System.Threading;
using System.Text;
using System.Net;
using System.Net.Sockets;
using log4net;
using Nini.Config;
using OpenMetaverse;
using OpenMetaverse.StructuredData;
using OpenSim.Framework;
using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes;
using System.Collections.Generic;
using System.Text.RegularExpressions;

[assembly: Addin("ModInvokeTest", "0.1")]
[assembly: AddinDependency("OpenSim", "0.5")]

namespace ModInvokeTest
{
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule")]

public class ModInvokeTestModule : INonSharedRegionModule
{
private static readonly ILog m_log =
LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);

private IConfig m_config = null;
private bool m_enabled = true;
private Scene m_scene = null;

private IScriptModuleComms m_comms;

#region IRegionModule Members

public string Name
{
get { return this.GetType().Name; }
}

public void Initialise(IConfigSource config)
{
m_log.WarnFormat("[ModInvoke] start configuration");

try
{
if ((m_config = config.Configs["ModInvoke"]) != null)
m_enabled = m_config.GetBoolean("Enabled", m_enabled);
}
catch (Exception e)
{
m_log.ErrorFormat("[ModInvoke] initialization error: {0}",e.Message);
return;
}

m_log.ErrorFormat("[ModInvoke] module {0} enabled",(m_enabled ? "is" : "is not"));
}

public void PostInitialise()
{
if (m_enabled) {}
}

public void Close() { }
public void AddRegion(Scene scene) { }
public void RemoveRegion(Scene scene) { }

public void RegionLoaded(Scene scene)
{
if (m_enabled)
{
m_scene = scene;
m_comms = m_scene.RequestModuleInterface<IScriptModuleComms>();
if (m_comms == null)
{
m_log.WarnFormat("[ModInvoke] ScriptModuleComms interface not defined");
m_enabled = false;

return;
}

m_comms.RegisterScriptInvocation(this,"ModTest0");
m_comms.RegisterScriptInvocation(this,"ModTest1");
m_comms.RegisterScriptInvocation(this,"ModTest2");
m_comms.RegisterScriptInvocation(this,"ModTest3");
m_comms.RegisterScriptInvocation(this,"ModTest4");
m_comms.RegisterScriptInvocation(this,"ModTest5");
m_comms.RegisterScriptInvocation(this,"ModTest6");
m_comms.RegisterScriptInvocation(this,"ModTest7");
m_comms.RegisterScriptInvocation(this,"ModTest8");
}
}

public Type ReplaceableInterface
{
get { return null; }
}

#endregion

#region ScriptInvocationInteface
public string ModTest0(UUID hostID, UUID scriptID)
{
m_log.WarnFormat("[ModInvoke] ModTest0 parameter");
return "";
}

public string ModTest1(UUID hostID, UUID scriptID, string value)
{
m_log.WarnFormat("[ModInvoke] ModTest1 parameter: {0}",value);
return value;
}

public int ModTest2(UUID hostID, UUID scriptID, int value)
{
m_log.WarnFormat("[ModInvoke] ModTest2 parameter: {0}",value);
return value;
}

public float ModTest3(UUID hostID, UUID scriptID, float value)
{
m_log.WarnFormat("[ModInvoke] ModTest3 parameter: {0}",value);
return value;
}

public UUID ModTest4(UUID hostID, UUID scriptID, UUID value)
{
m_log.WarnFormat("[ModInvoke] ModTest4 parameter: {0}",value.ToString());
return value;
}

public OpenMetaverse.Vector3 ModTest5(UUID hostID, UUID scriptID, OpenMetaverse.Vector3 value)
{
m_log.WarnFormat("[ModInvoke] ModTest5 parameter: {0}",value.ToString());
return value;
}

public OpenMetaverse.Quaternion ModTest6(UUID hostID, UUID scriptID, OpenMetaverse.Quaternion value)
{
m_log.WarnFormat("[ModInvoke] ModTest6 parameter: {0}",value.ToString());
return value;
}

public object[] ModTest7(UUID hostID, UUID scriptID, int count, string val)
{
object[] result = new object[count];
for (int i = 0; i < count; i++)
result[i] = val;

return result;
}

public object[] ModTest8(UUID hostID, UUID scriptID, object[] lparm)
{
object[] result = new object[lparm.Length];

for (int i = 0; i < lparm.Length; i++)
result[lparm.Length - i - 1] = lparm[i];

return result;
}

#endregion
}
}
</source>

The module registers functions through the IScriptModuleComms RegisterScriptInvocation() method. This method takes the name of the function, an invocation delegate, an array of types used to validate parameters to the function, and a return type.

The functions in the region module can assume that the parameters passed through the argument array match the signature that was registered. That is, the function in the region module does not need to perform any kind of type checking.

== The In-world Script ==

Here's the in-world script that calls the functions defined in the region module.

<source lang="lsl">
default
{
state_entry()
{
llSay(0, "Script running");
llOwnerSay("ModTest0: " + ModTest0());
llOwnerSay("ModTest1: " + ModTest1("one"));

integer v2 = ModTest2(2) + 2;
llOwnerSay("ModTest2: " + (string)v2);

float v3 = ModTest3(3.14) + 4.56;
llOwnerSay("ModTest3: " + (string)v3);

key v4 = ModTest4(llGetKey());
llOwnerSay("ModTest4: " + (string)v4);

vector v5 = ModTest5(llGetPos());
llOwnerSay("ModTest5: " + (string)v5);

rotation v6 = ModTest6(llGetRot());
llOwnerSay("ModTest6: " + (string)v6);

list v7 = ModTest7(5,"hello");
llOwnerSay("ModTest7: " + (string)llGetListLength(v7));
llOwnerSay("ModTest7: " + llList2CSV(v7));

list v8 = ["a", 1, llGetKey(), llGetPos(), llGetRot()];
list v9 = ModTest8(v8);
llOwnerSay("ModTest8: " + (string)llGetListLength(v9));
llOwnerSay("ModTest8: " + llList2CSV(v9));

}
}
</source>

== Notes ==

One thing to note regarding parameter and return types: the LSL_Types are not available in the region module; however, all of the OpenMetaverse types are. Use UUID for a key and string, int, OpenMetaverse.Vector3, etc for other types.

[[Category:Scripts]]

JsonStore Module

2012-04-17T23:43:54Z

Cmickeyb:

== Introduction ==

The JsonStore module enables scripts and region modules to share structured data among themselves.

== Enabling the Module ==

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = True
</pre>

== JsonStore Path Syntax ==

== JsonStore Value Syntax ==

== JsonStore Script Functions ==

*JsonCreateStore
*JsonDestroyStore
*JsonReadNotecard
*JsonWriteNotecard
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson
*JsonSetValue/JsonSetValueJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

<source lang="lsl">
// Create a JsonStore initialized with a key pointing to an array with two values
storeID = JsonCreateStore("{'Event' : ['1', '2']}");
</source>

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. Return 1 if the operation is successful.

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonReadNotecard(storeID,"Event[0]",notecardID);
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
llOwnerSay("notecard read: " + JsonGetValueJson(storeID,"Event[0]"));
}
}
</source>

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== int status = JsonTestPath(key storeID, string path) int status = JsonTestPathJson(key storeID, string path) ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

=== string value = JsonGetValue(key storeID, string path) string jsonvalue = JsonGetValueJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary.

=== key requestID = JsonTakeValue(key storeID, string path) key reqeustID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

<source lang="lsl">
default
{
state_entry()
{
key requestID = JsonTakeValue(storeID,"Event.Lock");
}

link_message(integer sender, integer ival, integer sval, key id)
{
if (sender != -1) return;
if (id == requestID)
{
// we now have a "lock"
llOwnerSay("read: " + sval);

// release the "lock" by placing the value back in the store
llSetValue(storeID,"Event.Lock",sval);
}
}
}
</source>

=== key requestID = JsonReadValue(key storeID, string path) key reqeustID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

=== int status = JsonSetValue(key storeID, string path, string value) int status = JsonSetValue(key storeID, string path, string jsonvalue) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string. JsonSetValueJson() assumes that the value is a Json encoded string.

=== int status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

== Examples ==

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2012-04-17T23:26:23Z

Cmickeyb: /* key requestID = JsonReadValue(key storeID, string path)key reqeustID = JsonReadValueJson(key storeID, string path) */

== Introduction ==

The JsonStore module enables scripts and region modules to share structured data among themselves.

== Enabling the Module ==

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = True
</pre>

== JsonStore Path Syntax ==

== JsonStore Value Syntax ==

== JsonStore Script Functions ==

*JsonCreateStore
*JsonDestroyStore
*JsonReadNotecard
*JsonWriteNotecard
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson
*JsonSetValue/JsonSetValueJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. Return 1 if the operation is successful.

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== int status = JsonTestPath(key storeID, string path) int status = JsonTestPathJson(key storeID, string path) ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

=== string value = JsonGetValue(key storeID, string path) string jsonvalue = JsonGetValueJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary.

=== key requestID = JsonTakeValue(key storeID, string path) key reqeustID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

=== key requestID = JsonReadValue(key storeID, string path) key reqeustID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

=== int status = JsonSetValue(key storeID, string path, string value) int status = JsonSetValue(key storeID, string path, string jsonvalue) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string. JsonSetValueJson() assumes that the value is a Json encoded string.

=== int status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

== Examples ==

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2012-04-17T23:25:57Z

Cmickeyb: /* key requestID = JsonReadValue(key storeID, string path)key reqeustID = JsonReadValueJson(key storeID, string path) */

== Introduction ==

The JsonStore module enables scripts and region modules to share structured data among themselves.

== Enabling the Module ==

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = True
</pre>

== JsonStore Path Syntax ==

== JsonStore Value Syntax ==

== JsonStore Script Functions ==

*JsonCreateStore
*JsonDestroyStore
*JsonReadNotecard
*JsonWriteNotecard
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson
*JsonSetValue/JsonSetValueJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. Return 1 if the operation is successful.

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== int status = JsonTestPath(key storeID, string path) int status = JsonTestPathJson(key storeID, string path) ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

=== string value = JsonGetValue(key storeID, string path) string jsonvalue = JsonGetValueJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary.

=== key requestID = JsonTakeValue(key storeID, string path) key reqeustID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

=== key requestID = JsonReadValue(key storeID, string path) key reqeustID = JsonReadValueJson(key storeID, string path) ===
Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

=== int status = JsonSetValue(key storeID, string path, string value) int status = JsonSetValue(key storeID, string path, string jsonvalue) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string. JsonSetValueJson() assumes that the value is a Json encoded string.

=== int status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

== Examples ==

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2012-04-17T23:25:45Z

Cmickeyb: /* int status = JsonTestPath(key storeID, string path)int JsonTestPathJson(key storeID, string path) */

== Introduction ==

The JsonStore module enables scripts and region modules to share structured data among themselves.

== Enabling the Module ==

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = True
</pre>

== JsonStore Path Syntax ==

== JsonStore Value Syntax ==

== JsonStore Script Functions ==

*JsonCreateStore
*JsonDestroyStore
*JsonReadNotecard
*JsonWriteNotecard
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson
*JsonSetValue/JsonSetValueJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. Return 1 if the operation is successful.

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== int status = JsonTestPath(key storeID, string path) int status = JsonTestPathJson(key storeID, string path) ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

=== string value = JsonGetValue(key storeID, string path) string jsonvalue = JsonGetValueJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary.

=== key requestID = JsonTakeValue(key storeID, string path) key reqeustID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

=== key requestID = JsonReadValue(key storeID, string path) key reqeustID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

=== int status = JsonSetValue(key storeID, string path, string value) int status = JsonSetValue(key storeID, string path, string jsonvalue) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string. JsonSetValueJson() assumes that the value is a Json encoded string.

=== int status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

== Examples ==

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2012-04-17T23:25:22Z

Cmickeyb:

== Introduction ==

The JsonStore module enables scripts and region modules to share structured data among themselves.

== Enabling the Module ==

Add the following to your OpenSim.ini to enable the JsonStore module:
<pre>
[JsonStore]
Enabled = True
</pre>

== JsonStore Path Syntax ==

== JsonStore Value Syntax ==

== JsonStore Script Functions ==

*JsonCreateStore
*JsonDestroyStore
*JsonReadNotecard
*JsonWriteNotecard
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson
*JsonSetValue/JsonSetValueJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. Return 1 if the operation is successful.

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== int status = JsonTestPath(key storeID, string path) int JsonTestPathJson(key storeID, string path) ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

=== string value = JsonGetValue(key storeID, string path) string jsonvalue = JsonGetValueJson(key storeID, string path) ===

Return the value identified by the path. In the case of JsonGetValue() the value must be a string. In the case of JsonGetValueJson() the value will be Json encoded string, array or dictionary.

=== key requestID = JsonTakeValue(key storeID, string path) key reqeustID = JsonTakeValueJson(key storeID, string path) ===

Request that the value identified by the path be removed from the store and returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonTakeValue() will request a string value. JsonTakeValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

This function is used to wait for a value to be available and then return. Since the operation of read and remove is atomic, it can be used to implement locks, task queues and other synchronization primitives.

=== key requestID = JsonReadValue(key storeID, string path) key reqeustID = JsonReadValueJson(key storeID, string path) ===

Request that the value identified by the path be returned to the script when it is available. The value will be returned through a link_message event with the requestID. JsonReadValue() will request a string value. JsonReadValueJson() will request a Json encoded string that corresponds to a string, array or hash value.

Unlike the JsonTakeValue() operation, the JsonReadValue operation does not remove the value from the store once it becomes available.

=== int status = JsonSetValue(key storeID, string path, string value) int status = JsonSetValue(key storeID, string path, string jsonvalue) ===

Save the value at the location identified by the path in the store. Any value currently at the location will be replaced. JsonSetValue() assumes that the value is a string. JsonSetValueJson() assumes that the value is a Json encoded string.

=== int status = JsonRemoveValue(key storeID, string path) ===

Remove from the store the value identified by the path.

== Examples ==

*[[OSSL Script Library/JsonStore|Generator/Consumer]]

JsonStore Module

2012-04-17T23:06:49Z

Cmickeyb: Created page with "== Introduction == The JsonStore module enables scripts and region modules to share structured data among themselves. == Enabling the Module == == JsonStore Path Syntax =..."

== Introduction ==

The JsonStore module enables scripts and region modules to share structured data among themselves.

== Enabling the Module ==

== JsonStore Path Syntax ==

== JsonStore Value Syntax ==

== JsonStore Script Functions ==

*JsonCreateStore
*JsonDestroyStore
*JsonReadNotecard
*JsonWriteNotecard
*JsonTestPath/JsonTestPathJson
*JsonGetValue/JsonGetValueJson
*JsonTakeValue/JsonTakeValueJson
*JsonReadValue/JsonReadValueJson
*JsonSetValue/JsonSetValueJson

=== key storeID = JsonCreateStore(string jsonvalue) ===

Create a JsonStore and initialize it using the Json encoded value. The new store identifier is returned.

=== integer status = JsonDestroyStore(key storeID) ===

Destroy the JsonStore associated with the provided identifier. Return 1 if the operation is successful.

=== key requestID = JsonReadNotecard(key storeID, string path, key assetID) ===

Request that the Json encoded content of a notecard be decoded and  placed in the structure in the store at the given path. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== key requestID = JsonWriteNotecard(key storeID, string path, string notecard) ===

Request that the value identified by the given path be Json encoded and written to the notecard. The function returns the request identifier. When the operation completes, a link_message event is generated with the request identifier.

=== int status = JsonTestPath(key storeID, string path) int JsonTestPathJson(key storeID, string path) ===

Check to see if there is a value identified by the path. In the case of JsonTestPath() the value must be a string. In the case of JsonTestPathJson() the value can be a string, an array, or a dictionary. The function returns 1 when there is an appropriate value.

=== string value = JsonGetValue(key storeID, string path) string jsonvalue = JsonGetValueJson(key storeID, string path) ===

=== key requestID = JsonTakeValue(key storeID, string path) key reqeustID = JsonTakeValueJson(key storeID, string path) ===

=== key requestID = JsonReadValue(key storeID, string path) key reqeustID = JsonReadValueJson(key storeID, string path) ===

=== int status = JsonSetValue(key storeID, string path, string value) int status = JsonSetValue(key storeID, string path, string jsonvalue) ===

=== int status = JsonRemoveValue(key storeID, string path) ===

== Examples ==

*[[OSSL_Script_Library/JsonStore|Generator/Consumer]]

User Documentation

2012-04-17T22:20:37Z

Cmickeyb: /* Optional Features */

{{Quicklinks}}

== Introduction ==
This is user documentation for OpenSimulator, mainly aimed towards administrators of the system rather than the ultimate end-users who access the environment through a viewer. If you can't find what you want here you might want to try looking in the [[Developer Documentation]].

For a summary of what features have been implemented in OpenSimulator, please see the [[Feature Matrix]].

== Initial Setup ==
* [[Download]] - Download instructions
* [[Dependencies]] - The other packages you need to install that OpenSimulator relies upon
* [[Build Instructions]] - How to build and compile OpenSimulator from source
* [[Configuration]] - How to configure OpenSimulator so you can get the server up and running
* [[Configuring Regions]] - More details on configuring regions in Regions.ini
* [[Configuring Simulator Parameters]] - More details on the structure and configuration simulator parameters after the initial setup.
* [[Database Settings]] - Detailed configurations to connect to your database
* [[Upgrading]] - How to upgrade your OpenSimulator version so that you can use your existing data
* [[Network Settings]] - NAT, Ports, Services and more.
* [[Firewall Settings]] - Incomplete operating system specific instructions on how to open firewall ports for external OpenSimulator access.
* [[Troubleshooting]] - How to trouble shoot your OpenSimulator installation.
* [[Tips]] - Useful tips from users like you
* [[OpenSim Graphics]] - Graphics that can be used on OpenSimulator websites, viewer login pages or products.
* [[FAQ]] - Frequently Asked Questions

== User Guide ==
* [[Connecting]] - How to connect a compatible viewer to OpenSimulator

== Administrator Guide ==
* [[Server Commands]] - Commands to control OpenSimulator
* [[OpenSim.exe Command Line Options]] - Switches when you launch OpenSimulator.
* [[Useful Queries]] - Some useful queries for manipulating the OpenSimulator database.
* [[Logging]] - Logging in OpenSimulator
* [[Monitoring]] - Monitoring OpenSimulator
* [[Automating Tasks]] - How to make administrating a walk in the park
* [[RemoteAdmin]] - Using the XMLRPC administration interface for executing commands remotely
* [[RestConsole]] - Using the remote console.
* [[Performance]] - How to tweak OpenSim's performance
* [[Console-less OpenSim]] - How to run OpenSimulator without console
* [[Backups]] - How to backup your OpenSimulator data.

== Core Features ==
* [[Feature Matrix]] - Matrix of features currently implemented by OpenSimulator.
* [[Scripting Documentation]] - Everything you need to know about OpenSimulator scripting, and the list of sample scripts
* [[OpenSim Archives]] - Loading and saving whole region archives with OpenSimulator
* [[Inventory Archives|OpenSimulator Inventory Archives]] - Loading and saving user inventory items and folders with OpenSimulator
* [[NPC]] - Use of Non Player Characters (NPCs) in OpenSim, also known as bots.
* [[Custom Libraries]] - Describes how to add custom content to your OpenSimulator server
* [[IRCBridgeModule]] - A core OpenSimulator module for integrating IRC with a simulator.
* [[Hypergrid]] - Information about how to configure the experimental hypergrid architecture
* [[GridInfo]] - how to provide information about your grid to smart clients
* [[PhysicsEngines]] — Options for physics engines in OpenSimulator.
* [[:Category:Tech Reference|Technical Reference]] - Technical Reference Guide

== Optional Features ==
* [[Feature Proposals/AutoBackup|AutoBackup]] - Module for automatically backing up a region to an OAR regularly using a different filename.
* [[Freeswitch Module]] - Using FreeSWITCH for voice in OpenSimulator.
* [[Mumble]] - Using Mumble/Whisper for voice in OpenSimulator.
* [[Enabling Groups]] — How to enable creating groups in your regions
* [[JsonStore Module]] -- Module for storing and sharing structured data among region modules and scripts

== Experimental Features ==

These are even more alpha than the rest of the code and may not currently work properly.

* [[Setting Up Mega-Regions]]

== RealXtend ==
* [[ModRex]] - How to setup the RealXtend server module
* [[RealXtend Viewer Linux]] - This tutorial describes how to use the RealXtend viewer on Linux, using wine

== Tutorials ==

If you've written a tutorial or guide on this wiki or on an external site, then please feel free to add a link here and/or on more specific topic pages.

=== Platform specific ===
* [[Linux Gridserver, the ubuntu way]] the quick and dirty way to install opensim under ubuntu (Linux)
* [[Wiimote]] - How to use a wiimote/nunchuk controller with the OpenSimulator viewer (Linux)
* [[Cacti]] - Generate Serverstats using the Cacti-Tool and SNMP (Linux)
* [http://sunredbeach.com/dokuwiki/doku.php?id=opensim:minimal-server Installing an openSUSE 11.1 Minimal server setup for an OpenSimulator server] - Quick and Dirty setup on an openSUSE 11.1 server
* [[Streaming Media in OpenSim]]

* [http://chapter-and-metaverse.blogspot.com Chapter & Metaverse] - Full suite of tutorials, tips and tricks, for the Windows user (Windows) Also very useful for Linux users!

=== Cross-platform ===
* [[Getting Started with Region Modules]] - The Hello World of OpenSimulator application development
* [[Using L3DT]] - How to create custom terrains
* [[Detailed cross-region terrain making]] - A workflow for creating large cross-region custom terrains
* [http://update.multiverse.net/wiki/index.php/About_Terrain How to make a good Terrain (includes 4 programs to use)]
* [http://www.nsl.tuis.ac.jp/xoops/modules/d3downloads/index.php?page=singlefile&cid=8&lid=22 Japanese Manual for Construction of OpenSimulator Server System on Linux] by NSL (Sorry, Japanese only)

=== Application ===
* [http://www.scribd.com/doc/57959626/OpenSimulator-School-Quick-Start-Guide David W. Deeds' OpenSimulator School Quick Start Guide] - David W. Deeds' OpenSimulator School Quick Start Guide courtesy of Changchun American International School. Has lots of useful and interesting info, including lesson plans.

== Gforge Projects ==
* [[OpenSimSearch]] - Search for your OpenSimulator
* [[ServerStats]] - RRD/Proc serverstats using the OpenSimulator module for Berlios Serverstats (Linux)
<cleanpage title=hide cats=hide />

[[Category:Users]]
[[Category:Support]]
[[Category:Help]]
[[Category:Configuration]]
[[Category:Getting Started]]
[[Category:Development]]

OSSL Script Library/JsonStore

2012-04-17T22:16:05Z

Cmickeyb: /* Introduction */

== Introduction ==

This page describes two scripts, a generator and a consumer, that demonstrate how to use the JsonStore JsonStoreRead and JsonStoreTake operations for creating a master/worker pair of scripts. Place the generator script in an object and the consumer script in another object. Touch the generator to start the process.

To see the value of the master/worker pattern, try to make multiple copies of the consumer object. Each one will read tasks created by the generator.

This functionality current only exists in OpenSimulator development code (0.7.4-dev).

== Enabling the JsonStore Module ==

The first thing is to enable the JsonStore module in OpenSim.ini. Add the following to enable the module:

<pre>
[JsonStore]
Enabled = True
</pre>

== The Generator Script ==

The generator script writes values to a shared array where consumers can pull those values. The script uses the global store (public scratch storage space) to share the identity of the Json store that it creates.

<source lang="lsl">
string sStoreName = "JsonStoreTest";
key kGlobalStore = (key)NULL_KEY;

integer iCounter = 0;
key kStoreID;

default
{
state_entry()
{
llOwnerSay("running...");
}

touch_start(integer i)
{
state running;
}
}

state running
{
state_entry()
{
// Create a JsonStore initialized with an empty array associated with the key 'Event'
kStoreID = JsonCreateStore("{'Event' : []}");

// Save the store that was just created in the global store, this makes it easier for
// other scripts to find; an alternative is to say the store id in a private channel
JsonSetValue(kGlobalStore,sStoreName,(string)kStoreID);

// Start a timer that will generate counters periodically
llSetTimerEvent(1.0);
}

timer()
{
// Generate a new counter and add it to the end of the Event array
iCounter += 1;
JsonSetValue(kStoreID,"Event[+]",(string)iCounter);
}

touch_start(integer i)
{
// When the test is done, remove the identity of the store and destroy it
JsonRemoveValue(kGlobalStore,sStoreName);
JsonDestroyStore(kStoreID);

llResetScript();
}
}
</source>

== The Consumer Script ==

The consumer script waits for the generator to create the store and place its identity into the global store. At that
point it begins to read values from the generator's store.

<source lang="lsl">
string sStoreName = "JsonStoreTest";
key kGlobalStore = (key)NULL_KEY;

key kStoreID;
key kReqID;

default
{
state_entry()
{
// Set up a request for the identity of the generator's store
// This posts a request, when the value is available a link message event will be fired
kReqID = JsonReadValue(kGlobalStore,sStoreName);
}

link_message(integer sender, integer result, string msg, key id)
{
if (sender != -1)
return;

llOwnerSay("shared store id: " + msg);
kStoreID = (key)msg;

state running;
}
}

state running
{
state_entry()
{
// Set up a request that will take a value (remove it from the store) when it is available
// A link_message will be fired when the value is available
kReqID = JsonTakeValue(kStoreID,"Event[0]");
}

link_message(integer sender, integer result, string msg, key id)
{
if (sender != -1)
return;

llOwnerSay("read " + msg);
kReqID = JsonTakeValue(kStoreID,"Event[0]");
}

touch_start(integer i)
{
llResetScript();
}
}
</source>

[[Category:Scripts]]

OSSL Script Library/JsonStore

2012-04-17T22:13:08Z

Cmickeyb: /* Enabling modInvoke() */

== Introduction ==

This functionality current only exists in OpenSimulator development code (0.7.4-dev).

== Enabling the JsonStore Module ==

The first thing is to enable the JsonStore module in OpenSim.ini. Add the following to enable the module:

<pre>
[JsonStore]
Enabled = True
</pre>

== The Generator Script ==

The generator script writes values to a shared array where consumers can pull those values. The script uses the global store (public scratch storage space) to share the identity of the Json store that it creates.

<source lang="lsl">
string sStoreName = "JsonStoreTest";
key kGlobalStore = (key)NULL_KEY;

integer iCounter = 0;
key kStoreID;

default
{
state_entry()
{
llOwnerSay("running...");
}

touch_start(integer i)
{
state running;
}
}

state running
{
state_entry()
{
// Create a JsonStore initialized with an empty array associated with the key 'Event'
kStoreID = JsonCreateStore("{'Event' : []}");

// Save the store that was just created in the global store, this makes it easier for
// other scripts to find; an alternative is to say the store id in a private channel
JsonSetValue(kGlobalStore,sStoreName,(string)kStoreID);

// Start a timer that will generate counters periodically
llSetTimerEvent(1.0);
}

timer()
{
// Generate a new counter and add it to the end of the Event array
iCounter += 1;
JsonSetValue(kStoreID,"Event[+]",(string)iCounter);
}

touch_start(integer i)
{
// When the test is done, remove the identity of the store and destroy it
JsonRemoveValue(kGlobalStore,sStoreName);
JsonDestroyStore(kStoreID);

llResetScript();
}
}
</source>

== The Consumer Script ==

The consumer script waits for the generator to create the store and place its identity into the global store. At that
point it begins to read values from the generator's store.

<source lang="lsl">
string sStoreName = "JsonStoreTest";
key kGlobalStore = (key)NULL_KEY;

key kStoreID;
key kReqID;

default
{
state_entry()
{
// Set up a request for the identity of the generator's store
// This posts a request, when the value is available a link message event will be fired
kReqID = JsonReadValue(kGlobalStore,sStoreName);
}

link_message(integer sender, integer result, string msg, key id)
{
if (sender != -1)
return;

llOwnerSay("shared store id: " + msg);
kStoreID = (key)msg;

state running;
}
}

state running
{
state_entry()
{
// Set up a request that will take a value (remove it from the store) when it is available
// A link_message will be fired when the value is available
kReqID = JsonTakeValue(kStoreID,"Event[0]");
}

link_message(integer sender, integer result, string msg, key id)
{
if (sender != -1)
return;

llOwnerSay("read " + msg);
kReqID = JsonTakeValue(kStoreID,"Event[0]");
}

touch_start(integer i)
{
llResetScript();
}
}
</source>

[[Category:Scripts]]

OSSL Script Library/JsonStore

2012-04-17T22:12:43Z

Cmickeyb: /* The Generator Script */

== Introduction ==

This functionality current only exists in OpenSimulator development code (0.7.4-dev).

== Enabling modInvoke() ==

The first thing is to enable the JsonStore module in OpenSim.ini. Add the following to enable the module:

<pre>
[JsonStore]
Enabled = True
</pre>

== The Generator Script ==

The generator script writes values to a shared array where consumers can pull those values. The script uses the global store (public scratch storage space) to share the identity of the Json store that it creates.

<source lang="lsl">
string sStoreName = "JsonStoreTest";
key kGlobalStore = (key)NULL_KEY;

integer iCounter = 0;
key kStoreID;

default
{
state_entry()
{
llOwnerSay("running...");
}

touch_start(integer i)
{
state running;
}
}

state running
{
state_entry()
{
// Create a JsonStore initialized with an empty array associated with the key 'Event'
kStoreID = JsonCreateStore("{'Event' : []}");

// Save the store that was just created in the global store, this makes it easier for
// other scripts to find; an alternative is to say the store id in a private channel
JsonSetValue(kGlobalStore,sStoreName,(string)kStoreID);

// Start a timer that will generate counters periodically
llSetTimerEvent(1.0);
}

timer()
{
// Generate a new counter and add it to the end of the Event array
iCounter += 1;
JsonSetValue(kStoreID,"Event[+]",(string)iCounter);
}

touch_start(integer i)
{
// When the test is done, remove the identity of the store and destroy it
JsonRemoveValue(kGlobalStore,sStoreName);
JsonDestroyStore(kStoreID);

llResetScript();
}
}
</source>

== The Consumer Script ==

The consumer script waits for the generator to create the store and place its identity into the global store. At that
point it begins to read values from the generator's store.

<source lang="lsl">
string sStoreName = "JsonStoreTest";
key kGlobalStore = (key)NULL_KEY;

key kStoreID;
key kReqID;

default
{
state_entry()
{
// Set up a request for the identity of the generator's store
// This posts a request, when the value is available a link message event will be fired
kReqID = JsonReadValue(kGlobalStore,sStoreName);
}

link_message(integer sender, integer result, string msg, key id)
{
if (sender != -1)
return;

llOwnerSay("shared store id: " + msg);
kStoreID = (key)msg;

state running;
}
}

state running
{
state_entry()
{
// Set up a request that will take a value (remove it from the store) when it is available
// A link_message will be fired when the value is available
kReqID = JsonTakeValue(kStoreID,"Event[0]");
}

link_message(integer sender, integer result, string msg, key id)
{
if (sender != -1)
return;

llOwnerSay("read " + msg);
kReqID = JsonTakeValue(kStoreID,"Event[0]");
}

touch_start(integer i)
{
llResetScript();
}
}
</source>

[[Category:Scripts]]

OSSL Script Library/JsonStore

2012-04-17T22:09:41Z

Cmickeyb: Created page with "== Introduction == This functionality current only exists in OpenSimulator development code (0.7.4-dev). == Enabling modInvoke() == The first thing is to enable the JsonStore ..."

== Introduction ==

This functionality current only exists in OpenSimulator development code (0.7.4-dev).

== Enabling modInvoke() ==

The first thing is to enable the JsonStore module in OpenSim.ini. Add the following to enable the module:

<pre>
[JsonStore]
Enabled = True
</pre>

== The Generator Script ==

<source lang="lsl">
string sStoreName = "JsonStoreTest";
key kGlobalStore = (key)NULL_KEY;

integer iCounter = 0;
key kStoreID;

default
{
state_entry()
{
llOwnerSay("running...");
}

touch_start(integer i)
{
state running;
}
}

state running
{
state_entry()
{
// Create a JsonStore initialized with an empty array associated with the key 'Event'
kStoreID = JsonCreateStore("{'Event' : []}");

// Save the store that was just created in the global store, this makes it easier for
// other scripts to find; an alternative is to say the store id in a private channel
JsonSetValue(kGlobalStore,sStoreName,(string)kStoreID);

// Start a timer that will generate counters periodically
llSetTimerEvent(1.0);
}

timer()
{
// Generate a new counter and add it to the end of the Event array
iCounter += 1;
JsonSetValue(kStoreID,"Event[+]",(string)iCounter);
}

touch_start(integer i)
{
// When the test is done, remove the identity of the store and destroy it
JsonRemoveValue(kGlobalStore,sStoreName);
JsonDestroyStore(kStoreID);

llResetScript();
}
}
</source>

== The Consumer Script ==

The consumer script waits for the generator to create the store and place its identity into the global store. At that
point it begins to read values from the generator's store.

<source lang="lsl">
string sStoreName = "JsonStoreTest";
key kGlobalStore = (key)NULL_KEY;

key kStoreID;
key kReqID;

default
{
state_entry()
{
// Set up a request for the identity of the generator's store
// This posts a request, when the value is available a link message event will be fired
kReqID = JsonReadValue(kGlobalStore,sStoreName);
}

link_message(integer sender, integer result, string msg, key id)
{
if (sender != -1)
return;

llOwnerSay("shared store id: " + msg);
kStoreID = (key)msg;

state running;
}
}

state running
{
state_entry()
{
// Set up a request that will take a value (remove it from the store) when it is available
// A link_message will be fired when the value is available
kReqID = JsonTakeValue(kStoreID,"Event[0]");
}

link_message(integer sender, integer result, string msg, key id)
{
if (sender != -1)
return;

llOwnerSay("read " + msg);
kReqID = JsonTakeValue(kStoreID,"Event[0]");
}

touch_start(integer i)
{
llResetScript();
}
}
</source>

[[Category:Scripts]]

OSSL Script Library

2012-04-17T21:53:38Z

Cmickeyb: /* The Library */

{{Quicklinks}} {{information}}

= OSSL Script Library =

=== Rules for posting: ===

# Your script '''MUST''' depend on at least one [[OSSL Functions|OSSL function]], or on other OpenSim-specific functions.
# Test your script in-world, and make sure it works, so that other people can use it.
# No copies of scripts which already exist on this wiki, unless it exists in your own user page.
# Please, no short scripts (5 lines or less), and definitely no one-liners!
# Make sure to read "[[OSSL Script Library#Adding your script to the Library|Adding your script to the Library]]" for important info!

== The Library ==

{| class="sortable" border="2" cellspacing="0" cellpadding="3"
|-
| Script Name
| Posted by:
| Description
|-
| [[OSSL Script Library/ModSendCommand|ModSendCommand]]
| [[User:Justincc|Justincc]]
| Demonstrates the use of an in-world script to communicate with a specific OpenSimulator module.
|-
| [[OSSL Script Library/ModInvoke|ModInvoke]]
| [[User:Cmickeyb|Cmickeyb]]
| Demonstrates the use of an in-world script to invoke functions defined in an OpenSimulator module.
|-
| [[OSSL Script Library/JsonStore|JsonStore]]
| [[User:Cmickeyb|Cmickeyb]]
| Demonstrates the use of the JsonStore module for managing structured data in an LSL script.
|-
| [[OSSL Script Library/OpenSim Radio|OpenSimulator Radio]]
| [[User:Fritigern|Fritigern]]
| A dialog controlled radio for OpenSimulator. Uses OSSL functions to read stations from a notecard,
|-
| [[OSSL Script Library/Persist NPC|Persist NPC]]
| [[User:Marcus Llewellyn|Marcus Llewellyn]]
| A short example of a method for persisting an NPC across simulator restarts.
|-
| [[OSSL Script Library/Simple Notecard Reader|Simple Notecard Reader]]
| [[User:Fritigern|Fritigern]]
| Reading notecards in OSSL is easy. This script is more of an example than a fully useful script, but it does work. Use it in your own scripts!
|-
| [[OSSL Script Library/OSSL Poseball|OSSL Poseball]]
| [[User:Fritigern|Fritigern]]
| Poseball script, written from scratch, using [[osAvatarPlayAnimation]]() and [[osAvatarStopAnimation]]()
|}

== Adding your script to the Library ==

* First select, right-click, and copy the following code:
<pre> |-
| [[OSSL Script Library/SCRIPT_NAME|SCRIPT_NAME]]
| [[User:YOURNAME|YOURNAME]]
| DESCRIPTION
</pre>
* Edit the Library section, and paste the above code to the end of the list,, but just above "'''|}'''"
* Replace "'''SCRIPT_NAME'''" with the name of your script. Make sure to change both instances.
* Replace "'''YOURNAME'''" with your wiki username. Make sure to change both instances.
* Replace the word '''DESCRIPTION''' with a short desription of what your script does.
* Click the "'''Show preview'''" button to check and see if everything works as it's supposed to.
* If something looks wrong, change whatever is not right, and click "'''Show preview'''" again.
* If everything looks okay, click the "'''Save page'''" button.
* In the table, look up the name of your script (it should be red) and click it. This will create a new page.
* In the new page, Type '''<nowiki><source lang="lsl"></nowiki>'''. This will make the wiki recognise your script as LSL, and apply the correct source highlighting.
* Paste your script into the page.
* Immediately below your script, type '''<nowiki></source></nowiki>'''. This will tell the wiki where your script ends.
* Optionally add an introductory text, though you are encouraged to place usage instructions for your script in your script's comments.
* Preview the page by clicking the "'''Show preview'''" button.
* Make changes where nescessary and click the "'''Show preview'''" button again.
* Save your page by pressing the "'''Save page'''" button, and presto!

[[Category:Scripts]]
[[Category:OSSL]]

OSSL Script Library/ModInvoke

2012-03-26T16:25:16Z

Cmickeyb: /* The Region Module */

You can invoke functions defined in a region module from a script using the modInvoke() family of functions.

== Enabling modInvoke() ==

The first thing is to enable modSendCommand() in OpenSim.ini. Make sure the line

<pre>
AllowMODFunctions = true
</pre>

is set to true and uncommented.

== The Region Module ==

Here's the region module that implements several functions to be provided to scripts in the region.

<source lang = "csharp">
using Mono.Addins;

using System;
using System.Reflection;
using System.Threading;
using System.Text;
using System.Net;
using System.Net.Sockets;
using log4net;
using Nini.Config;
using OpenMetaverse;
using OpenMetaverse.StructuredData;
using OpenSim.Framework;
using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes;
using System.Collections.Generic;
using System.Text.RegularExpressions;

[assembly: Addin("ModInvokeTest", "0.1")]
[assembly: AddinDependency("OpenSim", "0.5")]

namespace ModInvokeTest
{
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule")]

public class ModInvokeTestModule : INonSharedRegionModule
{
private static readonly ILog m_log =
LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);

private IConfig m_config = null;
private bool m_enabled = true;
private Scene m_scene = null;

private IScriptModuleComms m_comms;

#region IRegionModule Members

public string Name
{
get { return this.GetType().Name; }
}

public void Initialise(IConfigSource config)
{
m_log.WarnFormat("[ModInvoke] start configuration");

try
{
if ((m_config = config.Configs["ModInvoke"]) != null)
m_enabled = m_config.GetBoolean("Enabled", m_enabled);
}
catch (Exception e)
{
m_log.ErrorFormat("[ModInvoke] initialization error: {0}",e.Message);
return;
}

m_log.ErrorFormat("[ModInvoke] module {0} enabled",(m_enabled ? "is" : "is not"));
}

public void PostInitialise()
{
if (m_enabled) {}
}

public void Close() { }
public void AddRegion(Scene scene) { }
public void RemoveRegion(Scene scene) { }

public void RegionLoaded(Scene scene)
{
if (m_enabled)
{
m_scene = scene;
m_comms = m_scene.RequestModuleInterface<IScriptModuleComms>();
if (m_comms == null)
{
m_log.WarnFormat("[ModInvoke] ScriptModuleComms interface not defined");
m_enabled = false;

return;
}

m_comms.RegisterScriptInvocation(this,"ModTest0");
m_comms.RegisterScriptInvocation(this,"ModTest1");
m_comms.RegisterScriptInvocation(this,"ModTest2");
m_comms.RegisterScriptInvocation(this,"ModTest3");
m_comms.RegisterScriptInvocation(this,"ModTest4");
m_comms.RegisterScriptInvocation(this,"ModTest5");
m_comms.RegisterScriptInvocation(this,"ModTest6");
m_comms.RegisterScriptInvocation(this,"ModTest7");
m_comms.RegisterScriptInvocation(this,"ModTest8");
}
}

public Type ReplaceableInterface
{
get { return null; }
}

#endregion

#region ScriptInvocationInteface
public string ModTest0(UUID hostID, UUID scriptID)
{
m_log.WarnFormat("[ModInvoke] ModTest0 parameter");
return "";
}

public string ModTest1(UUID hostID, UUID scriptID, string value)
{
m_log.WarnFormat("[ModInvoke] ModTest1 parameter: {0}",value);
return value;
}

public int ModTest2(UUID hostID, UUID scriptID, int value)
{
m_log.WarnFormat("[ModInvoke] ModTest2 parameter: {0}",value);
return value;
}

public float ModTest3(UUID hostID, UUID scriptID, float value)
{
m_log.WarnFormat("[ModInvoke] ModTest3 parameter: {0}",value);
return value;
}

public UUID ModTest4(UUID hostID, UUID scriptID, UUID value)
{
m_log.WarnFormat("[ModInvoke] ModTest4 parameter: {0}",value.ToString());
return value;
}

public OpenMetaverse.Vector3 ModTest5(UUID hostID, UUID scriptID, OpenMetaverse.Vector3 value)
{
m_log.WarnFormat("[ModInvoke] ModTest5 parameter: {0}",value.ToString());
return value;
}

public OpenMetaverse.Quaternion ModTest6(UUID hostID, UUID scriptID, OpenMetaverse.Quaternion value)
{
m_log.WarnFormat("[ModInvoke] ModTest6 parameter: {0}",value.ToString());
return value;
}

public object[] ModTest7(UUID hostID, UUID scriptID, int count, string val)
{
object[] result = new object[count];
for (int i = 0; i < count; i++)
result[i] = val;

return result;
}

public object[] ModTest8(UUID hostID, UUID scriptID, object[] lparm)
{
object[] result = new object[lparm.Length];

for (int i = 0; i < lparm.Length; i++)
result[lparm.Length - i - 1] = lparm[i];

return result;
}

#endregion
}
}
</source>

The module registers functions through the IScriptModuleComms RegisterScriptInvocation() method. This method takes the name of the function, an invocation delegate, an array of types used to validate parameters to the function, and a return type.

The functions in the region module can assume that the parameters passed through the argument array match the signature that was registered. That is, the function in the region module does not need to perform any kind of type checking.

== The In-world Script ==

Here's the in-world script that calls the functions defined in the region module.

<source lang="lsl">
default
{
state_entry()
{
llSay(0, "Script running");
llOwnerSay("ModTest0: " + ModTest0());
llOwnerSay("ModTest1: " + ModTest1("one"));

integer v2 = ModTest2(2) + 2;
llOwnerSay("ModTest2: " + (string)v2);

float v3 = ModTest3(3.14) + 4.56;
llOwnerSay("ModTest3: " + (string)v3);

key v4 = ModTest4(llGetKey());
llOwnerSay("ModTest4: " + (string)v4);

vector v5 = ModTest5(llGetPos());
llOwnerSay("ModTest5: " + (string)v5);

rotation v6 = ModTest6(llGetRot());
llOwnerSay("ModTest6: " + (string)v6);

list v7 = ModTest7(5,"hello");
llOwnerSay("ModTest7: " + (string)llGetListLength(v7));
llOwnerSay("ModTest7: " + llList2CSV(v7));

list v8 = ["a", 1, llGetKey(), llGetPos(), llGetRot()];
list v9 = ModTest8(v8);
llOwnerSay("ModTest8: " + (string)llGetListLength(v9));
llOwnerSay("ModTest8: " + llList2CSV(v9));

}
}
</source>
[[Category:Scripts]]

OSSL Script Library/ModInvoke

2012-03-26T16:24:53Z

Cmickeyb: /* The Region Module */

You can invoke functions defined in a region module from a script using the modInvoke() family of functions.

== Enabling modInvoke() ==

The first thing is to enable modSendCommand() in OpenSim.ini. Make sure the line

<pre>
AllowMODFunctions = true
</pre>

is set to true and uncommented.

== The Region Module ==

Here's the region module that implements several functions to be provided to scripts in the region.

<source lang = "csharp">
/*
* Copyright (c) Contributors
* See CONTRIBUTORS.TXT for a full list of copyright holders.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* * Neither the name of the OpenSim Project nor the
* names of its contributors may be used to endorse or promote products
* derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY
* DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
* LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
using Mono.Addins;

using System;
using System.Reflection;
using System.Threading;
using System.Text;
using System.Net;
using System.Net.Sockets;
using log4net;
using Nini.Config;
using OpenMetaverse;
using OpenMetaverse.StructuredData;
using OpenSim.Framework;
using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes;
using System.Collections.Generic;
using System.Text.RegularExpressions;

[assembly: Addin("ModInvokeTest", "0.1")]
[assembly: AddinDependency("OpenSim", "0.5")]

namespace ModInvokeTest
{
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule")]

public class ModInvokeTestModule : INonSharedRegionModule
{
private static readonly ILog m_log =
LogManager.GetLogger(MethodBase.GetCurrentMethod().DeclaringType);

private IConfig m_config = null;
private bool m_enabled = true;
private Scene m_scene = null;

private IScriptModuleComms m_comms;

#region IRegionModule Members

public string Name
{
get { return this.GetType().Name; }
}

public void Initialise(IConfigSource config)
{
m_log.WarnFormat("[ModInvoke] start configuration");

try
{
if ((m_config = config.Configs["ModInvoke"]) != null)
m_enabled = m_config.GetBoolean("Enabled", m_enabled);
}
catch (Exception e)
{
m_log.ErrorFormat("[ModInvoke] initialization error: {0}",e.Message);
return;
}

m_log.ErrorFormat("[ModInvoke] module {0} enabled",(m_enabled ? "is" : "is not"));
}

public void PostInitialise()
{
if (m_enabled) {}
}

public void Close() { }
public void AddRegion(Scene scene) { }
public void RemoveRegion(Scene scene) { }

public void RegionLoaded(Scene scene)
{
if (m_enabled)
{
m_scene = scene;
m_comms = m_scene.RequestModuleInterface<IScriptModuleComms>();
if (m_comms == null)
{
m_log.WarnFormat("[ModInvoke] ScriptModuleComms interface not defined");
m_enabled = false;

return;
}

m_comms.RegisterScriptInvocation(this,"ModTest0");
m_comms.RegisterScriptInvocation(this,"ModTest1");
m_comms.RegisterScriptInvocation(this,"ModTest2");
m_comms.RegisterScriptInvocation(this,"ModTest3");
m_comms.RegisterScriptInvocation(this,"ModTest4");
m_comms.RegisterScriptInvocation(this,"ModTest5");
m_comms.RegisterScriptInvocation(this,"ModTest6");
m_comms.RegisterScriptInvocation(this,"ModTest7");
m_comms.RegisterScriptInvocation(this,"ModTest8");
}
}

public Type ReplaceableInterface
{
get { return null; }
}

#endregion

#region ScriptInvocationInteface
public string ModTest0(UUID hostID, UUID scriptID)
{
m_log.WarnFormat("[ModInvoke] ModTest0 parameter");
return "";
}

public string ModTest1(UUID hostID, UUID scriptID, string value)
{
m_log.WarnFormat("[ModInvoke] ModTest1 parameter: {0}",value);
return value;
}

public int ModTest2(UUID hostID, UUID scriptID, int value)
{
m_log.WarnFormat("[ModInvoke] ModTest2 parameter: {0}",value);
return value;
}

public float ModTest3(UUID hostID, UUID scriptID, float value)
{
m_log.WarnFormat("[ModInvoke] ModTest3 parameter: {0}",value);
return value;
}

public UUID ModTest4(UUID hostID, UUID scriptID, UUID value)
{
m_log.WarnFormat("[ModInvoke] ModTest4 parameter: {0}",value.ToString());
return value;
}

public OpenMetaverse.Vector3 ModTest5(UUID hostID, UUID scriptID, OpenMetaverse.Vector3 value)
{
m_log.WarnFormat("[ModInvoke] ModTest5 parameter: {0}",value.ToString());
return value;
}

public OpenMetaverse.Quaternion ModTest6(UUID hostID, UUID scriptID, OpenMetaverse.Quaternion value)
{
m_log.WarnFormat("[ModInvoke] ModTest6 parameter: {0}",value.ToString());
return value;
}

public object[] ModTest7(UUID hostID, UUID scriptID, int count, string val)
{
object[] result = new object[count];
for (int i = 0; i < count; i++)
result[i] = val;

return result;
}

public object[] ModTest8(UUID hostID, UUID scriptID, object[] lparm)
{
object[] result = new object[lparm.Length];

for (int i = 0; i < lparm.Length; i++)
result[lparm.Length - i - 1] = lparm[i];

return result;
}

#endregion
}
}
</source>

The module registers functions through the IScriptModuleComms RegisterScriptInvocation() method. This method takes the name of the function, an invocation delegate, an array of types used to validate parameters to the function, and a return type.

The functions in the region module can assume that the parameters passed through the argument array match the signature that was registered. That is, the function in the region module does not need to perform any kind of type checking.

== The In-world Script ==

Here's the in-world script that calls the functions defined in the region module.

<source lang="lsl">
default
{
state_entry()
{
llSay(0, "Script running");
llOwnerSay("ModTest0: " + ModTest0());
llOwnerSay("ModTest1: " + ModTest1("one"));

integer v2 = ModTest2(2) + 2;
llOwnerSay("ModTest2: " + (string)v2);

float v3 = ModTest3(3.14) + 4.56;
llOwnerSay("ModTest3: " + (string)v3);

key v4 = ModTest4(llGetKey());
llOwnerSay("ModTest4: " + (string)v4);

vector v5 = ModTest5(llGetPos());
llOwnerSay("ModTest5: " + (string)v5);

rotation v6 = ModTest6(llGetRot());
llOwnerSay("ModTest6: " + (string)v6);

list v7 = ModTest7(5,"hello");
llOwnerSay("ModTest7: " + (string)llGetListLength(v7));
llOwnerSay("ModTest7: " + llList2CSV(v7));

list v8 = ["a", 1, llGetKey(), llGetPos(), llGetRot()];
list v9 = ModTest8(v8);
llOwnerSay("ModTest8: " + (string)llGetListLength(v9));
llOwnerSay("ModTest8: " + llList2CSV(v9));

}
}
</source>
[[Category:Scripts]]

OSSL Script Library/ModInvoke

2012-03-25T05:34:38Z

Cmickeyb: /* The Region Module */

You can invoke functions defined in a region module from a script using the modInvoke() family of functions.

== Enabling modInvoke() ==

The first thing is to enable modSendCommand() in OpenSim.ini. Make sure the line

<pre>
AllowMODFunctions = true
</pre>

is set to true and uncommented.

== The Region Module ==

Here's the region module that implements several functions to be provided to scripts in the region.

<source lang = "csharp">
using Mono.Addins;

using System;
using System.Reflection;
using System.Threading;
using System.Text;
using log4net;
using Nini.Config;
using OpenSim.Framework;
using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes;
using System.Collections.Generic;
using OpenMetaverse;
using OpenMetaverse.StructuredData;

[assembly: Addin("ModInvokeTest", "0.1")]
[assembly: AddinDependency("OpenSim", "0.5")]

namespace ModInvokeTest
{
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule")]

public class ModInvokeTestModule : INonSharedRegionModule
{
private Scene m_scene = null;
private IScriptModuleComms m_comms;

#region IRegionModule Members

public string Name
{
get { return this.GetType().Name; }
}

public void Initialise(IConfigSource config) {}
public void PostInitialise(){}
public void Close(){}
public void AddRegion(Scene scene){}
public void RemoveRegion(Scene scene){}

public void RegionLoaded(Scene scene)
{
m_scene = scene;
m_comms = m_scene.RequestModuleInterface<IScriptModuleComms>();

m_comms.RegisterScriptInvocation("ModTest0",SI_ModTest0,new Type[] { }, typeof(string));
m_comms.RegisterScriptInvocation("ModTest1",SI_ModTest1,new Type[] { typeof(string) }, typeof(string));
m_comms.RegisterScriptInvocation("ModTest2",SI_ModTest2,new Type[] { typeof(int) }, typeof(int));
m_comms.RegisterScriptInvocation("ModTest3",SI_ModTest3,new Type[] { typeof(float) }, typeof(float));
m_comms.RegisterScriptInvocation("ModTest4",SI_ModTest4,new Type[] { typeof(UUID) }, typeof(UUID));
m_comms.RegisterScriptInvocation("ModTest5",SI_ModTest5,
new Type[] { typeof(OpenMetaverse.Vector3) },typeof(OpenMetaverse.Vector3));
m_comms.RegisterScriptInvocation("ModTest6",SI_ModTest6,
new Type[] { typeof(OpenMetaverse.Quaternion)},
typeof(OpenMetaverse.Quaternion));
m_comms.RegisterScriptInvocation("ModTest7",SI_ModTest7,
new Type[] { typeof(int), typeof(string) },typeof(object[]));
m_comms.RegisterScriptInvocation("ModTest8",SI_ModTest8,
new Type[] { typeof(object[]) },typeof(object[]));
}

public Type ReplaceableInterface
{
get { return null; }
}

#endregion

#region ScriptInvocationInteface
protected object SI_ModTest0(UUID scriptID, object[] parray)
{
return "";
}

protected object SI_ModTest1(UUID scriptID, object[] parray)
{
string value = (string)parray[0];
return value;
}

protected object SI_ModTest2(UUID scriptID, object[] parray)
{
int value = (int)parray[0];
return value;
}

protected object SI_ModTest3(UUID scriptID, object[] parray)
{
float value = (float)parray[0];
return value;
}

protected object SI_ModTest4(UUID scriptID, object[] parray)
{
UUID value = (UUID)parray[0];
return value;
}

protected object SI_ModTest5(UUID scriptID, object[] parray)
{
OpenMetaverse.Vector3 value = (OpenMetaverse.Vector3)parray[0];
return value;
}

protected object SI_ModTest6(UUID scriptID, object[] parray)
{
OpenMetaverse.Quaternion value = (OpenMetaverse.Quaternion)parray[0];
return value;
}

protected object SI_ModTest7(UUID scriptID, object[] parray)
{
int count = (int)parray[0];
string val = (string)parray[1];

object[] result = new object[count];
for (int i = 0; i < count; i++)
result[i] = val;

return result;
}

protected object SI_ModTest8(UUID scriptID, object[] parray)
{
object[] lparm = (object[])parray[0];
object[] result = new object[lparm.Length];

for (int i = 0; i < lparm.Length; i++)
result[lparm.Length - i - 1] = lparm[i];

return result;
}

#endregion
}
}
</source>

The module registers functions through the IScriptModuleComms RegisterScriptInvocation() method. This method takes the name of the function, an invocation delegate, an array of types used to validate parameters to the function, and a return type.

The functions in the region module can assume that the parameters passed through the argument array match the signature that was registered. That is, the function in the region module does not need to perform any kind of type checking.

== The In-world Script ==

Here's the in-world script that calls the functions defined in the region module.

<source lang="lsl">
default
{
state_entry()
{
llSay(0, "Script running");
llOwnerSay("ModTest0: " + ModTest0());
llOwnerSay("ModTest1: " + ModTest1("one"));

integer v2 = ModTest2(2) + 2;
llOwnerSay("ModTest2: " + (string)v2);

float v3 = ModTest3(3.14) + 4.56;
llOwnerSay("ModTest3: " + (string)v3);

key v4 = ModTest4(llGetKey());
llOwnerSay("ModTest4: " + (string)v4);

vector v5 = ModTest5(llGetPos());
llOwnerSay("ModTest5: " + (string)v5);

rotation v6 = ModTest6(llGetRot());
llOwnerSay("ModTest6: " + (string)v6);

list v7 = ModTest7(5,"hello");
llOwnerSay("ModTest7: " + (string)llGetListLength(v7));
llOwnerSay("ModTest7: " + llList2CSV(v7));

list v8 = ["a", 1, llGetKey(), llGetPos(), llGetRot()];
list v9 = ModTest8(v8);
llOwnerSay("ModTest8: " + (string)llGetListLength(v9));
llOwnerSay("ModTest8: " + llList2CSV(v9));

}
}
</source>
[[Category:Scripts]]

OSSL Script Library/ModInvoke

2012-03-25T05:33:55Z

Cmickeyb: /* The Region Module */

You can invoke functions defined in a region module from a script using the modInvoke() family of functions.

== Enabling modInvoke() ==

The first thing is to enable modSendCommand() in OpenSim.ini. Make sure the line

<pre>
AllowMODFunctions = true
</pre>

is set to true and uncommented.

== The Region Module ==

Here's the region module that implements several functions to be provided to scripts in the region.

<source lang = "csharp">
using Mono.Addins;

using System;
using System.Reflection;
using System.Threading;
using System.Text;
using log4net;
using Nini.Config;
using OpenSim.Framework;
using OpenSim.Region.Framework.Interfaces;
using OpenSim.Region.Framework.Scenes;
using System.Collections.Generic;

[assembly: Addin("ModInvokeTest", "0.1")]
[assembly: AddinDependency("OpenSim", "0.5")]

namespace ModInvokeTest
{
[Extension(Path = "/OpenSim/RegionModules", NodeName = "RegionModule")]

public class ModInvokeTestModule : INonSharedRegionModule
{
private Scene m_scene = null;
private IScriptModuleComms m_comms;

#region IRegionModule Members

public string Name
{
get { return this.GetType().Name; }
}

public void Initialise(IConfigSource config) {}
public void PostInitialise(){}
public void Close(){}
public void AddRegion(Scene scene){}
public void RemoveRegion(Scene scene){}

public void RegionLoaded(Scene scene)
{
m_scene = scene;
m_comms = m_scene.RequestModuleInterface<IScriptModuleComms>();

m_comms.RegisterScriptInvocation("ModTest0",SI_ModTest0,new Type[] { }, typeof(string));
m_comms.RegisterScriptInvocation("ModTest1",SI_ModTest1,new Type[] { typeof(string) }, typeof(string));
m_comms.RegisterScriptInvocation("ModTest2",SI_ModTest2,new Type[] { typeof(int) }, typeof(int));
m_comms.RegisterScriptInvocation("ModTest3",SI_ModTest3,new Type[] { typeof(float) }, typeof(float));
m_comms.RegisterScriptInvocation("ModTest4",SI_ModTest4,new Type[] { typeof(UUID) }, typeof(UUID));
m_comms.RegisterScriptInvocation("ModTest5",SI_ModTest5,
new Type[] { typeof(OpenMetaverse.Vector3) },typeof(OpenMetaverse.Vector3));
m_comms.RegisterScriptInvocation("ModTest6",SI_ModTest6,
new Type[] { typeof(OpenMetaverse.Quaternion)},
typeof(OpenMetaverse.Quaternion));
m_comms.RegisterScriptInvocation("ModTest7",SI_ModTest7,
new Type[] { typeof(int), typeof(string) },typeof(object[]));
m_comms.RegisterScriptInvocation("ModTest8",SI_ModTest8,
new Type[] { typeof(object[]) },typeof(object[]));
}

public Type ReplaceableInterface
{
get { return null; }
}

#endregion

#region ScriptInvocationInteface
protected object SI_ModTest0(UUID scriptID, object[] parray)
{
return "";
}

protected object SI_ModTest1(UUID scriptID, object[] parray)
{
string value = (string)parray[0];
return value;
}

protected object SI_ModTest2(UUID scriptID, object[] parray)
{
int value = (int)parray[0];
return value;
}

protected object SI_ModTest3(UUID scriptID, object[] parray)
{
float value = (float)parray[0];
return value;
}

protected object SI_ModTest4(UUID scriptID, object[] parray)
{
UUID value = (UUID)parray[0];
return value;
}

protected object SI_ModTest5(UUID scriptID, object[] parray)
{
OpenMetaverse.Vector3 value = (OpenMetaverse.Vector3)parray[0];
return value;
}

protected object SI_ModTest6(UUID scriptID, object[] parray)
{
OpenMetaverse.Quaternion value = (OpenMetaverse.Quaternion)parray[0];
return value;
}

protected object SI_ModTest7(UUID scriptID, object[] parray)
{
int count = (int)parray[0];
string val = (string)parray[1];

object[] result = new object[count];
for (int i = 0; i < count; i++)
result[i] = val;

return result;
}

protected object SI_ModTest8(UUID scriptID, object[] parray)
{
object[] lparm = (object[])parray[0];
object[] result = new object[lparm.Length];

for (int i = 0; i < lparm.Length; i++)
result[lparm.Length - i - 1] = lparm[i];

return result;
}

#endregion
}
}
</source>

The module registers functions through the IScriptModuleComms RegisterScriptInvocation() method. This method takes the name of the function, an invocation delegate, an array of types used to validate parameters to the function, and a return type.

The functions in the region module can assume that the parameters passed through the argument array match the signature that was registered. That is, the function in the region module does not need to perform any kind of type checking.

== The In-world Script ==

Here's the in-world script that calls the functions defined in the region module.

<source lang="lsl">
default
{
state_entry()
{
llSay(0, "Script running");
llOwnerSay("ModTest0: " + ModTest0());
llOwnerSay("ModTest1: " + ModTest1("one"));

integer v2 = ModTest2(2) + 2;
llOwnerSay("ModTest2: " + (string)v2);

float v3 = ModTest3(3.14) + 4.56;
llOwnerSay("ModTest3: " + (string)v3);

key v4 = ModTest4(llGetKey());
llOwnerSay("ModTest4: " + (string)v4);

vector v5 = ModTest5(llGetPos());
llOwnerSay("ModTest5: " + (string)v5);

rotation v6 = ModTest6(llGetRot());
llOwnerSay("ModTest6: " + (string)v6);

list v7 = ModTest7(5,"hello");
llOwnerSay("ModTest7: " + (string)llGetListLength(v7));
llOwnerSay("ModTest7: " + llList2CSV(v7));

list v8 = ["a", 1, llGetKey(), llGetPos(), llGetRot()];
list v9 = ModTest8(v8);
llOwnerSay("ModTest8: " + (string)llGetListLength(v9));
llOwnerSay("ModTest8: " + llList2CSV(v9));

}
}
</source>
[[Category:Scripts]]

OSSL Script Library/ModInvoke

2012-03-25T05:30:32Z

Cmickeyb: /* The In-world Script */

OSSL Script Library/ModInvoke

2012-03-15T20:54:41Z

Cmickeyb: /* The Region Module */

OSSL Script Library/ModInvoke

2012-03-15T20:53:50Z

Cmickeyb: /* The Region Module */

OSSL Script Library/ModInvoke

2012-03-15T20:53:00Z

Cmickeyb: Created page with "You can invoke functions defined in a region module from a script using the modInvoke() family of functions. == Enabling modInvoke() == The first thing is to enable modSendCom..."

OSSL Implemented

2009-03-08T05:17:05Z

Cmickeyb:

{| border=1 style="border-collapse:collapse;th background-color:#666;width:100%;text-align:left;"
! style="background-color:#D2ECD2;" | Function
! style="background-color:#D2ECD2;" | Explanation
! style="background-color:#D2ECD2;" | Examples
! style="background-color:#D2ECD2;" | Threat Level
|-
| string osSetDynamicTextureURL(string dynamicID, string contentType, string url, string extraParams, int refreshTimer);
| Loads a web texture on a prim. Should work for any image URL (including php scripts) that Opensim can render. [Note refreshTimer may not yet be implemented, use a timer event and recall the function to get the same effect]
| [[osSetDynamicTextureURL_example1|example 1]]
[[osSetDynamictextureURL_example2|example 2]]
| VeryLow
|-
|-
| osSetDynamicTextureData("", "vector", drawList, "1024", 0);
| Writes text and vector graphics onto a prim face. See list of implemented [[OSSL_TextureDrawing|Functions]]. NOTE:As of r8206 (above v0.6.2) width,height and alpha value can be passed e.g. osSetDynamicTextureData("", "vector", drawList, "width:64,height:1024:alpha:0", 0);
To turn off the alpha layer completely use "alpha:false" in the optional parameters
| [[osSetDynamicdata_example1|example 1]]
| VeryLow
|-
| double osTerrainGetHeight(int x, int y);
| Gets height of terrain
|
| None
|-
|-
| int osTerrainSetHeight(int x, int y);
| Sets height of terrain
|
| High
|-
|-
| int osRegionRestart(double seconds);
| Restarts the region
|
| High
|-
|-
| void osRegionNotice(string msg);
| Sends a notice to the region
|
| VeryHigh
|-
|-
| System.Collections.Hashtable osParseJSON(string JSON);
| returns a hashtable containing the structured JSON contents (c# only)
| [[osParseJSON_example1|example 1]]
| None
|-
|-
| osMessageObject(key objectId, string message);
| sends a string to the object identified by objectId, the receiving object requires to implement the method dataserver( key queryid, string data ) in a contained script(s). The queryid passed will be the id of the calling object.
|
| Low
|-
|-
| osTeleportAgent(key agentId, string regionName, vector position, vector lookAt);
| Teleports agent ''agentId'' to region ''regionName'', region-local position ''position'', with looking direction ''lookAt'' without asking the user first (in contrast to ''llMapDestination''). This function works only in scripts '''owned by''' the region's master-avatar.
|
| High
|-
|-
| osTeleportAgent(key agentId, vector position, vector lookAt);
| Teleports agent ''agentId'' to position ''position'' in the same region, with looking direction ''lookAt'' without asking the user first (in contrast to ''llMapDestination''). This function works only in scripts '''owned by''' the region's master-avatar.
|
| High
|-
|-
| osConsoleCommand(string command);
| Issues command as if from the server console. "Severe" threat level. Eg.: osConsoleCommand("link-region X Y URL port").
|
| Severe
|-
|-
| osMakeNotecard(string cardname, list cardlines);
| Writes a new notecard into the containing prim's inventory. The list parameter may contain only strings. Eg.: osMakeNotecard("new card", ["line-1", "line-2", "line-3"]).
|
| High
|-
|-
| string osGetGridNick();
| Return the nick name of the grid as per the config .ini file.
|
| Moderate
|-
|-
| string osGetGridName();
| Return the name of the grid as per the config .ini file.
|
| Moderate
|-
|-
| string osGetGridLoginURI();
| Return the Login URI of the grid as per the config .ini file.
|
| Moderate
|-
|-
| string osFormatString(string format, list params);
| Return the string with parameters substituted into it (format comes from .NET String.Format class) in . Parameters are specified positionally. Example: llOwnerSay(osFormatString("{0}: pos is {1}",[llGetName(), llGetPos()]));
|
| Low
|-
|-
| list osMatchString(string source, string pattern);
| Return a list of matches for the pattern and its components inside the source string. The pattern is a regular expression with syntax defined by the .NET Regex class. Each match in the result is the string that matched and its position in the source.
|
| Low
|-
|-
[[Category:Users]]
[[Category:Development]]

Second Birthday

2009-01-29T16:22:13Z

Cmickeyb: Added ScienceSim blog entry

[[Image:OpenSim_2nd_Birthday_Banner.png]]

== History ==
The consensus is that OpenSim was 'born' on Jan 29 2007, when Darren Guard (MW) made his prototypical c# 3D world server publicly available. Help us celebrate this joyous occasion! Read [[History]] for some recap of the early days.

== Activities ==
Here you can add your activity, sorted by starting time GMT. Please supply at least basic information (when it starts, ends, what happens and how to get there). Also, if the activity takes place in a public hypergrid location, feel free to add link-region information so that others can link to your region.

Consider announcing your party on the opensim-users mailing list.

=== Jan 28 2009 ===
{| border="1" cellpadding="5" cellspacing="0" align="center"
!When? (GMT)
!When? (Local Time)
!Duration
!What?
!Where?
!How do I get there?
![[Hypergrid|link-region server and port]]
|-
|9:00pm
|1:00pm (PST)
|90 minutes
|Foolish Frost live from the Cornfield
|Rezzable Private Grid Alpha
|[http://rezzable.com/blog/vint-falken/opensim-2nd-birthday-celebration-foolish-frost-live-cornfield Instructions for existing & new accounts.]
|Non-hypergrid. (for now)
|}

=== Jan 29 2009 ===
{| border="1" cellpadding="5" cellspacing="0" align="center"
!When? (GMT)
!When? (Local Time)
!Duration
!What?
!Where?
!How do I get there?
![[Hypergrid|link-region server and port]]
|-
|9:00pm (GMT)
|10:00pm (Local Time)
|3 hours
|Presentation of Cyberlandia (Italian) grid, ((((Welcome areas, outstanding building architecture tour and Dancing Party for everybody))))
|www.cyberlandia.net www.opensimita.org
| "Born To Learn" and "Cyberlandia" sims. At entry point will find agenda and landmark givers. NB: due to severe instability problems we experienced in latest days we are not sure the event can take place without problems... The enthusiasm of the builders did provoke crashes on the land. If this is going to happen again this evening, please consider to use also the IRC channel on freenet (#cyberlandia) or going to web client http://www.cyberlandia.net/index.php?&page=smodul&id=17&btn=17 . When we will find the origin of the inconsistencies and solve the problems (probably posting some mantis), we will reschedule the presentation again. People interested in the Italian Cyberlandia project can also try to join the http://tinyurl.com/opensimita skype channel where people is connected during European day and evening/night.
|[[Hypergrid|grid.cyberlandia.net:8002]]
|-
|20:00pm (GMT)
|21:00pm (Local Time)
|2+ hours
|Game over for SL - Dark musix party, lottery and more. switch to night before enterering.
|www.schwarze-welle.de www.osgrid.org
| SCHWARZE WELT and surounding regions in osgrid
|[[Hypergrid|87.230.89.74:9000]]
|-
|14:00pm (GMT)
|6:00am (PST)
|1 hour
|Introduction to Building - learn to build in OpenSim
|http://reactiongrid.com
| ReactionGrid Welcome Sim will have all markers and directions to which sims for each of the events.
|[[Hypergrid|http://gsquared.info:8008]]
|-
|21:00pm (GMT)
|13:00pm (PST)
|1 hour
|Introduction to Building - repeated for west coast and those who could not make it to the earlier class
|http://reactiongrid.com
| ReactionGrid Welcome Sim will have all markers and directions to which sims for each of the events.
|[[Hypergrid|http://gsquared.info:8008]]
|-
|20:15pm (GMT)
|21:15pm (UTC+1) (France time)
|2 hours
|Live Concert by Bell Clellon (1 hour)

OpenMusic, OpenMinds (1 hour)
|New World Grid
* English : http://www.newworldgrid.com/lang/en-us/register
* Français : http://www.newworldgrid.com/lang/fr/register
| Events will take place at the Sunshine region. Prefer login to Welcome or Faelwen region to avoid avatar overload. You will redirected there ;)

Two events :
* First, a live concert by Bell Clellon (about 1 hour)
* Second, a "OpenMusic, OpenMinds" mix party : broadcasting of Creative Commons music from Jamendo.com artists. OpenSim is Open, let the music be it too :D

Blog : http://www.newworldgrid.com/os2b (EN/FR)
|No hypergrid access yet :D
|}

=== Jan 30 2009 ===
{| border="1" cellpadding="5" cellspacing="0" align="center"
!When? (GMT)
!When? (Local Time)
!Duration
!What?
!Where?
!How do I get there?
![[Hypergrid|link-region server and port]]
|-
|21:00pm (GMT)
|13:00pm (PST)
|1 hour
|Particle Madness - learn to make your own particle effects
|http://reactiongrid.com
| ReactionGrid Welcome Sim will have all markers and directions to which sims for each of the events.
|[[Hypergrid|http://gsquared.info:8008]]
|-
|22:00pm (GMT)
|14:00pm (PST)
|1 hour
|1939 World's Fair weekly meeting, 22:00-23:00 UTC - anyone interested in learning more and possibly participating in the reconstruction project are more than welcome to come along!
|http://reactiongrid.com
| 39FairHQ sim
|[[Hypergrid|http://gsquared.info:8008]]
|}

=== Jan 31 2009 ===
{| border="1" cellpadding="5" cellspacing="0" align="center"
!When? (GMT)
!When? (Local Time)
!Duration
!What?
!Where?
!How do I get there?
![[Hypergrid|link-region server and port]]
|-
|16:00pm (GMT)
|8:00am (PST)
|1 hour
|Creating Prim Hair - learn to make your prim hair
|http://reactiongrid.com
| ReactionGrid Welcome Sim will have all markers and directions to which sims for each of the events.
|[[Hypergrid|http://gsquared.info:8008]]
|-
|22:00pm (GMT)
|14:00pm (PST)
|til late night
|Mega Fright Night - public domain movies streamed to Reactiongrid - sit in an old time car (drive in style) or pop a squat on a tomato and pitch tomatoes at the screen and scream. A real fun time and we are planning to keep this running all night long - among movies you will see Gila Monster, House on Haunted Hill, and many more
|http://reactiongrid.com
| Tarzan sim - directions and more at Welcome sim entrance or just head to Tarzan sim and join in!
|[[Hypergrid|http://gsquared.info:8008]]
|}

=== Jan 31 - Feb 1 2009 ===
{| border="1" cellpadding="5" cellspacing="0" align="center"
!When? (GMT)
!When? (Local Time)
!Duration
!What?
!Where?
!How do I get there?
![[Hypergrid|link-region server and port]]
|-
|24:
|24:
|48 hours
|Sailing Regatta - Live Music DJ's - Hypergrid - freebies
|[[OSGrid]]
|http://simzee.com/event.html
|OSGrid, M1 Rock (42, 96, 25)
|}

=== Feb 3 2009 ===
{| border="1" cellpadding="5" cellspacing="0" align="center"
!When? (GMT)
!When? (Local Time)
!Duration
!What?
!Where?
!How do I get there?
![[Hypergrid|link-region server and port]]
|-
|20:00pm (GMT)
|12:00pm (PST)
|1 hour
|Photoshop CS3 for Textures
|http://reactiongrid.com
| ReactionGrid Welcome Sim will have all markers and directions to which sims for each of the events.
|[[Hypergrid|http://gsquared.info:8008]]
|-
|21:00pm (GMT)
|13:00pm (PST)
|1 hour
|Avatar Clothing Tutorial
|http://reactiongrid.com
| ReactionGrid Welcome Sim will have all markers and directions to which sims for each of the events.
|[[Hypergrid|http://gsquared.info:8008]]
|}

== Demos and Exhibits ==
Here you can add your ongoing demo and/or interesting content. Please supply a brief description of the demo and/or content. Also, if the activity takes place in a public hypergrid location, feel free to add link-region information so that others can link to your region.

{| border="1" cellpadding="5" cellspacing="0" align="center"
!Title
!Description
!Location
![[Hypergrid|link-region server and port]]

|-
|Urban Planning modules
|Traffic and pedestrian simulations in the UCI Grid, provided by [http://encitra.com/ Encitra].
|UCI Grid. Go to Gateway 7000 and use the teleporter for UCI Campus (1,1). Or link to it directly, using the info on the right.
|ucigrid01.nacs.uci.edu:9000 (centered in the 8000's)

|-
|Metaverse Illuminations Gallery
|Large gallery of high-quality Second Life documentary photography
|OSGrid: Snoopies/21/15/521 (skybox) manual link: secondlife://Snoopies/21/15/521
|(not sure!)

|-
|German welcome area
|Informationen fuer deutsche Newbies im Osgrid, Freebies in Sharkland Hills, Mitbauer willkommen, Mietregionen
|OSGrid, Sharkland Tropical 3
|regionsDE.ralf-haifisch.biz:9000

|-
|OpenSim Dutchies
|Mostly empty, but if you're lucky you catch me there for some information about interconnectivity between webinterface and virtual world, using wixtd and OpenSim
|OSN Grid
|os-networks:9000

|-
|Pseudospace - Ellis Island Welcome Center & Telehub
|Pop on by and enjoy a slice of open sourced birthday cake and punch in our lobby! Feel free to look around and explore some of the different roleplay environments we're working on and help yourself to some freebies from our content library. All sims on the grid are HyperGrid enabled so no need to worry about becoming stranded if you teleport off of Ellis Island. :)
|Pseudospace
|ellis.pseudospace.net:9000
centered at 9000,9000

|-
|OpenSimulator-Club
|Club (german language) for upcoming OpenSimulator and 3D-Internet activities. Founded to support the OpenSimulator 2nd birthday event.
| 
|http://www.talentraspel.de/index.php?option=com_content&view=article&id=53&Itemid=72

|-
|3D-Internet TV
|Web-TV channel (german language) covering news and developments for 3D-Internet activities. The OpenSimulator 2nd birthday event will be reported too.
| 
|http://www.talentraspel.de/index.php?option=com_wrapper&view=wrapper&Itemid=105

|-
|Schwarze Welle
|Club and Shops (german/english) , 3D representation of www.schwarze-welle.de dark music radio. every monday german osgrid meeting 20:00 at next region SCHWARZE WELT
|OSGrid, SCHWARZE WELT
|87.230.89.74:9000

|-
|Open Vue
|Virtual University of Edinburgh on Opensim hosted on the Virtual AIAI Grid
| 
|http://vue.ed.ac.uk/openvue/

|-
|Folk Cate Delta
|Edy Rau's Folk Cafe(german/english) , every thursday 1 to 2 hours live musicans. 20 MET (11 PST)
|Grid4Us, Folk Cafe Delta
|http://grid4us.net:9020 (centered to 8500, 8500)
|
|-
'''|Sim-OnDemand'''''Italic text''
|Virtual world Abundance. Use robust Amazon EC2 infrastructure to run OpenSim server. GUI based EC2 launcher( No need to know EC2 API). Pay only for what you use. Very useful for occasional and experimentation with OpenSim.
|
|http://simondemand.ec29.com/index.html
|}

== Blog Entries ==
Keep a list of the 2nd Birthday Blog Entries here:
* [http://opensimulator.info/article.php/Opensim-Les-anniversaires Happy 2nd birthday Opensimulator]
* [http://www.cybertechnews.org/?p=529 CyberTech News blog post]
* [http://xyzzyxyzzy.net/2009/01/29/happy-2nd-birthday-opensim/ happy 2nd birthday opensim (xyzzyxyzzy.net)]
* [http://blogs.intel.com/research/2009/01/sciencesim.php ScienceSim on Research@Intel]

== Resources ==

=== Hypergrid Bridges ===

To bridge between grids in the 1000's and grids in the 10,000's, you can use 2 gateways in the UCI Grid:

* Gateway 3000, placed in position 3,000 3,000: ucigrid04.nacs.uci.edu 9003
* Gateway 7000, placed in position 7,000 7,000: ucigrid04.nacs.uci.edu 9007

=== Banners ===
This banner is suitable for inclusion on your own web page, in blogs et c:

[[Image:OpenSim_2nd_Birthday_Banner.png]]

(Courtesy [http://www.vintfalken.com Vint Falken])

=== Invitation Card ===
This image is suitable for creating your own invitation notecards:

[[Image:OpenSim_Second_Birthday_Note.png]]

(Courtesy [http://www.vintfalken.com Vint Falken])

Public Hypergrid Nodes

2009-01-28T07:26:18Z

Cmickeyb:

The following is a list of hypergrid-ready nodes that you can use for testing your installation and for linking your world. Please add your public node here if you wish to help build a web of opensims!

For the time being, and until the security concerns are addressed, we advise you to be careful about who you link to.

{| border="1" cellpadding="5" cellspacing="0" align="center"
![[Hypergrid|link-region server and port]]
!Organization
!Description
!Grid Location
|-
|'''osl2.nac.uci.edu 9006'''
|University of California, Irvine
|The "UCI Welcome" region connected to OSGrid. It is run by Diva (Crista Lopes) on a machine owned by the University of California, Irvine. You can link to it as a way to link to OSGrid.
|OSGrid is centered at 10,000, 10,000

|-
|'''osl3.nac.uci.edu 9000'''
|University of California, Irvine
|The "UC Irvine" region connected to OSGrid, neighboring Wright Plaza. You can link to it as a way to link to OSGrid.
|OSGrid is centered at 10,000, 10,000

|-
|'''ucigrid02.nacs.uci.edu 9000'''
|University of California, Irvine
|The UCI Grid
|UCIGrid is centered at 8,888, 8,888

|-
|'''ucigrid04.nacs.uci.edu 9003'''
|University of California, Irvine
|The UCI Grid, region "Gateway 3000". Link your lower-1,000's grid to this node in order to bridge to grids in the 10,000's.
|This node is positioned at 3,000, 3,000

|-
|'''ucigrid04.nacs.uci.edu 9007'''
|University of California, Irvine
|The UCI Grid, region "Gateway 7000". Link your 10,000's grid to this node in order to bridge to grids in the lower-1,000's.
|This node is positioned at 7,000, 7,000.

|-
|'''grid.cyberlandia.net 9000'''
|Cyberlandia
|The "Cyberlandia Gw" region. http://www.cyberlandia.net Metaverso italiano 3D, more to 250 region and 1000 users. You can link to it as a way to link to Cyberlandia.
|Cyberlandia is centered at ???

|-
|'''hypergrid.cyberlandia.net 9000'''
|Cyberlandia
|The "Osgrid Gw" region connected to Cyberlandia grid http://www.cyberlandia.net. Search on map "Cyberlandia grid" You can link to it as a way to link to OSGrid.
|OSGrid is centered at 10,000, 10,000

|-
|'''regionsde.ralf-haifisch.biz 9045'''
|Ralf Haifisch on osgrid
|The "Sharkland Tropical" region connected to OSGrid. German welcome aerea, Freebie aerea, region rental, pretty tropical regions
|Centered at 10000,10000

|-
|'''joomla-italia.net 9000'''
|Social Network Italia
|The "SNI City" region connected to SNI (Social Network Italia) grid http://www.opensim-italia.net. This grid is connected with Osgrid,Collateral World,Francogrid and Darwin
|Centered at ???

|-
|'''collateral.opensim-italia.net 9000'''
|Part of Social Network Italia
|Collateral World
|Centered at ???

|-
|'''88.191.79.199 9050'''
|Francogrid
|Francogrid node, connected to "City", behind the welcome land of Francogrid "Orion"
|Centered at 1000 1000

|-
|'''94.23.8.158 9999'''
|Le Monde de Darwin
|The Lost World of Darwin http://www.LeMondedeDarwin.com. [[Image:hypergrid.jpg|200px]]
|Centered at ???

|-
|'''grid.k-grid.com 9000'''
|K-Grid
|The Kool grid for the Kool KidZ . Feel free to visit us. The main Gateway is located at 3700,3700 so take that in account before any HyperJump
|This node is located at 3700,3700

|-
|'''metropolis.hypergrid.org 9000'''
|METROPOLIS-Grid
|The Region "Center-World" (at 1000:1000) connected to the METROPOLIS-Grid http://metropolis.hypergrid.org . German Grid with a lot of free Content and free SIM-hosting. Connected via HG to the most of the Grids listed here
|Centered at 1000,1000

|-
|'''ascent.bluewallgroup.com 9910'''
|BlueWall Group
|This region is in a good proximity @ (6000,6000) for intermediate jumps to OSGrid from grids in the (2000,2000) range, or any region within 4096 units. [[Image:Hypernaut 001.png|150px|none|thumb|Get your Hypernaut here :)]]
|Centered at 6000,6000

|-
|'''sim.thestudyofracialism.org 9000'''
|Backintyme Publishing
|TSOR1 is a stand-alone sim owned by Backintyme Publishing. It connects to most of the other downrange sites listed here. The sim is intended for an SL study/discussion group's eventual migration from SL to OS.
|Centered at 4000,4000

|-
|'''pc.backintyme.com 9100'''
|Backintyme Publishing
|TSOR2 is a small teleport relay island, also owned by Backintyme Publishing, intended for jumps to the vicinity of OSGrid. It is linked to most of the uprange sites listed here.
|Centered at 8000,8000

|-
|'''24.248.172.208 9003'''
|'''MyOpenGrid'''
|Myopengrid is connected to osl2.nac.uci.edu "Osgrid Gateway" and 88.191.79.199 9050 "Franco Grid"
|Centered at 7000,7000

|-
|'''cuonsim1.de 9300'''
|Cuon-Grid
|Cuon-Grid is a little grid and has some Main Sims with linux themes, server are in Germany. To login in to the grid use this http://sim-linuxmain.org:8081/CuonGrid/index.html. There are free sims for testing.
|Centered at 10,000, 10,000

|-
|'''metaversesims.net 9014'''
|Metaverse Sims
|Standalone mode - 6 regions - linked to several other grids. [[Image:Mtvs09010101.jpg|200px]]
|Centered at 9,000, 9,000

|-
|'''mecatreco.game-host.org 9002'''
|Villa Pelopes
|Two regions,one standalone server. Member of the [http://www.dmu.com Digital Media Universe], brazilian federation of independed hypergrided worlds: [[Image:Dmu.jpg|100px]]
| 1002 1002

|-
|'''ellis.pseudospace.net 9000'''
|Pseudospace Central Gateway & Welcome Center
|Pseudospace is a free to play, public access OpenSimulator grid created to provide role players with an immersive environment by which they may play, socialize, and build within. This is a mature grid which may contain adult content and situations, only those who are 18 or older may enter.

Please be advised, that we are currently under heavy construction. Feel free to look around, but mind the mess and the occasional flying prims! If you have any questions or concerns please feel free to email john(at)pseudospace(dot)net.

All user content such as skins, attachments, textures, etc. are provided for free using a share and share alike, create for the sake of creativity methodology. All such assets are kept within the content library on Ellis Island and are freely copyable / distributable unless the "No Transfer" option is enabled which simply means that the asset may not be copied off of the grid. Individual contributions to the grid's content library are greatly welcomed and may be done so by leaving a copyable box containing your contribution on one of the shelves located inside the Ellis Library.

| 9000 9000
|-
|-

|'''grid4us.net 9020'''
|Grid4Us
|German Grid that is linked to OSGrid and Francogrid.
|Centered at 8500,8500

|-
|'''gotz.ath.cx 9002'''
|Gotz
|One region,one standalone server. Visits: 9:00 PST -> 19:00 PST. Member of the
[http://www.dmu.com Digital Media Universe] , brazilian federation of independent hypergrided worlds:[[Image:Dmu.jpg|100px]]
| 1002 1002

|-
|'''villapileque.game-host.org 9002'''
|Villa Pileque
|One region,one standalone server. Member of the
[http://www.dmu.com Digital Media Universe] , brazilian federation of independent hypergrided worlds:[[Image:Dmu.jpg|100px]]
| 1002 1002

|-
|'''peak.sciencesim.com 9001'''
|ScienceSim
|[http://www.sciencesim.com/ ScienceSim] is a virtual world created for the high performance computing community for scientific visualizations, a number of interesting real world terrains (Mt St Helens and Yellowstone Park) and some astronomical simulations. And some useful, BSD-licensed content.
| Centered at 10000,10000

|}

Grid List/ScienceSim

2009-01-28T07:01:52Z

Cmickeyb: New page: <table border="1" cellpadding="5" cellspacing="0"> <tr> <td>Name:</td> <td>ScienceSim</td> </tr> <tr> <td>Website:</td> <td>http://www.sciencesim.com</td> </tr> <...

<table border="1" cellpadding="5" cellspacing="0">
<tr>
<td>Name:</td>
<td>ScienceSim</td>
</tr>
<tr>
<td>Website:</td>
<td>http://www.sciencesim.com</td>
</tr>
<tr>
<td>Login URI:</td>
<td>http://island.sciencesim.com:8002/</td>
</tr>
<tr>
<td>Wiki/Forum:</td>
<td>http://www.sciencesim.com/wiki</td>
<tr>
<td>Approx # Regions</td>
<td>~25</td>
</tr>
<tr>
<td>Approx # Users</td>
<td>~30</td>
</tr>
<tr>
<td>Logins/day</td>
<td>10</td>
</tr>
</table>

ScienceSim is a virtual world for the high performance computing community. The expectation is that scientists will create collaborative visualizations driven by various HPC simulations. ScienceSim is maintained by the IEEE/ACM SuperComputing conference committee.