Change Configuration File

15 March 2022

  • C11 - changed the semantics of the command to process lists of XPaths via CSV formatting.

11 March 2022

  • C11 - add proper namespace handling.

15 June 2018

  • C10 - the remove action parameter has been introduced.

2 April 2014

  • Release 7.93 - added the set and get options and removed the Base64 requirement.

14 December 2014

  • Release 7.28 - added.
configuration (Commands)
TypeCorrade progressive command
Commandconfiguration
DescriptionThe configuration command allows an authenticated group that has the system permission to read and write Corrade's configuration file.
Permissionssystem
Parametersgroup, password, action, namespace
Last ChangesC11 - add proper namespace handling.

The configuration command allows an authenticated group that has the system permission to read and write Corrade's configuration file. Note that when the configuration file is written to, Corrade reloads its configuration file automatically such that this command can be used to configure Corrade dynamically.

Command Required Parameters Required Corrade Permissions Example
configuration group, password, action, namespace system
llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            // read and return Corrade's 
            // configuration file as part
            // of the "data" return key
            "command", "configuration",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "read",
            "callback", wasURLEscape(URL)
        ]
    )
);
Parameter Value Secondary Parameters Description
action read Read the entire configuration file and pass it to the data key.
write data Write all the data passed through the data key to the configuration file.
get path, namespace Get the inner XML of a node specified by the XPath path.
set path, namespace Write the inner XML of a node specified by the XPath by value CSV contained in path to the configuration file.
remove path, namespace Remove a node specified by the XPath path

The get and set actions allow you to manipulate the XML nodes individually which eases the configuration of Corrade under size constraints (such as LSL). Both of them require two secondary parameters path that is an XPath to a node whose inner XML you wish to modify and namespace that is the default namespace for the XPath. set additionally takes an XML snippet and will replace the node specified by path with data.

Tutorials

The configuration command is very powerful and could be exactly the type of command you would need in order to create some shared-dynamic hosting of Corrade bots. The command gives you access to Corrade's configuration file, allowing you to get and set raw XML and set the value of any key in Corrade's configuration.

Selecting XML Nodes (Chunks of Data)

In some applications you may want to retrieve the currently configured groups as a chunk of XML and then process it. You could, for instance, select "the first group":

llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "configuration",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "get",
            "namespace", "x",
            "path", wasURLEscape(
                "/x:CorradeConfiguration/
                    x:Groups/
                        x:Group[1]"
            ),
            "callback", wasURLEscape(URL)
        ]
    )
);

which will return the inner-XML of the first group in the configuration.

Otherwise, to retrieve all the groups as an XML chunk, you would do:

llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "configuration",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "get",
            "namespace", "x",
            "path", wasURLEscape(
                "/x:CorradeConfiguration/
                    x:Groups"
            ),
            "callback", wasURLEscape(URL)
        ]
    )
);

which will return all the inner-XML inside the Groups tag:

<Group>
    <Name>One Group</Name>
    ...
</Group>
<Group>
    <Name>Wizardry and Steamworks</Name>
    ...
</Group>
<Group>
    <Name>Chocolat</Name>
    ...
</Group>

this XML can then be processed, modified and then updated by using the set action and passing the XML to the data key.

Querying Group Information

Since Corrade uses XML XPath semantics for get and set actions, it is possible to determine specific configuration keys for a given group. For instance, suppose that we wanted to whether group members should be cached via the option CacheMembers for a configured group named Wizardry and Steamworks. In order to do that, we would issue the command:

llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "configuration",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "get",
            "namespace", "x",
            "path", wasURLEscape(
                "/x:CorradeConfiguration/
                    x:Groups/
                        x:Group[x:Name='Wizardry and Steamworks']/
                            x:CacheMembers"
            ),
            "callback", wasURLEscape(URL)
        ]
    )
);

This command reads as: "select from root Configuration the Group sub-node and select the sub-sub-node Group where the Name tag is equal to Wizardry and Steamworks. The return to the callback will be a an integer that corresponds to the CacheMembers configured for the group Wizardry and Steamworks.

Let's say that we wanted to enable the CacheMembers setting now. We issue:

llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            "command", "configuration",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "set",
            "namespace", "x",
            // Set CorradeConfiguration -> Groups -> Wizardry and Steamworks -> CacheMebers to 1
            "path", wasListToCSV([
                wasURLEscape(
                    "/x:CorradeConfiguration/
                        x:Groups/
                            x:Group[x:Name='Wizardry and Steamworks']/
                                x:CacheMembers"
                ), 1
            ]),
            "callback", wasURLEscape(URL)
        ]
    )
);

which would perform the same steps to select the CacheMembers sub-sub-node of the Wizardry and Steamworks group and then set its value to 1.

Batch-Setting Values using Lists of XPaths

The actions set, get and remove all process CSV lists such that multiple changes can be performed in one go. For instance, the following command:

llInstantMessage(CORRADE,
    wasKeyValueEncode(
        [
            // query two configuration parameters
            // by x-path using a CSV list of paths
            "command", "configuration",
            "group", wasURLEscape(GROUP),
            "password", wasURLEscape(PASSWORD),
            "action", "get",
            "namespace", "x",
            "path", wasListToCSV([
                wasURLEscape("/x:CorradeConfiguration/x:Groups/x:Group[x:Name = '[Wizardry and Steamworks]:Support']/x:CacheMembers"), "0",
                wasURLEscape("/x:CorradeConfiguration/x:Range"), "99"
            ]),
            "callback", wasURLEscape(URL)
        ]
    )
);

will:

  • set CorradeConfiguration->Groups->the [Wizardry and Steamworks]:Support group->CacheMembers to 0
  • set CorradeConfiguration->Range to 99

secondlife/scripted_agents/corrade/api/commands/configuration.txt ยท Last modified: 2022/04/19 09:28 (external edit)

Access website using Tor Access website using i2p Wizardry and Steamworks PGP Key


For the copyright, license, warranty and privacy terms for the usage of this website please see the license, privacy, copyright and the plagiarism pages.