Second Life Wiki - User contributions [en]

Texture meta-data

2009-07-17T20:14:39Z

Phoenix Linden: Created page with 'On upload, [http://www.jpeg.org/public/fcd15444-1.pdf j2c textures] will have all CME segments in the main header removed to be replaced by a single CME segment. That segment wil...'

On upload, [http://www.jpeg.org/public/fcd15444-1.pdf j2c textures] will have all CME segments in the main header removed to be replaced by a single CME segment. That segment will be serialized as an unordered key-value url query string with the following keys and associated values.

;a:The agent_id of the resident that uploaded the texture.
;z:The utc time the texture was uploaded in '''YYYYmmddHHMMSS''' [http://www.python.org/doc/2.5.2/lib/module-time.html format].
;w:The original width of the image as reported by the viewer. This value must be interpretable as an integer greater than 0 and less than 1,000,000.
;h:The original height of the image as reported by the viewer. This value must be interpretable as an integer greater than 0 and less than 1,000,000.
;c:The average color of the image as calculated during verification. The value will be '''RRGGBBAA''' in hex with 00 being none and ff representing full saturation of that component. If the image only has three components, then alpha is set to ff. If there are more than four components, the extra components are skipped.

== example ==
The actual encoded comment string will look something like:

<pre>
a=abbee3b5-fbe0-4cfa-8d15-323d6800448e&h=480&w=640&z=20081118204138&c=26961aff
</pre>

== tool support ==
The <code>j2c_comments.py</code> script understands j2c codestream CME markers and will parse for them in the main header. To use it, pass a list of j2c codestream file names on the command line. The script will emit the file name parsed and report on comments found for each. If the example above is in test.texture, the session would look something like:

<pre>
$ ./j2c_comments.py test.texture
test.texture: {
'a':['abbee3b5-fbe0-4cfa-8d15-323d6800448e'],
'h':['480'],
'w':['640'],
'z':['20081118204138'],
'c':['26961aff']}
</pre>

The tool will emit error messages if the codestream could not be understood, or if the comment is not latin1. Comments which do not conform to the query string format will be treated as a plain, raw latin1 string.

=== j2c_comments.py ===

<pre>
#!/usr/bin/env python
"""
Extract out all of the j2c CME markers
"""

import cgi
import optparse
import struct

class NotJ2C(Exception):
pass

def parse_cme(filename):
j2c = file(filename, 'rb')
comments = None
while True:
marker_bytes = j2c.read(2)
marker, marker_type = struct.unpack('BB', marker_bytes)
if marker != 0xff:
raise NotJ2C
if marker_type == 0x90:
# we found the SOT, so we're done.
return comments
elif marker_type == 0x4f:
# this is SOC, which does not have a lsoc element
continue
size_bytes = j2c.read(2)
size = struct.unpack('!H', size_bytes)[0] - 2

if marker_type == 0x64:
# found a CME. read it, and interpret it.
rcme = j2c.read(2)
rcme = struct.unpack('!H', rcme)[0]
if rcme == 0:
new_comment = '<binary>'
elif rcme == 1:
raw_comment = j2c.read(size - 2)
new_comment = cgi.parse_qs(raw_comment)
if len(new_comment) == 0:
new_comment = raw_comment
else:
new_comment = '<unknown>'

if comments is None:
comments = new_comment
elif type(comments) == 'list':
comments.append(new_comment)
else:
comments = [comments, new_comments]
continue

j2c.seek(size, 1)
continue

def main():
parser = optparse.OptionParser(
usage="usage: %prog [options] file_list",
description="Read through file list and extract the CME field")
options, args = parser.parse_args()
if len(args) < 1:
parser.error("Please specify one or more files to assign.")
for filename in args:
try:
comments = parse_cme(filename)
print filename + ': ' + str(comments)
except NotJ2C:
print filename + ': Unable to parse file'

if __name__ == "__main__":
main()
</pre>

[[Category:Assets]]

Textures (OS)

2009-07-17T20:11:07Z

Phoenix Linden: /* Functional Spec */

{{OSWikiFeatureNav}}
=== Feature Design Document ===
(none)

=== Functional Spec ===
File format details are available in annex A of [http://www.jpeg.org/public/fcd15444-1.pdf JPEG 2000 Part I Final Committee Draft Version 1.0].

Second Life treats jpeg 2000 codestreams as MIME type image/x-j2c. The image/j2c MIME type include extra packing data which was not finalized when Second Life first opened.

As of version 1.27 of the Second Life server, uploaded textures contain [[texture meta-data]] in the jpeg 2000 CME sections.

=== Test scripts ===
[[Texture Test]]

[[Edit Object Texture Test]]

[https://osiris.lindenlab.com/mediawiki/index.php/Texture_Pipeline_Performance_test Texture_Pipeline_Performance_test internal test]

[https://osiris.lindenlab.com/mediawiki/index.php/Texture_Pipeline_Quality_test Texture_Pipeline_Quality_test internal test]

=== Discussion for future improvements ===
[[Texture Console]]

=== Relationship to other features ===
<b> List of features that need to be tested when this feature changes, and why. </b>

[https://osiris.lindenlab.com/mediawiki/index.php/Render_Performance_Test internal test]

[[Uploading Assets]] - You can only upload textures of a certain format and size.

=== User Guides ===
* [http://robinwood.com/Catalog/Technical/SL-Tuts/SLTutSet.html Texture Tutorials by Robin Sojourner]

Patch TUT

2009-06-29T17:27:10Z

Phoenix Linden: /* TUT-2008-11-30 */

Our unit test framework did not have any method for skipping tests. Sometimes known failure cases are found which require temporarily skipping tests. This patch adds that functionality.

= TUT-2006-11-04 =
'''WARNING''': This is a patch to a pretty old version of tut, but currently the version in use.

<pre>
--- tut-orig/tut.h 2007-05-23 16:37:00.000000000 -0700
+++ tut-new/tut.h 2007-05-23 16:40:18.000000000 -0700
@@ -79,6 +79,15 @@
};

/**
+ * Exception to be throwed when skip_fail() is called.
+ */
+ class skip_failure : public std::logic_error
+ {
+ public:
+ skip_failure(const std::string& msg) : std::logic_error(msg){};
+ };
+
+ /**
* Exception to be throwed when test desctructor throwed an exception.
*/
class warning : public std::logic_error
@@ -120,8 +129,20 @@
* ex - test throwed an exceptions
* warn - test finished successfully, but test destructor throwed
* term - test forced test application to terminate abnormally
+ * skip - test skipped
+ * skip_fail - test skpped because it is a known failure case
*/
- typedef enum { ok, fail, ex, warn, term, ex_ctor } result_type;
+ typedef enum
+ {
+ ok,
+ fail,
+ ex,
+ warn,
+ term,
+ ex_ctor,
+ skip,
+ skip_fail,
+ } result_type;
result_type result;

/**
@@ -168,7 +189,7 @@

// execute tests iteratively
virtual void rewind() = 0;
- virtual test_result run_next() = 0;
+ virtual test_result run_next(int skip_test_id = 0) = 0;

// execute one test
virtual test_result run_test(int n) = 0;
@@ -316,7 +337,7 @@
/**
* Runs all tests in specified group.
*/
- void run_tests(const std::string& group_name) const
+ void run_tests(const std::string& group_name, int skip_test_id = 0) const
{
callback_->run_started();

@@ -328,7 +349,7 @@

try
{
- run_all_tests_in_group_(i);
+ run_all_tests_in_group_(i, skip_test_id);
}
catch( const no_more_tests& )
{
@@ -371,12 +392,13 @@
}

private:
- void run_all_tests_in_group_(const_iterator i) const
+ void run_all_tests_in_group_(const_iterator i, int skip_test_id = 0) const
{
i->second->rewind();
for( ;; )
{
- test_result tr = i->second->run_next();
+ test_result tr = i->second->run_next(skip_test_id);
+
callback_->test_completed(tr);

if( tr.result == test_result::ex_ctor )
@@ -436,13 +458,11 @@
}
};

- namespace
- {
/**
* Tests provided condition.
* Throws if false.
*/
- void ensure(bool cond)
+ inline void ensure(bool cond)
{
if( !cond ) throw failure("");
}
@@ -511,10 +531,19 @@
/**
* Unconditionally fails with message.
*/
- void fail(const char* msg="")
+ template <class T>
+ void fail(const T msg)
{
throw failure(msg);
}
+
+ /**
+ * Unconditionally fails with message.
+ */
+ template <class T>
+ void skip_fail(const T msg)
+ {
+ throw skip_failure(msg);
}

/**
@@ -705,7 +734,7 @@
/**
* Runs next test.
*/
- test_result run_next()
+ test_result run_next(int skip_test_id = 0)
{
if( current_test_ == tests_.end() )
{
@@ -718,8 +747,17 @@
{
try
{
+ if (current_test_->first == skip_test_id)
+ {
+ test_result tr(name_,current_test_->first,test_result::skip);
+ current_test_++;
+ return tr;
+ }
+ else
+ {
return run_test_(current_test_++,obj);
}
+ }
catch( const no_such_test& )
{
continue;
@@ -774,6 +812,12 @@
test_result tr(name_,ti->first,test_result::fail,ex);
return tr;
}
+ catch(const skip_failure& ex)
+ {
+ // test failed because of ensure() or similar method
+ test_result tr(name_,ti->first,test_result::skip_fail,ex);
+ return tr;
+ }
catch(const seh& ex)
{
// test failed with sigsegv, divide by zero, etc
</pre>

Save this patch as tut.patch in the same directory as tut.h and apply it from a terminal program like xterm or cygwin with the command:

<pre>
$ patch -p1 < tut.patch
</pre>

= TUT-2008-11-30 =
Internally, TUT has been migrated to the 2008-11-30. This patch will not work against the current code, but is expected to be in use soon.

<pre>
--- tut.orig/tut_assert.hpp 2008-12-05 17:35:10.000000000 -0800
+++ tut.new/tut_assert.hpp 2008-12-05 17:37:56.000000000 -0800
@@ -154,9 +154,23 @@
throw failure(msg);
}

+/**
+ * Skip test because of known failure.
+ */
+void skip(const char* msg = "")
+{
+ throw skip_failure(msg);
+}
+
+void skip(const std::string& msg)
+{
+ throw skip_failure(msg);
+}
+
} // end of namespace

}

+
#endif

diff -u tut.orig/tut_exception.hpp tut.new/tut_exception.hpp
--- tut.orig/tut_exception.hpp 2008-12-05 17:35:10.000000000 -0800
+++ tut.new/tut_exception.hpp 2008-12-05 17:37:56.000000000 -0800
@@ -201,6 +201,26 @@
const test_result tr;
};

+/**
+ * Exception to be throwed when skip_fail() is called.
+ */
+struct skip_failure : public failure
+{
+ skip_failure(const std::string& msg)
+ : failure(msg)
+ {
+ }
+
+ test_result::result_type result() const
+ {
+ return test_result::skip;
+ }
+
+ ~skip_failure() throw()
+ {
+ }
+};
+
}

#endif
diff -u tut.orig/tut_result.hpp tut.new/tut_result.hpp
--- tut.orig/tut_result.hpp 2008-12-05 17:35:10.000000000 -0800
+++ tut.new/tut_result.hpp 2008-12-05 17:37:56.000000000 -0800
@@ -51,6 +51,7 @@
* ex - test throwed an exceptions
* warn - test finished successfully, but test destructor throwed
* term - test forced test application to terminate abnormally
+ * skip - test skpped because it is a known failure case
*/
enum result_type
{
@@ -60,7 +61,8 @@
warn,
term,
ex_ctor,
- rethrown
+ rethrown,
+ skip,
};

result_type result;

</pre>

Save this patch as <code>tut.patch</code> in the <code>tut-2008-11-30/tut</code> directory - alongside the <code>tut_assert.hpp</code>, <code>tut_exception.hpp</code>, and <code>tut_result.hpp</code> files - and apply it from a terminal program like xterm or cygwin with the command:

$ patch -p1 < tut.patch

Patch TUT

2009-06-29T17:25:50Z

Phoenix Linden: /* TUT-2008-11-30 */

Eventlet

2009-04-16T17:00:48Z

Phoenix Linden: /* Releases */

= Eventlet =

Eventlet is a networking library written in Python. It achieves high scalability by using [http://en.wikipedia.org/wiki/Non-blocking_IO#Select.28.2Fpoll.29_loop non-blocking io] while at the same time retaining high programmer usability by using [http://en.wikipedia.org/wiki/Coroutine coroutines] to make the non-blocking io operations appear blocking at the source code level.

* Example code: [[Eventlet/Examples]]
* PyPI entry: http://pypi.python.org/pypi/eventlet/
* Subversion repository: http://svn.secondlife.com/svn/eventlet
* Mercurial (hg) repository: http://www.donovanpreston.com:8888/eventlet
* Trac page: http://svn.secondlife.com/trac/eventlet
* Mailing list: https://lists.secondlife.com/cgi-bin/mailman/listinfo/eventletdev

== Documentation ==

[[Eventlet/Documentation]]

== Releases ==

{| cellpadding="6"
|-
| '''Name''' || '''Date''' || '''URL'''
|-
| 0.8 || 2008-10-13 || http://pypi.python.org/pypi/eventlet/0.8/
|-
| 0.7 || July 29, 2008 || http://pypi.python.org/pypi/eventlet/0.7
|-
| 0.6.1 || July 7, 2008 || http://pypi.python.org/pypi/eventlet/0.6.1
|-
| beta-1 || Aug 24, 2007 || [http://svn.secondlife.com/trac/eventlet/changeset/8/branches/beta-1?old_path=%2F&format=zip] [http://svn.secondlife.com/svn/eventlet/branches/beta-1]
|}

== Requirements ==

Eventlet runs on Python version 2.3 or greater, with the following dependencies:
* [http://cheeseshop.python.org/pypi/greenlet greenlet]
* [http://pyopenssl.sourceforge.net/ pyOpenSSL] if you want to use ssl sockets
* (if running python versions < 2.4) a deque object in a <code>collections</code> module. One option is to copy [http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/259179 this deque] into a file called <code>collections.py</code>.

== Eventlet at Linden ==

eventlet is the networking library used to implement the [[backbone]] architecture. Backbone is primarily an http server, and as such uses the eventlet.httpd module. eventlet itself is responsible only for handling http protocol-level semantics; "web framework" concepts such as URL traversal and html rendering are implemented in a separate python package, [[mulib]].

== Limitations ==

* Not enough test coverage -- the goal is 100%, but we are not there yet.
* The SSL client does not properly connect to the SSL server, though both client and server interoperate with other SSL implementations (e.g. curl and apache).
** We could use a) a unit test that reproduces the bug (rather than the hand-testing we have been doing) and b) a fix for said bug.
* Not tested on Windows
** There are probably some simple Unix dependencies we introduced by accident. If you're running Eventlet on Windows and run into errors, let us know.
** The eventlet.processes module is known to not work on Windows.

== Eventlet History ==

Eventlet began life as Donovan Preston was talking to Bob Ippolito about coroutine-based non-blocking networking frameworks in Python. Most non-blocking frameworks require you to run the "main loop" in order to perform all network operations, but Donovan wondered if a library written using a trampolining style could get away with transparently running the main loop any time i/o was required, stopping the main loop once no more i/o was scheduled. Bob spent a few days during PyCon 2006 writing a proof-of-concept. He named it eventlet, after the coroutine implementation it used, [http://cheeseshop.python.org/pypi/greenlet greenlet]. Donovan began using eventlet as a light-weight network library for his spare-time project [http://soundfarmer.com/Pavel/trunk/ Pavel], and also began writing some unittests.

* http://svn.red-bean.com/bob/eventlet/trunk/

When Donovan started at Linden Lab in May of 2006, he added eventlet as an svn external in the indra/lib/python directory, to be a dependency of the yet-to-be-named [[backbone]] project (at the time, it was named restserv). However, including eventlet as an svn external meant that any time the externally hosted project had hosting issues, Linden developers were not able to perform svn updates. Thus, the eventlet source was imported into the linden source tree at the same location, and became a fork.

Bob Ippolito has ceased working on eventlet and has stated his desire for Linden to take it's fork forward to the open source world as "the" eventlet.

== License ==
Eventlet is made available under the terms of the open source MIT license below.

'''EVENTLET'''

Copyright (c) 2005-2006, Bob Ippolito

Copyright (c) 2007, Linden Research, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

QtWebkitWin32BuildInstructions

2009-02-04T23:51:38Z

Phoenix Linden: QtWebkitWin32BuildInstructions moved to Qt Webkit Win32 Build Instructions: Make the page searchable

#REDIRECT [[Qt Webkit Win32 Build Instructions]]

Qt Webkit Win32 Build Instructions

2009-02-04T23:51:38Z

Phoenix Linden: QtWebkitWin32BuildInstructions moved to Qt Webkit Win32 Build Instructions: Make the page searchable

These are instructions for building the Qt/WebKit library as well as testgl and
uBrowser demo apps using WebKit.

If you do not have git, you can download and install from:
http://code.google.com/p/msysgit/

Select the option (number 2 of 3) to add git to your path, but not all the unix
tools that ship with it.

1) Building the open source Qt snapshot with Visual Studio:
1.1) Set up directories
* Start/All Programs/Microsoft Visual Studio 2005/Visual Studio Tools/Visual Studio 2005 Command Prompt
* mkdir C:\Qt
1.2) Clone a copy of Qt - about 500 MB
* cd C:\Qt
* git clone git://labs.trolltech.com/qt-snapshot
1.3) Configure Qt, takes about 10 minutes:
* cd qt-snapshot
* configure -release -no-qt3support -prefix C:\Qt\qt-snapshot
* When the license agreement appears, if you agree type:
* y<enter>
1.4) Build Qt, without demos. This takes 1-2 hours.
* nmake sub-src

After building Qt the release and debug libraries will be in C:\Qt\qt-snapshot\lib

1.5) Create the file C:\Qt\qt-snapshot\bin\qt-vars.bat and put the following in it

@echo off
echo Setting up a Qt environment...
set QTDIR=C:\Qt\qt-snapshot
set PATH=C:\Qt\qt-snapshot\bin;%PATH%
set QMAKESPEC=win32-msvc2005
call "C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\vsvars32.bat"

1.6) Make a shortcut to qt-vars.bat on your desktop
Right-click > Properties on the shortcut and set:
Target: %COMSPEC% /k "C:\Qt\qt-snapshot\bin\qt-vars.bat"
Start in: C:\Qt\qt-snapshot

Rename the command prompt shortcut to "Qt Snapshot Command Prompt.

You can test it by opening the prompt and typing qmake --version.

2) Acquire llmozlib
2.1) Run "Qt Snapshot Command Prompt" and go to "C:\"
* git clone git://code.staikos.net/llmozlib
* cd C:\llmozlib
2.2) Checkout the qtwebkit branch
* git checkout -f -b qtwebkit origin/qtwebkit

3) Build llmozlib.a
3.1) Launch the Qt command prompt
* cd C:\llmozlib\llmozlib2
* qmake
* nmake

3) Acquire test dependencies
a. Glut: http://www.xmission.com/~nate/glut.html Grab the library and header zip.
a1. Extract the contents of the zip to a c:\llmozlib\llmozlib2\tests\GL
b. Glui32: http://glui.sourceforge.net/
b1. Extract the zip
b2. Open glui\src\msvc\glui.vcproj. Allow Visual Studio to convert the project.
b2. Edit src\include\GL\glut.h
b3. Move "#include <cstdlib>" to the top of the file, just under #define GLUI_GLUI_H
(hence above #include <GL/glut.h>
b4. See http://www.lighthouse3d.com/opengl/glut/ for details on this edit
b5. Follow the instructions in the readme.txt to compile the library
Make sure to build a release library
b6. Copy glui.h and from the include into C:\llmozlib\llmozlib2\tests\GL
b7. Copy glui32.lib from msvc/lib into C:\llmozlib\llmozlib2\tests\GL

4) Build testgl and run it
* cd C:\llmozlib\llmozlib2\tests\testgl
* qmake CONFIG-=debug
* nmake
* ..\GL\testgl.exe

5) Build ubrowser and run it
* cd C:\llmozlib\llmozlib2\tests\ubrowser
* qmake CONFIG-=debug
* nmake
* ..\GL\ubrowser.exe

Notes:
a.To use Visual studio 2005, under qt *commercial* command prompt to get a .vcproj, run
qmake -tp vc

b. Make sure all libs and app are built as Multi-threaded Dll or Multi-threaded debug dll.
In Visual Studio this is in Properties->configuration->c/c++->code generation->runtime library

Troubleshooting:
1) If you see this, you need to reorder the <cstdlib> and <GL/glut.h> includes.

C:\Program Files\Microsoft Visual Studio 8\VC\include\stdlib.h(406) : error C2381: 'exit' : redefinition; __declspec(noreturn) differs
../include\GL/glut.h(146) : see declaration of 'exit'

2) uBrowser crashes on startup in stdlib (vc8crt.dll or similar)

This happens when you mix debug and release libraries. Make sure you are using
all "release" builds of GLUI and ubrowser.

User talk:Phoenix Linden

2008-12-13T03:25:43Z

Phoenix Linden:

==[[Tao of Linden]]==
Heyas!<br>I noticed you Sysop-locked the [[Tao of Linden]] article so I wanted to request if you could add <nowiki>{{Help|Glossary=*}}</nowiki> on top of the article. It would insert a header like the one in the [[Linden]] article and would register it to certain categories.<br>
On a sidenote: Are these translations you're storing at [[User:Phoenix Linden#scratch work]]? Since ''Ich leibe Buchen'' has a typo (leibe -> liebe) and I guess it's not what you meant. ''Buchen'' [http://de.wikipedia.org/wiki/Buchen are trees] (beeches). ''Bücher'' are books. So should be "''Ich liebe Bücher''".<br>
Kewl rezdate btw ^_^<br>
Greetz, [[Image:Zai_signature.png|45px]] '''[[User:Zai Lynch|Lynch]]''' <sup><small>([[User talk:Zai Lynch|talk]]|[[Special:Contributions/Zai Lynch|contribs]])</small></sup> 02:45, 13 December 2008 (UTC)
:P.S.: Maybe you can also add a ''Related Links'' section, linking to [[Tao of Volunteers]], maybe [[Linden]], [[Linden Lab]], the [http://lindenlab.com/about/tao Tao on the official Website], add some [http://blog.secondlife.com/2006/07/25/the-tao-of-linden/ history about the tao]... I think it would be expandable. Sad that it's locked.
:[[Image:Zai_signature.png|45px]] '''[[User:Zai Lynch|Lynch]]''' <sup><small>([[User talk:Zai Lynch|talk]]|[[Special:Contributions/Zai Lynch|contribs]])</small></sup> 03:18, 13 December 2008 (UTC)
:: I lock the page because the text is part of [[Linden]] policy. I don't know if the [[:Template:Help]] link is that useful in this case because we do not have translations at this time, but I will contemplate adding a related links section to cover things like [[Linden Lab]]. Thanks for the feedback. [[User:Phoenix Linden|Phoenix Linden]] 03:25, 13 December 2008 (UTC)

Tao of Linden

2008-12-12T23:03:53Z

Phoenix Linden: Changed protection level for "Tao of Linden" [edit=sysop:move=sysop]

== Vision and Mission ==
<b>To connect us all to an online world that improves the human condition.</b>

== Company Principles ==

'''Work Together.'''

We are engaged in a wildly ambitious and complex endeavor. We need to take on risk and accept the occasional failure. But we dream, stumble and win only together. This requires a level of creative collaboration you won’t find in many companies. You must not only respect but actively seek out differing views, and then find closure after dissent to move forward together. When you look back, do so to find ways to improve rather than to blame.

'''Walk in our Residents’ shoes.'''

We are blessed by some of the most informed, passionate, committed customers imaginable. They are our reason for being, they are our world, and we call them Residents. They are an insuperable source of advantage and an awesome responsibility. In every choice you make, consider how your choice will impact their experience.

'''Good People Make Good Choices . . . ''and vice versa''.'''

There’s love in the spirit of our mission, the enjoyment we take in each others’ company, the style and humor we have at our best. We’re here because we’re open to all the wonders of the world and the goodness in each other; even the cynics among us harbor the begrudging belief that all things are possible. This is a place where you can be you, and we ask you to make the choices that enable your colleagues to bring out the best in themselves.

'''Be thoughtful and transparent.'''

We build trust through transparent and open communication. Be prolific in your communication but thoughtful, and remember that context is key. Report on your progress regularly and in language that benefits the widest possible range of your colleagues. You are responsible for ensuring that your messages reach your intended audience - make sure your signal does not become noise.

'''No Politics.'''

Sharing our mission requires that you honor this rule at all times: Never act to advance your own interests or someone else’s interests at the expense of the interests of the company.

Tao of Linden

2008-12-12T22:53:04Z

Phoenix Linden: Changed protection level for "Tao of Linden" [edit=autoconfirmed:move=autoconfirmed]

== Vision and Mission ==
<b>To connect us all to an online world that improves the human condition.</b>

== Company Principles ==

''' Work together! '''

The problems we face in creating Second Life are usually larger than one person can solve, and solving them together is one of the great strengths we have as a company. We will succeed only if we collaborate with each other extensively and well. This means helping others reach their goals, asking for help and input often, and being easy to work with. Create teams as necessary to solve specific problems, and support your teammates. Remember that being open and honest is essential, but is only the threshold requirement - great collaborative work requires intuitive compassion and support.

''' Your Choice is Your Responsibility '''

There's a dual meaning here.

Most companies tell you what to do. Then they make you accountable to the person who told you what to do, not to yourself. We don't think this gets the best long-term results with a truly ambitious project like Second Life. At Linden Lab, you are expected to choose your own work, you have to decide how you can best move the company forward. This isn't always easy, but it can be very rewarding for you and it is a huge win for the company. ''This doesn't mean that you can't ask someone else what to do'' - it means that you are responsible for choosing who to listen to! You are responsible for listening well and broadly enough to choose wisely.

And once you have chosen, you are responsible for executing well to making your choices work. You must understand that other people now rely on you for single-minded execution, and it is time to shut out the noise and work without distraction. Sometimes you will fail, and in those cases it is very important to fail fast and fail publicly - that is how we learn and iterate and ultimately win.

''' Be Transparent and Open '''

There are many ways to emphasize responsibility, accountability, communication and trust. We believe that the one key principle that best supports all of these values is transparency. As much as possible, tell everyone what you are doing, all the time. This transparency makes us responsible to our peers, makes us accountable to our own statements, and replaces the need for management with individual responsibility. Over time, it creates and reinforces trust. Be willing to share ideas before you feel they are ‘baked’. Report on your own progress frequently and to everyone.

''' Make Weekly Progress '''

We believe that every person should make specific, visible individual contributions that moves the company forward every week. Projects must be broken down into measurable tasks so that making weekly progress is possible. This is a principle that almost no one believes is true when they first hear it, yet everyone who keeps to this principle over the course of several months is stunned by the amount of progress made during that time. Set weekly goals and report progress to everyone. Regardless how big what you are working on may be, you can always break it down this way. Give it a try.

''' No Politics! '''

Never act to advance your own interests or someone else's interests at the expense of the interests of the company. This is the one principle, outside of violations of law, for which violation will likely result in immediate termination.

''' Might Makes Right '''

Just kidding – wanted to make sure you’re still paying attention. Lots of things could be said here: Have a sense of humor. Have a sense of humility. Have fun. Call out inconsistency in principles when you see it. Don’t let a staid form and function become routine and boilerplate. Which leads to our last principle . . .

''' Do It With Style '''

It’s not enough that we are changing the world. It’s not enough that Second Life is incredibly complex and our vision is vast and shifting. We’re not just going to succeed, we’re going to do it with style. As with life, the journey matters as much as the destination. That means a lot of different things, and a lot of what it means can’t be captured in words alone. Find out by talking to your colleagues, by living the principles above, and by exploring Second Life.

Patch TUT

2008-12-09T18:45:07Z

Phoenix Linden: /* TUT-2008-11-30 */

Patch TUT

2008-12-08T18:38:20Z

Phoenix Linden:

Bug Tracker

2008-04-04T20:21:33Z

Phoenix Linden: /* Security Issues -- a.k.a "the missing Fifth Project" */

{{Multi-lang}}

{{OSWikiContribBox|parent=QA}}

<span style="color: red; font-weight: bold;">The JIRA Issue Tracker is ''not'' for technical support-type requests.</span> '''If you're looking for account-specific help, please use our [http://secondlife.com/support support resources].'''

'''NOTE''': All submissions to this site (JIRA included) are governed by the [[Project:Contribution_Agreement|Second Life Project Contribution Agreement]]. By submitting patches and other information using this site, you acknowledge that you've read, understood, and agreed to those terms.

= What is the Issue Tracker or PJIRA? =
[[Image:JIRA.jpg|thumb]]The public issue tracker, known as "Public JIRA", "PJIRA", or just "JIRA", is an issue-tracking project management tool made by [http://www.atlassian.com/software/jira Atlassian] that is located at http://jira.secondlife.com. It's used by the Second Life open source initiative to organize issues (i.e. bugs and feature requests) submitted by the Second Life community into a searchable database. You, too, can submit issues you find when using the open source or standard versions of Second Life. Please familiarize yourself with the information in this page before proceeding to JIRA.

= How it works =
Bug reports created in JIRA are composed of a description of the problem and, if possible, a reproduction. New features are composed of descriptions of the proposed feature and how it should work. Both types of issues then get contributions from other users, such as better or simpler descriptions and reproductions, and popular issues accumulate votes from other users. Programmers in the open source community can attach "patches", changes to the code that fix or implement the issue. These votes, as well as events like [[bug triage]]s, help prioritize the issues. Those which are acknowledged are "imported" into the Lindens' private copy of JIRA.

After the issue gets Linden attention, others can still continue to help.:

* Once the changes are completed and awaiting release to the public, the bug is resolved as '''"Fix Pending"'''.
* When the change has been made available, it's resolved as '''"Fixed"'''.
* Generally, after being confirmed by Linden Lab's Quality Assurance Team and our community, its status is changed from "Resolved" to '''"Closed"'''.

In addition to "Fix Pending" and "Fixed", an issue can also be resolved or closed if it appears to be a duplicate of another issue, unreproducible, misfiled, not a bug, incomplete, etc.

= Second Life JIRA FAQ =

== Caveats ==
<span style="color: red; font-weight: bold;">The JIRA Issue Tracker is ''not'' for technical support</span>, so please do '''''not''''' enter issues like:

:* "I keep crashing and want it to stop now!"
:* "Someone stole my L$"
:* "The sim I'm in is LAGGIN BAD"
:* "How do I build a house?"
:* [https://jira.secondlife.com/secure/QuickSearch.jspa?searchString=misfiled More examples of misfiled issues]

'''Entering misfiled issues which ''aren't'' actionable and ''don't'' contain clear instructions (see below for more info) makes it harder for your fellow Residents to use the Issue Tracker.''' If you're looking for personal assistance, please send your message to the right place by [http://secondlife.com/community/support.php contacting Support] (towards the bottom of the page), and be sure to include ''useful details'' to help us help you.

Before reporting issues, we recommend you thoroughly search the [http://secondlife.com/community/support.php support resources] first and look for the latest news and status reports on the [http://blog.secondlife.com/ Official Linden Blog].

If you cannot log-in after *repeated attempts* this is regarded by Linden Labs as a Showstopper Issue. At present, JIRA is the approved way for Linden Lab to discover widespread log-in difficulties, it will be dealt with promptly, but you should not post a separate issue that you cannot log in, add a comment or vote to the first cannot log-in issue raised on that day.

== Logging in ==
* Visit https://jira.secondlife.com and click the 'Log In' link on the top right of the page
* On the login page enter your SecondLife Username and Password.
* This will now load the main Jira page you saw before but it will have more options ie Create Issue and a link to edit your profile as well as some pre-defined filters.

== Bugs & New Features ==
* Please read [[Bug_Reporting_101|QA Bug Submission Guidelines]] '''before''' submitting a a bug.
* You can also propose new features through JIRA. (JIRA is emerging to succeed the [http://secondlife.com/vote/ Feature Voting Tool] with your help, because it has better search and parallels the way we Lindens internally organize issues. Plus, you can discuss with other Residents.)

== User profile ==
* Each JIRA user has a ''profile''. The profile consists of your Username (SL name), Fullname (in our case, also your SL name), and all of the JIRA groups you belong to. For most people, this means "jira-users."

* The email address associated with your account shall remain anonymous to other users. The address is not visible or configurable at this time. Direct import of your email address from Second Life's database is currently disabled.

* The JIRA profile is not editable because allowing changes would introduce conflicts with your Second Life account. If you wish to edit account information such as your email address, please login to the [https://secondlife.com/account account management page] at secondlife.com.

== Customizing preferences ==
* If you want to show more issues per page or change the language JIRA's displayed in, [https://jira.secondlife.com/secure/UpdateUserPreferences!default.jspa Update User Preferences] after logging in. (Note that e-mail features for newer users may not be available; see [http://jira.secondlife.com/browse/WEB-335 WEB-335] to track.)

== Projects and Components ==
* ''Projects'' are used to categorize issues into logical groups.
* ''Components'' are used to specify which part of a system the issue affects. In other words, what is the scope of the problem within a project.

{| class="wikitable" border="1"
|+ Projects and Components in JIRA
! Viewer (VWR) !! Service (SVC) !! Website (WEB) !! Miscellaneous (MISC)
|- valign="top"
|
* Avatar/Character
* Building (in-world)
* Chat/IM
* Crashes
* Documentation
* Graphics
* Internationalization
* Inventory
* Land
* Linden Dollars (L$)
* Missing Content
* Performance
* Permissions
* Physics
* Scripting
* Sound
* Source Code
* Stipends
* User Interface
* Voice
|
* HTTPRequest
* Internationalization
* Performance
* Physics
* Scripts
* Simulation
* Teleport
* XML-RPC
|
* Account summary
* blog.secondlife.com
* Developer Directory
* Events
* forums.secondlife.com
* Friends Online
* Interactive map
* jira.secondlife.com
* Land Store
* lindenlab.com
* Lindex
* New account creation
* Public Data Feeds
* Public Metrics & Charts
* secondlife.com
* teen.secondlife.com
* wiki.secondlife.com
|
* Miscellaneous
|}

;Second Life Viewer (VWR): Issues pertaining to the Second Life viewer are reported under this project.
:'''Examples''':
:* "My avatar clothing is all black after installing a video driver update" (Component = Avatar/Character)
:* "Objects in my Inventory do not remain sorted in the correct order after logging out and back in again" (Component = Inventory)

;Second Life Service (SVC): Issues pertaining to the Second Life service are reported here.
:'''Examples''':
:* "Server performance decreases when several avatars teleport into the region at once" (Component = Performance and/or Teleport)
:* "My scripted objects are not able to talk to the outside world after Second Life grid downtime" (Component = Scripts).

;Second Life Website (WEB): Issues pertaining to the Second Life website are in this project.
:'''Examples''':
:* "Wiki prevents login for users with a dash in their name" (Component = wiki.secondlife.com)
:* "jira.secondlife.com always forces me to authenticate even if I save my login information" (Component = jira.secondlife.com).

;Second Life Miscellaneous (MISC): Any other type of issue should be reported in the MISC project.
:'''Example''':
:* "The TOS does not allow me to edit the viewer source code" (Component = Miscellaneous)

== Security Issues -- a.k.a "the missing Fifth Project" ==
The Security project in Jira is only accessible by Linden employees. However, you can create a new issue there, and the security team will get immediate notification. See [[security issues]] page for more information about submitting issues and collecting bounties for responsibly reporting valid security issues.

== Who is WorkingOnIt Linden? ==
When an issue is being worked on, it may be assigned to "WorkingOnIt Linden" to mark its status. Any Linden has access to the account. See [[User:WorkingOnIt Linden]] for details.

== Found a bug on JIRA itself! ==
When you found a bug or other problem (including feature request) on the JIRA itself, Lindens want you to file it on the JIRA run by Atlassian (the developer of JIRA software) by yourself, not thgough the SL public JIRA. It is available on http://jira.atlassian.com

Lindens also want you to put a link to the issue you filed [[Talk:Issue tracker#Feature requests for Atlassian|here]] if you do so.

= Searching =

== Parameters ==
* JIRA searching is easy once you know a bit about the parameters you may use.
* For instructions on searching in JIRA, please visit [http://www.atlassian.com/software/jira/docs/v3.7.1/querysyntax.html JIRA query syntax] and [http://www.atlassian.com/software/jira/docs/v3.7.1/quicksearch.html JIRA quick search].

== Perform a search ==
* First, click on the "Find Issues" link at the top of the screen.
* Next, enter the parameters you wish to search for in the search pane on the left-hand side of the screen.
* As an example, if I wish to search for issues that have not been resolved containing the word "avatar", I would choose the following parameters:
** Project = all projects
** Text search = avatar
** Resolutions = Unresolved
* Another sample search would be for any issues that are fixed in the last week in a particular project. For example, I want to find all bugs in the Second Life Viewer project that were resolved between February 1, 2007 and February 14, 2007. I would enter the following parameters:
** (Optional: Click the "New" link in the search pane to clear settings from any previous searches)
** Project = Second Life Viewer
** Resolution = Fixed
** Updated After = January 31, 2007
** Updated Before = February 15, 2007

== Saving a search as a Filter ==
* A search ''filter'' is a saved search that you may share with others.
* After performing a search as described above, you may save it as a filter by clicking the "Save" link in the Search pane.
* Name the filter something meaningful, for example "Unresolved avatar bugs in all projects."
* Now you can access the search and run it at any time by clicking the "Filter" link in the top right-hand side of the page. This saves time and effort, especially if you frequently run the same complex search and want a handy shortcut!

= Creating bug reports and feature requests =
'''If you feel lost and don't know where to begin, see the easy starter guide, "[http://blog.secondlife.com/2007/07/05/how-to-report-bugs-better/ How to report bugs better]".'''

== Stay recent ==
You can check the [[Release Notes]] or [[Beta Release Notes]] to stay current with recent changes to Second Life. Sometimes, one can discover the context around a new bug, or find that a change was intentional. For example, not being able to sell your land for L$0 is a feature, not a bug.

Also, you should make sure your video drivers are up to date. These are normally obtained from the website of your graphics hardware manufacturer, usually either the [http://www.nvidia.com/content/drivers/drivers.asp NVIDIA official site] or the [http://ati.amd.com/support/driver.html ATI official site]. The [http://www.omegadrivers.net/ Omega Drivers] are often-used modified versions of those drivers.

== Determine if the issue has already been submitted ==
Avoiding duplicate issues is very important. Sorting through duplicates wastes time and effort (for both Linden Lab staff and fellow residents), and it causes bugs and feature proposals to seem like they are getting less attention than they actually are. It is more effective to concentrate efforts about the same problem in the same issue, especially since more-active issues get greater priority.

After logging in, you will see the Dashboard. Here you have access to some search filters which give you access to the most up-to-date information on submitted issues. For example, you can click on ones which show all unresolved (unfixed or untested) issues within each project, then begin a text search from there (by editing the filter). Of course you may create and save your own filters at any time, or simply run a new search from the Quick Search box. Either way, it is best practice to search for issues you wish to report in several ways before submitting them!

If you find that your issue was already submitted, you can still do several things to help:
* Leave a comment containing additional information or details
* If it's a bug, possibly another way to reproduce the bug
* Vote for the issue to express that you feel it is important.
The more good information there is about a specific issue, the better chance it has for a quick resolution.

== Guidelines ==
* Submit security-related issues and exploits directly to the security team. Exploits are bugs that could be used to get an advantage over others, unauthorized access to scripts, unauthorized copying or transferring or modifying of objects that you didn't create (also called 'permissions' bugs), and other bugs that could potentially cause a compromise of the grid or a resident's privacy. For the fastest results, contact a Linden in the group "Bug Hunters", and e-mail your report to security@lindenlab.com. See the article on [[security issues]].
* If your issue is urgent (such as lost content), and you have a Premium Account use the phone or live text support. You might get a faster response if you also submit a ticket through the [http://support.secondlife.com support portal], but usually it take over seven days before your ticket is opened.
* When describing the bug, if possible, try to omit Resident names or other personally-identifying information. If the bug seems to affect only yourself or very few people, you should consider other ways to find technical support via the [http://support.secondlife.com support portal].
* The easier we can reproduce the bug, the more quickly it can get fixed. For example, instead of saying "I crash when I upload random things", the reproduction should be laid out in specific steps:
*: Example:
*:* Click File > Upload Image ($L10)...
*:* Choose a .TXT file instead of a .JPG file
*:* Click the Open button
: Try sending your writeup to a friend, to see if they can follow it! If your friend can follow the steps, chances are we can too!
* Consider uploading snapshots, images, videos, crash logs, or any other related files (10MB limit each). In the above example, you might consider uploading the files you tried to upload that caused the crash.
* '''Do not''' submit more than one issue in a single report.
* '''Do''' search through issues first to ensure yours is not a duplicate.

== Submitting a bug ==
To create a new bug in JIRA, do the following:
* Click the "Create New Issue" link in the blue navigation bar towards the top of the screen. (If you don't see this, make sure you are [[#Logging in|logged in to JIRA]].)

On the first page:
* Select a '''project''' that most closely matches the kind of bug you are submitting - see [[#Projects and Components]].
** Reminder: you should submit security-related issues directly to the security team. See [[security issues]].
* Select "Bug" as your '''issue type'''.
* Click "Next".

On the last page:
* Enter a concise but descriptive '''summary''' (title) for the issue
* Select the '''priority''' (severity) of the bug. For example, a "blocker" bug might render the program useless, but a "small" bug might be merely cosmetic. Click the icon next to the dropdown for more details.
* Select '''components''' that narrow the scope of the bug. You can select multiple components by Ctrl-clicking.
* Choose the '''versions''' that the bug effects. You should only select those versions where you have observed the bug, and only select a "first look" version if the bug ''only'' applies to First Look.
* The '''Linden Lab Issue ID''' should generally be left blank unless you are a Linden. If you want to reference a support ticket number, that should go in the description, not here.
* Describe the '''environment''' in which the problem occurs, if you have noticed that the bug only occurs with certain hardware or software configurations. One way to find such information is the About box inside Second Life. You can guesstimate whether certain facts might be relevant (such as graphics card model for graphics problems, or headset models for voice features) and look for further help in narrowing things down. If configuration doesn't seem to matter, you can leave it blank.
** For example, "Only happens with Mac OS X 10.4.1," or "Seen only with NVIDIA GeForce Go 7800 card," etc.
* Enter a detailed '''description''' of the issue, and be sure to include:
** Steps to reliably reproduce the bug (how to make the bug happen), or at least a description of what seems to lead to the bug, in some detail. Try to make this as simple as possible while still being specific enough to reproduce the bug. Simpler reproductions make it easier to narrow down the causes.
** Observed results (what happens when the bug occurs)
** Expected results (what behavior you would have expected instead)
** Anything else which you think might help, such as forum links or blog posts.
** Again, be as detailed as possible without including personal information!
* If you have a screenshot or video of the bug, or any other relevant file, you can attach it under '''attachment'''. Note that it has a 10MB size limit per file. You can also attach additional files later. (See [[Debug Help]] for various ways to provide such additional information.)
* If you are a programmer and are attaching a patch for the source code, enter the '''source version''' the patch is against and check the '''patch attached''' box.
* Finally, click "Create" to create the new issue.

== Submitting a new feature ==
The process is similar to submitting a bug, with the following differences:

* Select "New Feature" instead of "Bug" as your '''issue type'''.
* Instead of a "reproduction", clearly describe the desired implementation and functionality of the new feature. Make sure it hasn't already been done — you can refer to [http://www.slhistory.org/index.php/Release_Notes release notes] for historical context and [http://blog.secondlife.com/ read our blog] to learn more about what we're doing next.

== Voting for issues ==
You can vote for new features and bugs that you wish to see resolved, and [https://jira.secondlife.com/secure/IssueNavigator.jspa?mode=hide&requestId=10071 view all issues by # of votes]. JIRA uses [http://en.wikipedia.org/wiki/Approval_voting approval voting], so you can vote for as many (or few) issues as you'd like, and you get 1 vote per issue.

Votes can readily be used as part of our prioritization process. Note that since we need to look at aspects such as feasibility and the time required for implementation, a highly-voted issue isn't necessarily going to be resolved ahead of a lesser-voted, but more doable one.

== Return to check on issue status ==
Linden Lab will review issues submitted to jira.secondlife.com on a regular basis. The engineering team may require additional information from the issue reporter, or other contributors, so reviewing all of your created/commented issues regularly will be useful while email support in JIRA is disabled.

Also, when issues are resolved internally the external site will be updated as well, so check your issues for changes on a regular basis.

= Issue States =

== Available states ==

Here is how Linden Lab is using the resolutions:

; Open : This is an issue that belongs to the Assignee to resolve. The assignee may fix the issue, or kick the issue back to the reporter by marking it "Resolved" (see below)
; In Progress : This is how a developer signals to everyone that he/she is working on the issue.
; Reopened : same as "Open".
; Resolved : This is an implicit assignment back to the reporter of the issue. It is not closed yet, but rather in a state of limbo that depends on the resolution. It's up to the Reporter to decide whether to reopen an issue, or close it.
:; Fixed : means that the bug is fixed in a public release of Second Life.
:; Fix Pending: means that the bug is fixed in a version of the code that should soon be publicly available.
:; Won't Fix : means that the assignee doesn't believe this issue should ever be fixed.
:; Duplicate : means that there's some other issue that describes the same problem/idea.
:; Needs More Info : this issue lacks information
:; Cannot Reproduce : we're applying this label pretty liberally. Please provide a detailed description of how to reproduce a problem. Issues that can't be reproduced will eventually be closed.
:; Misfiled : this issue doesn't belong in this issue tracker.
; Closed : The final resting place.

== What's the difference between the "Fixed" and "Fix Pending" resolutions? ==
It's simple:

* "Fixed" means the fix is available in the live Second Life release, ''right now''.
* "Fix Pending" means the fix has been made within Linden Lab and ''has not'' been released publicly yet. It may need to undergo extra care, like quality assurance, or requires merging from a [http://en.wikipedia.org/wiki/Branching_%28software%29 branch], before being available to you. Think of it as a "We're almost there... coming soon!" notice.

= How do I help out? =

Glad you asked!

== Marking Duplicates ==
If you notice an newer issue that is a duplicate of an existing issue with a lot more comments, patches, or votes, feel free to choose "Resolve" and choose "Duplicate". But when you do this, please also choose "Link", and then say "This issue duplicates" and enter the main bug number. This lets everyone keep track of which bugs are duplicates of each other, and which bugs are reported more than others. This ensures that bugs that are often reported get the most attention, and also allows the duplicates to be reviewed from one central location, to ensure they are truly duplicates.

== Resolving support issues ==
This one is best left to technically adept users that can spot the difference between a support issue and a bug -- it's not always a simple matter to figure out. You should at most "Resolve" a report that seems to be a support issue. "Resolving" an issue puts the responsibility back on the reporter to provide more information on why the report isn't a support issue, and is indeed a reproducible bug that an entire class of user experiences.

== Resolving bugs that you can't reproduce ==
If you do exactly what they say in the bug, with the same environment, and can't reproduce the bug, you should resolve the bug. Be careful, if a bug is related to graphics rendering, and you do not have the same video card, for example, that is not the same environment and you can't make this determination. Again this is also best left to technically adept users.

== Reproducing bugs ==
This one is very important! If you can create a step-by-step list to reproduce the bug in the bug report, this helps Linden Lab concentrate on bugs that can be verifiably fixed. Unless a bug can be reproduced, it is impossible to know if it has been fixed or not. Do what the bug reporter said they were doing, write a detailed step-by-step list of things you did to cause the bug to happen, and add it to the bug saying that you have successfully reproduced the bug. Such bugs with solid reproductions get higher priority in the development process, and help the Bug Triage Team work more efficiently.

= Related resources =
Want to learn more about our Issue Tracker?

* '''[[Issue Tracker Forum Transcript]]''' - Info from Rob and Aric Linden on why we have an Issue Tracker, its behind-the-scenes workings, and answers to various questions.

[[Category: Issue Tracker]]

LSL Protocol/RestrainedLifeAPI

2008-03-26T21:46:11Z

Phoenix Linden:

{{Security Advisory|Linden Lab does not support and makes no representations regarding this application.}}

=Restrained Life viewer v1.10.2 Specification=

By [[User:Marine Kelley|Marine Kelley]]

==Audience==

This document is aimed at people who wish to modify or create their own [[LSL]] scripts to use the functionalities of the [http://realrestraint.blogspot.com RestrainedLife viewer]. It does not, however, explains [[LSL]] concepts such as messages and events, nor universal concepts such as [[UUID]]s.

==Introduction==

The [http://realrestraint.blogspot.com RestrainedLife viewer] is meant to execute certain behaviours when receiving special messages from scripts in-world. These messages are mostly calls to the [[llOwnerSay]]() [[LSL]] function.

==Architecture==

The [http://realrestraint.blogspot.com RestrainedLife viewer] parses every [[llOwnerSay]] call and executes every command beginning with ''''@''''. For instance, a call to [[llOwnerSay]] ("@detach=n") will tell the viewer that the object sending the message cannot be detached until further notice.

Version '''1.10''' and above are able to parse multiple commands in one message, in order to avoid spamming the user who is not using this viewer. The format of a message is therefore :

@<behaviour1>[:option1]=<param1>,<behaviour2>[:option2]=<param2>,...,<behaviourN>[:optionN]=<paramN>

Note that there is only one '@' sign, placed at the beginning of the message. The viewer understands this as "this whole [[llOwnerSay]]() is actually a command to execute", so no need to put a '@' before every command, it wouldn't even work. If at least one command fails (typo), the viewer says "... fails command : ... " and mentions it all. However correct commands are parsed and executed, only incorrect ones are discarded.

'''Warning''' : These behaviours are '''not''' persistent between sessions, and an object changes [[UUID]] everytime it [[rez]]zes. This means the object must resend its "status" (undetachable, preventing IMs...) in the [[on_rez]] () event as well as when it changes.

==List of commands==

''Note : These commands are not case-sensitive but are spacing-sensitive. In other words, "@detach = n" will '''not''' work.''

* '''''Automated version checking''''' : "@version=<channel_number>"
Makes the viewer automatically say its version immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

'''Warning''' : when logging in, the [[on_rez]] event of all the attachments occurs way before the avatar can actually send chat messages (about half the way through the login progress bar). This means the timeout should be long enough, like 30 seconds to one minute in order to receive the automatic reply from the viewer.

* '''''Manual version checking''''' : "@version"
This command must be sent in IM from an avatar to the user (will not work from objects). The viewer automatically answers its version to the sender in IM, but neither the message nor the answer appears in the user's IM window, so it's totally stealthy.

* '''''Render an object detachable/nondetachable''''' : "@detach=<y/n>"
When called with the "n" option, the object sending this message (which must be an attachment) will be made nondetachable. It can be detached again when the "y" option is called.

* '''''Allow/prevent sending chat messages''''' : "@sendchat=<y/n>"
When prevented, everything typed on [[channel]] 0 will be discarded. However, emotes and messages beginning with a slash ('/') will go through, truncated to strings of 30 and 15 characters long respectively (likely to change later). Messages with special signs like ()"-*=_^ are prohibited, and will be discarded. When a period ('.') is present, the rest of the message is discarded.

* '''''Remove/add an exception to the emote truncation above''''' : "@emote=<rem/add>"
When adding this exception, the emotes are not truncated anymore (however, special signs will still discard the message).

* '''''Allow/prevent sending instant messages''''' : "@sendim=<y/n>"
When prevented, everything typed in IM will be discarded and a bogus message will be sent to the receiver instead.

* '''''Remove/add exceptions to the instant message sending prevention''''' : "@sendim:<UUID>=<rem/add>"
When adding an exception, the user can send IMs to the receiver whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent receiving chat messages''''' : "@recvchat=<y/n>"
When prevented, everything heard in public chat will be discarded.

* '''''Remove/add exceptions to the chat message receiving prevention''''' : "@recvchat:<UUID>=<rem/add>"
When adding an exception, the user can hear chat messages from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent receiving instant messages''''' : "@recvim=<y/n>"
When prevented, every incoming IM will be discarded and the sender will be notified that the user cannot read them.

* '''''Remove/add exceptions to the chat message receiving prevention''''' : "@recvim:<UUID>=<rem/add>"
When adding an exception, the user can read instant messages from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent teleporting to a landmark''''' : "@tplm=<y/n>"
When prevented, the user cannot use a [[landmark]], pick or any other preset location to [[teleport]] there.

* '''''Allow/prevent teleporting to a location''''' : "@tploc=<y/n>"
When prevented, the user cannot use [[teleport]] to a coordinate by using the [[map]] and such.

* '''''Allow/prevent teleporting by a friend''''' : "@tplure=<y/n>"
When prevented, the user automatically discards any [[teleport]] offer, and the avatar who initiated the offer is notified.

* '''''Remove/add exceptions to the friend teleport prevention''''' : "@tplure:<UUID>=<rem/add>"
When adding an exception, the user can be teleported by the avatar whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Unlimit/limit sit-tp''''' : "@sittp=<y/n>"
When limited, the avatar cannot sit on a [[prim]] unless it is closer than 1.5 m. This allows cages to be secure, preventing the avatar from warping its position through the walls (unless the prim is too close).

* '''''Clear all the rules tied to an object''''' : "@clear"
This command clears all the restrictions and exceptions tied to a particular [[UUID]].

* '''''Clear a subset of the rules tied to an object''''' : "@clear=<string>"
This command clears all the restrictions and exceptions tied to a particular [[UUID]] which name contains <string>. A good example would be "@clear=tp" which clears all the [[teleport]] restrictions and exceptions tied to that object, whereas "@clear=tplure:" would only clear the exceptions to the "teleport-by-friend" restriction

* '''''Allow/prevent editing objects''''' : "@edit=<y/n>"
When prevented from editing and deleting objects, the Build & Edit window will refuse to open.

* '''''Allow/prevent rezzing inventory''''' : "@rez=<y/n>"
When prevented from [[rez]]zing stuff, creating objects, drag-dropping from inventory and dropping attachments will fail.

* '''''Allow/prevent wearing clothes''''' : @addoutfit[:<part>]=<y/n>
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin
If part is not specified, prevents from wearing anything beyond what the avatar is already wearing.

* '''''Allow/prevent removing clothes''''' : @remoutfit[:<part>]=<y/n> (underpants and underwear are kept for teens)
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin
If part is not specified, prevents from removing anything in what the avatar is wearing.

* '''''Force removing clothes''''' : @remoutfit[:<part>]=force (*)
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin
If part is not specified, removes everything.

* '''''Force removing attachments''''' : @detach[:attachpt]=force (*) (underpants and underwear are kept for teens)
Where part is :
chest|skull|left shoulder|right shoulder|left hand|right hand|left foot|right foot|spine|
pelvis|mouth|chin|left ear|right ear|left eyeball|right eyeball|nose|r upper arm|r forearm|
l upper arm|l forearm|right hip|r upper leg|r lower leg|left hip|l upper leg|l lower leg|stomach|left pec|
right pec|center 2|top right|top|top left|center|bottom left|bottom|bottom right
If part is not specified, removes everything.

* '''''Get the list of worn clothes''''' : @getoutfit[:part]=<channel_number>
Makes the viewer automatically answer the current occupation of clothes layers as a list of 0s (empty) and 1s (occupied) immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The list of 0s and 1s corresponds to :
gloves,jacket,pants,shirt,shoes,skirt,socks,underpants,undershirt,skin
in that order.

If a part is specified, answers a single 0 (empty) or 1 (occupied) corresponding to the part.
Ex 1 : @getoutfit=2222 => "0011000111" => avatar is wearing pants, shirt, underpants and undershirt, and of course a skin.
Ex 2 : @getoutfit:socks=2222 => "0" => the avatar is not wearing socks.

* '''''Get the list of worn attachments''''' : @getattach[:attachpt]=<channel_number>
Makes the viewer automatically answer the current occupation of attachment points as a list of 0s (empty) and 1s (occupied) immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The list of 0s and 1s corresponds to :
none,chest,skull,left shoulder,right shoulder,left hand,right hand,left foot,right foot,spine,
pelvis,mouth,chin,left ear,right ear,left eyeball,right eyeball,nose,r upper arm,r forearm,
l upper,arm,l forearm,right hip,r upper leg,r lower leg,left hip,l upper leg,l lower leg,stomach,left pec,
right pec,center 2,top right,top,top left,center,bottom left,bottom,bottom right
in that order.

If an attachment point is specified, answers a single 0 (empty) or 1 (occupied) corresponding to the point.
Ex 1 : @getattach=2222 => "011000011010000000000000100100000000101" => avatar is wearing attachments on
chest, skull, left and right foot, pelvis, l and r lower leg, HUD bottom left and HUD bottom right.
Ex 2 : @getattach:chest=2222 => "1" => avatar is wearing something on the chest.

''Note'' : The first character ("none") is always '0', so the index of each attach point in the string is '''exactly equal''' to the corresponding ATTACH_* macro in LSL. For instance, the index 9 in the string is ATTACH_BACK (which means "spine"). Remember the indices start at zero.

* '''''Allow/prevent using inventory''''' : @showinv=<y/n>
Forces the [[inventory]] windows to close and stay closed.

* '''''Allow/prevent reading notecards''''' : @viewnote=<y/n>
Prevents from opening [[notecards]] but does not close the ones already open.

* '''''Allow/prevent standing up''''' : @unsit=<y/n>
Hides the Stand up button.

* '''''Force sit on an object''''' : @sit:<UUID>=force (*)
Does not work if the user is prevented from sit-tping and further than 1.5 meters away, or when prevented from unsitting.

* '''''Force unsit''''' : @unsit=force (*)
Self-explanatory but for some reason it randomly fails, so don't rely on it for now. Further testing is needed.

* '''''Allow/prevent using any chat channel but certain channels''''' : @sendchannel[:<channel>]=<y/n>
Complimentary of @sendchat, this command prevents the user from sending messages on non-public [[channel]]s. If channel is specified, it becomes an exception to the aforementioned restriction.

* '''''Get the list of restrictions the avatar is currently submitted to''''' : @getstatus[:<part_of_rule>]=<channel>
Makes the viewer automatically answer the list of rules the avatar is currently under, only for the object containing the script issuing that command, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is a list of rules, separated by slashes ('/').

This command is useful for people who write scripts that may conflict with other scripts in the same object (for instance : third-party plugins). Conflict do not occur in different objects, that's why this command only applies to the object calling it.

<part_of_rule> is the name of a rule, or a part of it, useful if the script only needs to know about a certain restriction.

Example : If the avatar is under tploc, tplure, tplm and sittp, here is what the script would get :
@getstatus=2222 => tploc/tplure/tplm/sittp
@getstatus:sittp=2222 => sittp
@getstatus:tpl=2222 => tploc/tplure/tplm (because "tpl" is part of "tploc", "tplure" and "tplm" but not "sittp")

(*) Silently discarded if the user is prevented from doing so by the corresponding restriction. This is on purpose.
Ex : Force detach won't work if the object is undetachable. Force undress won't work if the user is prevented from undressing.

==Important note about the global behaviours such as sendchat==
Such behaviours are global, which means they don't depend on a particular object. However, they are triggered by objects with a set [[UUID]] which can change, and several objects can add the same behaviour, which will be stored several times as the [[UUID]]s are different.

This has a nice side effect : when wearing 2 locked devices that prevent chat, it is necessary to unlock them both to be able to chat again. But it has a nasty side effect, too : if the item changes [[UUID]] (for instance it was derezzed and rezzed again), and it doesn't allow chat beforehand, then the user will have to wait a short moment because the rule stays "orphaned" (its [[UUID]] is defunct) until the '''garbage collector''' kicks in.

Therefore :
'''ALWAYS DEACTIVATE A BEHAVIOUR WHEN THE OBJECT THAT HAS ACTIVATED IT DEREZZES FOR ANY REASON BESIDES LOGGING OUT ! "@CLEAR" IS YOUR FRIEND !'''

==For your information==
Here is how it works internally, for a better understanding of the gotchas you may encounter :
* Each command is parsed into a '''Behaviour''' (ex: "remoutfit"), an '''Option''' (ex: "shirt") and a '''Param''' (ex: "force") and comes from an [[UUID]] (the unique identifier of the emitting object).

* There are two types of commands : '''one-shot''' commands (those which Param is "force" and those which Param is a number such as the channel number of a "version" call) and '''rules''' (those which Param is "y", "n", "add" or "rem"). "clear" is special but can be seen as a one-shot command.

* Parameters "n" and "add" are '''exactly equal''' and are treated '''exactly the same way''', they are just '''synonyms'''. Same goes for "y" and "rem". The only purpose is to distinguish rules ("sendchannel=n") from exceptions ("sendchannel:8=add") in a script for clarity.

* Rules are stored inside a table linking the [[UUID]] of the emitter to the rule itself. They are '''added''' when receiving a "n"/"add" Param, and '''removed''' when receiving a "y"/"rem" Param.
If '''''UUID1''''' is a collar and '''''UUID2''''' is a gag :

'''''UUID1''''' => detach, tploc, tplm, tplure, sittp

'''''UUID2''''' => detach, sendim, sendim:(keyholder)

Those two rules mean that the user cannot send IMs except to their keyholder, and cannot TP at all. Those two items are not detachable. Now if the collar sends "@sendim=n", the table becomes :

'''''UUID1''''' => detach, tploc, tplm, tplure, sittp, sendim

'''''UUID2''''' => detach, sendim, sendim:(keyholder)

If it sends "@sendim=n" a second time nothing changes, as there is a check for its existence prior to adding it. If the gag is unlocked and detached, either it sends a "@clear" or the garbage collector kicks in so the rules linked to '''''UUID2''''' disappear. However, the avatar is still unable to send IMs even to their keyholder, as the exception has disappeared as well. This is because rules linked to one object don't conflict with rules linked to another one.

* One-shot commands, on the other hand, are executed on-the-fly and are not stored.

* When logging on, the avatar stays non-operational (cannot chat, cannot move) for some time, while the user sees the progress bar. However, worn scripted objects [[rez]] in the meantime and start sending rules and commands before the viewer can execute them. Therefore it stores them in a buffer and executes them only when the user is given controls (when the progress bar disappears).

* The viewer periodically (every N seconds) checks all its rules and removes the ones linked to an [[UUID]] that does not exist around anymore ("garbage collector"). This means that rules issued by an '''unworn''' owned object will be discarded as soon as the avatar [[teleports]] elsewhere.

[[Category:Third Party Client]]

File:Ambox emblem question yellow.svg

2008-03-26T21:42:22Z

Phoenix Linden: From http://upload.wikimedia.org/wikipedia/commons/b/b5/Ambox_emblem_question_yellow.svg.

From http://upload.wikimedia.org/wikipedia/commons/b/b5/Ambox_emblem_question_yellow.svg.

LSL Protocol/RestrainedLifeAPI

2008-03-26T21:41:47Z

Phoenix Linden:

LSL Protocol/RestrainedLifeAPI

2008-03-26T21:38:42Z

Phoenix Linden: /* Restrained Life viewer v1.10.2 Specification */

{{Security Advisory|Linden Lab does not support and makes no representations regarding this applications.}}

=Restrained Life viewer v1.10.2 Specification=

By [[User:Marine Kelley|Marine Kelley]]

==Audience==

This document is aimed at people who wish to modify or create their own [[LSL]] scripts to use the functionalities of the [http://realrestraint.blogspot.com RestrainedLife viewer]. It does not, however, explains [[LSL]] concepts such as messages and events, nor universal concepts such as [[UUID]]s.

==Introduction==

The [http://realrestraint.blogspot.com RestrainedLife viewer] is meant to execute certain behaviours when receiving special messages from scripts in-world. These messages are mostly calls to the [[llOwnerSay]]() [[LSL]] function.

==Architecture==

The [http://realrestraint.blogspot.com RestrainedLife viewer] parses every [[llOwnerSay]] call and executes every command beginning with ''''@''''. For instance, a call to [[llOwnerSay]] ("@detach=n") will tell the viewer that the object sending the message cannot be detached until further notice.

Version '''1.10''' and above are able to parse multiple commands in one message, in order to avoid spamming the user who is not using this viewer. The format of a message is therefore :

@<behaviour1>[:option1]=<param1>,<behaviour2>[:option2]=<param2>,...,<behaviourN>[:optionN]=<paramN>

Note that there is only one '@' sign, placed at the beginning of the message. The viewer understands this as "this whole [[llOwnerSay]]() is actually a command to execute", so no need to put a '@' before every command, it wouldn't even work. If at least one command fails (typo), the viewer says "... fails command : ... " and mentions it all. However correct commands are parsed and executed, only incorrect ones are discarded.

'''Warning''' : These behaviours are '''not''' persistent between sessions, and an object changes [[UUID]] everytime it [[rez]]zes. This means the object must resend its "status" (undetachable, preventing IMs...) in the [[on_rez]] () event as well as when it changes.

==List of commands==

''Note : These commands are not case-sensitive but are spacing-sensitive. In other words, "@detach = n" will '''not''' work.''

* '''''Automated version checking''''' : "@version=<channel_number>"
Makes the viewer automatically say its version immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

'''Warning''' : when logging in, the [[on_rez]] event of all the attachments occurs way before the avatar can actually send chat messages (about half the way through the login progress bar). This means the timeout should be long enough, like 30 seconds to one minute in order to receive the automatic reply from the viewer.

* '''''Manual version checking''''' : "@version"
This command must be sent in IM from an avatar to the user (will not work from objects). The viewer automatically answers its version to the sender in IM, but neither the message nor the answer appears in the user's IM window, so it's totally stealthy.

* '''''Render an object detachable/nondetachable''''' : "@detach=<y/n>"
When called with the "n" option, the object sending this message (which must be an attachment) will be made nondetachable. It can be detached again when the "y" option is called.

* '''''Allow/prevent sending chat messages''''' : "@sendchat=<y/n>"
When prevented, everything typed on [[channel]] 0 will be discarded. However, emotes and messages beginning with a slash ('/') will go through, truncated to strings of 30 and 15 characters long respectively (likely to change later). Messages with special signs like ()"-*=_^ are prohibited, and will be discarded. When a period ('.') is present, the rest of the message is discarded.

* '''''Remove/add an exception to the emote truncation above''''' : "@emote=<rem/add>"
When adding this exception, the emotes are not truncated anymore (however, special signs will still discard the message).

* '''''Allow/prevent sending instant messages''''' : "@sendim=<y/n>"
When prevented, everything typed in IM will be discarded and a bogus message will be sent to the receiver instead.

* '''''Remove/add exceptions to the instant message sending prevention''''' : "@sendim:<UUID>=<rem/add>"
When adding an exception, the user can send IMs to the receiver whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent receiving chat messages''''' : "@recvchat=<y/n>"
When prevented, everything heard in public chat will be discarded.

* '''''Remove/add exceptions to the chat message receiving prevention''''' : "@recvchat:<UUID>=<rem/add>"
When adding an exception, the user can hear chat messages from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent receiving instant messages''''' : "@recvim=<y/n>"
When prevented, every incoming IM will be discarded and the sender will be notified that the user cannot read them.

* '''''Remove/add exceptions to the chat message receiving prevention''''' : "@recvim:<UUID>=<rem/add>"
When adding an exception, the user can read instant messages from the sender whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Allow/prevent teleporting to a landmark''''' : "@tplm=<y/n>"
When prevented, the user cannot use a [[landmark]], pick or any other preset location to [[teleport]] there.

* '''''Allow/prevent teleporting to a location''''' : "@tploc=<y/n>"
When prevented, the user cannot use [[teleport]] to a coordinate by using the [[map]] and such.

* '''''Allow/prevent teleporting by a friend''''' : "@tplure=<y/n>"
When prevented, the user automatically discards any [[teleport]] offer, and the avatar who initiated the offer is notified.

* '''''Remove/add exceptions to the friend teleport prevention''''' : "@tplure:<UUID>=<rem/add>"
When adding an exception, the user can be teleported by the avatar whose [[UUID]] is specified in the command. This overrides the prevention for this avatar only (there is no limit to the number of exceptions), don't forget to remove it when it becomes obsolete.

* '''''Unlimit/limit sit-tp''''' : "@sittp=<y/n>"
When limited, the avatar cannot sit on a [[prim]] unless it is closer than 1.5 m. This allows cages to be secure, preventing the avatar from warping its position through the walls (unless the prim is too close).

* '''''Clear all the rules tied to an object''''' : "@clear"
This command clears all the restrictions and exceptions tied to a particular [[UUID]].

* '''''Clear a subset of the rules tied to an object''''' : "@clear=<string>"
This command clears all the restrictions and exceptions tied to a particular [[UUID]] which name contains <string>. A good example would be "@clear=tp" which clears all the [[teleport]] restrictions and exceptions tied to that object, whereas "@clear=tplure:" would only clear the exceptions to the "teleport-by-friend" restriction

* '''''Allow/prevent editing objects''''' : "@edit=<y/n>"
When prevented from editing and deleting objects, the Build & Edit window will refuse to open.

* '''''Allow/prevent rezzing inventory''''' : "@rez=<y/n>"
When prevented from [[rez]]zing stuff, creating objects, drag-dropping from inventory and dropping attachments will fail.

* '''''Allow/prevent wearing clothes''''' : @addoutfit[:<part>]=<y/n>
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin
If part is not specified, prevents from wearing anything beyond what the avatar is already wearing.

* '''''Allow/prevent removing clothes''''' : @remoutfit[:<part>]=<y/n> (underpants and underwear are kept for teens)
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin
If part is not specified, prevents from removing anything in what the avatar is wearing.

* '''''Force removing clothes''''' : @remoutfit[:<part>]=force (*)
Where part is :
gloves|jacket|pants|shirt|shoes|skirt|socks|underpants|undershirt|skin
If part is not specified, removes everything.

* '''''Force removing attachments''''' : @detach[:attachpt]=force (*) (underpants and underwear are kept for teens)
Where part is :
chest|skull|left shoulder|right shoulder|left hand|right hand|left foot|right foot|spine|
pelvis|mouth|chin|left ear|right ear|left eyeball|right eyeball|nose|r upper arm|r forearm|
l upper arm|l forearm|right hip|r upper leg|r lower leg|left hip|l upper leg|l lower leg|stomach|left pec|
right pec|center 2|top right|top|top left|center|bottom left|bottom|bottom right
If part is not specified, removes everything.

* '''''Get the list of worn clothes''''' : @getoutfit[:part]=<channel_number>
Makes the viewer automatically answer the current occupation of clothes layers as a list of 0s (empty) and 1s (occupied) immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The list of 0s and 1s corresponds to :
gloves,jacket,pants,shirt,shoes,skirt,socks,underpants,undershirt,skin
in that order.

If a part is specified, answers a single 0 (empty) or 1 (occupied) corresponding to the part.
Ex 1 : @getoutfit=2222 => "0011000111" => avatar is wearing pants, shirt, underpants and undershirt, and of course a skin.
Ex 2 : @getoutfit:socks=2222 => "0" => the avatar is not wearing socks.

* '''''Get the list of worn attachments''''' : @getattach[:attachpt]=<channel_number>
Makes the viewer automatically answer the current occupation of attachment points as a list of 0s (empty) and 1s (occupied) immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout.

The list of 0s and 1s corresponds to :
none,chest,skull,left shoulder,right shoulder,left hand,right hand,left foot,right foot,spine,
pelvis,mouth,chin,left ear,right ear,left eyeball,right eyeball,nose,r upper arm,r forearm,
l upper,arm,l forearm,right hip,r upper leg,r lower leg,left hip,l upper leg,l lower leg,stomach,left pec,
right pec,center 2,top right,top,top left,center,bottom left,bottom,bottom right
in that order.

If an attachment point is specified, answers a single 0 (empty) or 1 (occupied) corresponding to the point.
Ex 1 : @getattach=2222 => "011000011010000000000000100100000000101" => avatar is wearing attachments on
chest, skull, left and right foot, pelvis, l and r lower leg, HUD bottom left and HUD bottom right.
Ex 2 : @getattach:chest=2222 => "1" => avatar is wearing something on the chest.

''Note'' : The first character ("none") is always '0', so the index of each attach point in the string is '''exactly equal''' to the corresponding ATTACH_* macro in LSL. For instance, the index 9 in the string is ATTACH_BACK (which means "spine"). Remember the indices start at zero.

* '''''Allow/prevent using inventory''''' : @showinv=<y/n>
Forces the [[inventory]] windows to close and stay closed.

* '''''Allow/prevent reading notecards''''' : @viewnote=<y/n>
Prevents from opening [[notecards]] but does not close the ones already open.

* '''''Allow/prevent standing up''''' : @unsit=<y/n>
Hides the Stand up button.

* '''''Force sit on an object''''' : @sit:<UUID>=force (*)
Does not work if the user is prevented from sit-tping and further than 1.5 meters away, or when prevented from unsitting.

* '''''Force unsit''''' : @unsit=force (*)
Self-explanatory but for some reason it randomly fails, so don't rely on it for now. Further testing is needed.

* '''''Allow/prevent using any chat channel but certain channels''''' : @sendchannel[:<channel>]=<y/n>
Complimentary of @sendchat, this command prevents the user from sending messages on non-public [[channel]]s. If channel is specified, it becomes an exception to the aforementioned restriction.

* '''''Get the list of restrictions the avatar is currently submitted to''''' : @getstatus[:<part_of_rule>]=<channel>
Makes the viewer automatically answer the list of rules the avatar is currently under, only for the object containing the script issuing that command, immediately on the chat channel number <channel_number> that the script can listen to. Always use a positive integer. Remember that regular viewers do not answer anything at all so remove the listener after a timeout. The answer is a list of rules, separated by slashes ('/').

This command is useful for people who write scripts that may conflict with other scripts in the same object (for instance : third-party plugins). Conflict do not occur in different objects, that's why this command only applies to the object calling it.

<part_of_rule> is the name of a rule, or a part of it, useful if the script only needs to know about a certain restriction.

Example : If the avatar is under tploc, tplure, tplm and sittp, here is what the script would get :
@getstatus=2222 => tploc/tplure/tplm/sittp
@getstatus:sittp=2222 => sittp
@getstatus:tpl=2222 => tploc/tplure/tplm (because "tpl" is part of "tploc", "tplure" and "tplm" but not "sittp")

(*) Silently discarded if the user is prevented from doing so by the corresponding restriction. This is on purpose.
Ex : Force detach won't work if the object is undetachable. Force undress won't work if the user is prevented from undressing.

==Important note about the global behaviours such as sendchat==
Such behaviours are global, which means they don't depend on a particular object. However, they are triggered by objects with a set [[UUID]] which can change, and several objects can add the same behaviour, which will be stored several times as the [[UUID]]s are different.

This has a nice side effect : when wearing 2 locked devices that prevent chat, it is necessary to unlock them both to be able to chat again. But it has a nasty side effect, too : if the item changes [[UUID]] (for instance it was derezzed and rezzed again), and it doesn't allow chat beforehand, then the user will have to wait a short moment because the rule stays "orphaned" (its [[UUID]] is defunct) until the '''garbage collector''' kicks in.

Therefore :
'''ALWAYS DEACTIVATE A BEHAVIOUR WHEN THE OBJECT THAT HAS ACTIVATED IT DEREZZES FOR ANY REASON BESIDES LOGGING OUT ! "@CLEAR" IS YOUR FRIEND !'''

==For your information==
Here is how it works internally, for a better understanding of the gotchas you may encounter :
* Each command is parsed into a '''Behaviour''' (ex: "remoutfit"), an '''Option''' (ex: "shirt") and a '''Param''' (ex: "force") and comes from an [[UUID]] (the unique identifier of the emitting object).

* There are two types of commands : '''one-shot''' commands (those which Param is "force" and those which Param is a number such as the channel number of a "version" call) and '''rules''' (those which Param is "y", "n", "add" or "rem"). "clear" is special but can be seen as a one-shot command.

* Parameters "n" and "add" are '''exactly equal''' and are treated '''exactly the same way''', they are just '''synonyms'''. Same goes for "y" and "rem". The only purpose is to distinguish rules ("sendchannel=n") from exceptions ("sendchannel:8=add") in a script for clarity.

* Rules are stored inside a table linking the [[UUID]] of the emitter to the rule itself. They are '''added''' when receiving a "n"/"add" Param, and '''removed''' when receiving a "y"/"rem" Param.
If '''''UUID1''''' is a collar and '''''UUID2''''' is a gag :

'''''UUID1''''' => detach, tploc, tplm, tplure, sittp

'''''UUID2''''' => detach, sendim, sendim:(keyholder)

Those two rules mean that the user cannot send IMs except to their keyholder, and cannot TP at all. Those two items are not detachable. Now if the collar sends "@sendim=n", the table becomes :

'''''UUID1''''' => detach, tploc, tplm, tplure, sittp, sendim

'''''UUID2''''' => detach, sendim, sendim:(keyholder)

If it sends "@sendim=n" a second time nothing changes, as there is a check for its existence prior to adding it. If the gag is unlocked and detached, either it sends a "@clear" or the garbage collector kicks in so the rules linked to '''''UUID2''''' disappear. However, the avatar is still unable to send IMs even to their keyholder, as the exception has disappeared as well. This is because rules linked to one object don't conflict with rules linked to another one.

* One-shot commands, on the other hand, are executed on-the-fly and are not stored.

* When logging on, the avatar stays non-operational (cannot chat, cannot move) for some time, while the user sees the progress bar. However, worn scripted objects [[rez]] in the meantime and start sending rules and commands before the viewer can execute them. Therefore it stores them in a buffer and executes them only when the user is given controls (when the progress bar disappears).

* The viewer periodically (every N seconds) checks all its rules and removes the ones linked to an [[UUID]] that does not exist around anymore ("garbage collector"). This means that rules issued by an '''unworn''' owned object will be discarded as soon as the avatar [[teleports]] elsewhere.

File:Ambox emblem question.svg

2008-03-26T21:29:44Z

Phoenix Linden: From http://commons.wikimedia.org/wiki/Image:Ambox_emblem_question.svg

From http://commons.wikimedia.org/wiki/Image:Ambox_emblem_question.svg

File:Emblem-important-yellow.svg

2008-03-26T21:21:42Z

Phoenix Linden: From http://commons.wikimedia.org/wiki/Image:Emblem-important-yellow.svg

From http://commons.wikimedia.org/wiki/Image:Emblem-important-yellow.svg

File:Emblem-important-red.svg

2008-03-26T21:20:48Z

Phoenix Linden: From http://commons.wikimedia.org/wiki/Image:Emblem-important-red.svg

From http://commons.wikimedia.org/wiki/Image:Emblem-important-red.svg

File:Emblem-important.svg

2008-03-26T21:16:16Z

Phoenix Linden: From http://en.wikipedia.org/wiki/Image:Emblem-important.svg

From http://en.wikipedia.org/wiki/Image:Emblem-important.svg

Template:Security Advisory

2008-03-26T19:43:37Z

Phoenix Linden: New page: {{#vardefine:header|{{#var:header}} <div id="box"> {{{!}} cellspacing="3" cellpadding="3" width="100%" style="background:#660000;" {{!}} style="color:white;" title="Security Advisory" {{!}...

{{#vardefine:header|{{#var:header}}
<div id="box">
{{{!}} cellspacing="3" cellpadding="3" width="100%" style="background:#660000;"
{{!}} style="color:white;" title="Security Advisory" {{!}} '''Security Advisory'''
{{!}}-
{{!}} bgcolor="white" {{!}}
{{{1}}}
{{!}}}
</div>}}{{#if:{{{inline|}}}<noinclude>t</noinclude>|{{#var:header}}}}

Mulib/Examples

2008-02-15T19:08:01Z

Phoenix Linden: /* Chat Server */

= Mulib Examples =

These are some short examples to give a flavor of using [[mulib]]. You can find all the example code in the examples directory of a mulib checkout.

== hello world ==

The following program will bring up a webserver listening on port 8080 which can respond to a single request, "GET /", with the response "hello, world":

<python># hello_world.py:
from mulib import mu

from eventlet import api, httpd

class HelloWorld(mu.Resource):
def handle_get(self, req):
req.write("hello, world\n")

if __name__ == "__main__":
root = HelloWorld()

httpd.server(
api.tcp_listener(('0.0.0.0', 8080)),
mu.SiteMap(root))</python>

=== CGI ===
You can treat this resource as a [http://en.wikipedia.org/wiki/Common_Gateway_Interface CGI], by writing a second, wrapper, file that refers to it:

<python># hello_world.cgi:
#!/usr/bin/python
from mulib import cgiadapter

cgiadapter.run_as_cgi('hello_world', 'HelloWorld')</python>

Configure your web server to execute hello_world.cgi, and you should be able to interact with it just like the standalone version.

== stacked ==

Stacked is a pure REST server, and you can use it to traverse native python objects like <code>dicts</code>. You invoke these special capabilities of Stacked by placing a python dict or list in the resource hierarchy instead of a mu.Resource, in this case at the root.

<python>from mulib import mu

from eventlet import api, httpd

root = {'':'hello, world\n',
'other':"hello, other\n"}

httpd.server(api.tcp_listener(('0.0.0.0', 8080)), mu.SiteMap(root))</python>

You can then access this dictionary as a REST resource, e.g.
<pre><nowiki>
> curl http://localhost:8080/
hello, world
> curl http://localhost:8080/other
hello, other
> curl -X PUT -d "the new data" http://localhost:8080/third
> curl http://localhost:8080/third
the new data
</nowiki></pre>

Mu/stacked can do content negotiation:

<pre><nowiki>
> curl -X PUT -H "Content-type: application/json" -d '{"hi": "there"}' http://localhost:8080/fourth
> curl http://localhost:8080/fourth/hi
there
> curl -H "Accept: application/json" http://localhost:8080/fourth
{'hi': 'there'}
</nowiki></pre>

'''Note:''' This means that anyone who has access to your stacked web service can modify the data in your process! In the future we might have a 'read-only' implementation.

== Chat Server ==
[http://www.evilchuck.com/ EvilChuck] wrote a nifty [http://www.evilchuck.com/2008/02/toy-chat-server-with-eventlet-and-mulib.html toy chat server] that we will partially reproduce here at his permission.

Through tacked, and coros, we can tie a <code>ChatMessage</code> instance to the ''/listen'' url:

<python>
from mulib import mu, stacked, resources
from eventlet import api, httpd, coros, util

util.wrap_socket_with_coroutine_socket()

chat_listener = coros.event()

class ChatMessage(mu.Resource):
"""A Rsource to handle receiving chat messages"""
def handle_post(self, request):
"""POST to send chat messages
expects nick and message as POST arguments"""
nick = request.get_arg('nick')
message = request.get_arg('message').strip()
if message:
# Send the chat message to all who are listening
chat_listener.send("%s: %s" % (nick, message))
# Reset the listener so that it can receive more messages
chat_listener.reset()
request.write('')

root = {
'chat' : resources.File('chat.html'), # /chat -> Load chat.html
'listen' : chat_listener, # /listen -> Wait for new msgs
'message' : ChatMessage(), # /message -> Send a message
}

# Start the server
httpd.server(
api.tcp_listener(('0.0.0.0', 5000)),
mu.SiteMap(root), max_http_version="HTTP/1.0"
)
</python>

And with some fancy html which is served up through the <code>resources.File</code> we get:

<pre>
<html>
<head>
<link rel="stylesheet" href="http://yui.yahooapis.com/2.4.1/build/reset-fonts-grids/reset-fonts-grids.css" type="text/css">
<style>
#hd, #bd, #ft { border: 1px solid #808080;}
#hd h1 { margin-left: 5px; font-size: 120%; }
#bd { min-height: 350px; }
body { position: relative; }
.bd { text-align: left; }
input { width: 100%; }
</style>
</head>
<body>
<div id="doc" class="yui-t7">
<div id="hd"><h1>Web Chat</h1></div>
<div id="bd">
<div class="yui-g">
<div id="chat_text"></div>
</div>
</div>
<div id="ft">
<input type="text" maxlength="256" id="chat_message"/>
</div>
</body>
<script src="http://yui.yahooapis.com/2.4.1/build/yahoo/yahoo-min.js"></script>
<script src="http://yui.yahooapis.com/2.4.1/build/event/event-min.js" ></script>
<script src="http://yui.yahooapis.com/2.4.1/build/dom/dom-min.js"></script>
<script src="http://yui.yahooapis.com/2.4.1/build/connection/connection-min.js"></script>
<script type="text/javascript">
YAHOO.util.Event.onDOMReady(function () {
// Set up a random nickname for the user
var nick = 'User-' + Math.round(Math.random()*10000);
var handleReturn = function (type, args, obj) {
// Handler to run when the Enter key is pressed
var el = document.getElementById("chat_message");
if (el.value) {
// Send the message to the server
var postData = "nick="+escape(nick)+"&message="+escape(el.value);
YAHOO.util.Connect.asyncRequest('POST','/message', {
success : function(o) {
el.value = '';
},
}, postData);
}
};
var listen = function () {
// Listens for incoming messages
YAHOO.util.Connect.asyncRequest('GET', '/listen', {
success: function (o) {
if (o.status == 200) {
var el = document.getElementById("chat_text");
el.innerHTML += o.responseText + '<BR/>';
listen();
}
else if (o.status == 202) {
// 202 is returned when the connection has timed out
listen();
}
}
});
};
// Register the key listener to listen for the Enter key
var keyListener = new YAHOO.util.KeyListener(
document, {keys: 13}, handleReturn);
keyListener.enable();
// Start listening for incoming messages
listen();
});
</script>
</html>
</pre>

To test it out, put both files in the same directory, launch chat.py, and browse to http://localhost:5000/chat

Mulib/Examples

2008-02-15T18:46:55Z

Phoenix Linden:

LSL Library Call Test 2

2008-02-05T01:04:37Z

Phoenix Linden:

[[Category:Conformance Test]]

* Tests that LSL library functions are callable and that parameter and return types are correct
* Does NOT test library call semantics
* To run, rez a prim, add this script, then touch the prim
* On successful completion says "Ran 172 tests in 50 seconds"
* Test should take ~50s due to sleep and energy delays
* Generates multiple script errors due to erroneous parameters, these errors should be ignored
* For more verbose reporting uncomment llSay call in test()

<pre>
integer gTests = 0;

test(string name)
{
++gTests;
//llSay(0, name);
}

tests()
{
float floatResult;
integer integerResult;
string stringResult;
key keyResult;
vector vectorResult;
rotation rotationResult;
list listResult;

test("llGetInventoryKey"); keyResult = llGetInventoryKey("foo");
test("llAllowInventoryDrop"); llAllowInventoryDrop(42);
test("llGetSunDirection"); vectorResult = llGetSunDirection();
test("llGetTextureOffset"); vectorResult = llGetTextureOffset(42);
test("llGetTextureScale"); vectorResult = llGetTextureScale(42);
test("llGetTextureRot"); floatResult = llGetTextureRot(42);
test("llSubStringIndex"); integerResult = llSubStringIndex("foo", "foo");
test("llGetOwnerKey"); keyResult = llGetOwnerKey(NULL_KEY);
test("llGetCenterOfMass"); vectorResult = llGetCenterOfMass();
test("llGetListLength"); integerResult = llGetListLength([3]);
test("llList2Integer"); integerResult = llList2Integer([3], 42);
test("llList2Float"); floatResult = llList2Float([3], 42);
test("llList2String"); stringResult = llList2String([3], 42);
test("llList2Key"); keyResult = llList2Key([3], 42);
test("llList2Vector"); vectorResult = llList2Vector([3], 42);
test("llList2Rot"); rotationResult = llList2Rot([3], 42);
test("llCSV2List"); listResult = llCSV2List("foo");
test("llGetRegionCorner"); vectorResult = llGetRegionCorner();
test("llGetObjectName"); stringResult = llGetObjectName();
test("llSetObjectName"); llSetObjectName("foo");
test("llGetDate"); stringResult = llGetDate();
test("llEdgeOfWorld"); integerResult = llEdgeOfWorld(<1.1,2.2,3.3>, <1.1,2.2,3.3>);
test("llGetAgentInfo"); integerResult = llGetAgentInfo(NULL_KEY);
test("llAdjustSoundVolume"); llAdjustSoundVolume(0.5);
test("llSetSoundQueueing"); llSetSoundQueueing(42);
test("llSetSoundRadius"); llSetSoundRadius(0.5);
test("llKey2Name"); stringResult = llKey2Name(NULL_KEY);
test("llSetTextureAnim"); llSetTextureAnim(42, 42, 42, 42, 0.5, 0.5, 0.5);
test("llTriggerSoundLimited"); llTriggerSoundLimited("foo", 0.5, <1.1,2.2,3.3>, <1.1,2.2,3.3>);
test("llEjectFromLand"); llEjectFromLand(NULL_KEY);
test("llOverMyLand"); integerResult = llOverMyLand(NULL_KEY);
test("llGetLandOwnerAt"); keyResult = llGetLandOwnerAt(<1.1,2.2,3.3>);
test("llGetNotecardLine"); keyResult = llGetNotecardLine("foo", 42);
test("llGetAgentSize"); vectorResult = llGetAgentSize(NULL_KEY);
test("llSameGroup"); integerResult = llSameGroup(NULL_KEY);
test("llUnSit"); llUnSit(NULL_KEY);
test("llGroundSlope"); vectorResult = llGroundSlope(<1.1,2.2,3.3>);
test("llGroundNormal"); vectorResult = llGroundNormal(<1.1,2.2,3.3>);
test("llGroundContour"); vectorResult = llGroundContour(<1.1,2.2,3.3>);
test("llGetAttached"); integerResult = llGetAttached();
test("llGetFreeMemory"); integerResult = llGetFreeMemory();
test("llGetRegionName"); stringResult = llGetRegionName();
test("llGetRegionTimeDilation"); floatResult = llGetRegionTimeDilation();
test("llGetRegionFPS"); floatResult = llGetRegionFPS();
test("llGroundRepel"); llGroundRepel(0.5, 42, 0.5);
test("llScriptDanger"); integerResult = llScriptDanger(<1.1,2.2,3.3>);
test("llSetVehicleType"); llSetVehicleType(42);
test("llSetVehicleFloatParam"); llSetVehicleFloatParam(42, 0.5);
test("llSetVehicleVectorParam"); llSetVehicleVectorParam(42, <1.1,2.2,3.3>);
test("llSetVehicleRotationParam"); llSetVehicleRotationParam(42, <1.1,2.2,3.3,4.4>);
test("llSetVehicleFlags"); llSetVehicleFlags(42);
test("llRemoveVehicleFlags"); llRemoveVehicleFlags(42);
test("llSitTarget"); llSitTarget(<1.1,2.2,3.3>, <1.1,2.2,3.3,4.4>);
test("llAvatarOnSitTarget"); keyResult = llAvatarOnSitTarget();
test("llAddToLandPassList"); llAddToLandPassList(NULL_KEY, 0.5);
test("llSetTouchText"); llSetTouchText("foo");
test("llSetSitText"); llSetSitText("foo");
test("llSetCameraEyeOffset"); llSetCameraEyeOffset(<1.1,2.2,3.3>);
test("llSetCameraAtOffset"); llSetCameraAtOffset(<1.1,2.2,3.3>);
test("llVolumeDetect"); llVolumeDetect(42);
test("llResetOtherScript"); llResetOtherScript("foo");
test("llGetScriptState"); integerResult = llGetScriptState("foo");
test("llRemoteLoadScript"); llRemoteLoadScript(NULL_KEY, "foo", 42, 42);
test("llOpenRemoteDataChannel"); llOpenRemoteDataChannel();
test("llSendRemoteData"); keyResult = llSendRemoteData(NULL_KEY, "foo", 42, "foo");
test("llRemoteDataReply"); llRemoteDataReply(NULL_KEY, NULL_KEY, "foo", 42);
test("llCloseRemoteDataChannel"); llCloseRemoteDataChannel(NULL_KEY);
test("llMD5String"); stringResult = llMD5String("foo", 42);
test("llStringToBase64"); stringResult = llStringToBase64("foo");
test("llBase64ToString"); stringResult = llBase64ToString("foo");
test("llXorBase64Strings"); stringResult = llXorBase64Strings("foo", "foo");
test("llSetRemoteScriptAccessPin"); llSetRemoteScriptAccessPin(42);
test("llRemoteLoadScriptPin"); llRemoteLoadScriptPin(NULL_KEY, "foo", 42, 42, 42);
test("llRemoteDataSetRegion"); llRemoteDataSetRegion();
test("llLog10"); floatResult = llLog10(0.5);
test("llLog"); floatResult = llLog(0.5);
test("llSetParcelMusicURL"); llSetParcelMusicURL("foo");
test("llGetRootPosition"); vectorResult = llGetRootPosition();
test("llGetRootRotation"); rotationResult = llGetRootRotation();
test("llGetObjectDesc"); stringResult = llGetObjectDesc();
test("llSetObjectDesc"); llSetObjectDesc("foo");
test("llGetCreator"); keyResult = llGetCreator();
test("llGetTimestamp"); stringResult = llGetTimestamp();
test("llSetLinkAlpha"); llSetLinkAlpha(42, 0.5, 42);
test("llGetNumberOfPrims"); integerResult = llGetNumberOfPrims();
test("llGetNumberOfNotecardLines"); keyResult = llGetNumberOfNotecardLines("foo");
test("llGetBoundingBox"); listResult = llGetBoundingBox(NULL_KEY);
test("llGetGeometricCenter"); vectorResult = llGetGeometricCenter();
test("llIntegerToBase64"); stringResult = llIntegerToBase64(42);
test("llBase64ToInteger"); integerResult = llBase64ToInteger("foo");
test("llGetGMTclock"); floatResult = llGetGMTclock();
test("llGetSimulatorHostname"); stringResult = llGetSimulatorHostname();
test("llSetLocalRot"); llSetLocalRot(<1.1,2.2,3.3,4.4>);
test("llRezAtRoot"); llRezAtRoot("foo", <1.1,2.2,3.3>, <1.1,2.2,3.3>, <1.1,2.2,3.3,4.4>, 42);
test("llGetObjectPermMask"); integerResult = llGetObjectPermMask(42);
//test("llSetObjectPermMask"); llSetObjectPermMask(42,42);
test("llGetInventoryPermMask"); integerResult = llGetInventoryPermMask("foo", 42);
//test("llSetInventoryPermMask"); llSetInventoryPermMask("foo", 42, 42);
test("llOwnerSay"); llOwnerSay("foo");
test("llGetInventoryCreator"); keyResult = llGetInventoryCreator("foo");
test("llRequestSimulatorData"); keyResult = llRequestSimulatorData("foo", 42);
test("llForceMouselook"); llForceMouselook(42);
test("llGetObjectMass"); floatResult = llGetObjectMass(NULL_KEY);
test("llLoadURL"); llLoadURL(NULL_KEY, "foo", "foo");
test("llModPow"); integerResult = llModPow(42, 42, 42);
test("llGetInventoryType"); integerResult = llGetInventoryType("foo");
test("llGetCameraPos"); vectorResult = llGetCameraPos();
test("llGetCameraRot"); rotationResult = llGetCameraRot();
test("llSetPrimURL"); llSetPrimURL("foo");
test("llRefreshPrimURL"); llRefreshPrimURL();
test("llEscapeURL"); stringResult = llEscapeURL("foo");
test("llUnescapeURL"); stringResult = llUnescapeURL("foo");
test("llMapDestination"); llMapDestination("foo", <1.1,2.2,3.3>, <1.1,2.2,3.3>);
test("llAddToLandBanList"); llAddToLandBanList(NULL_KEY, 0.5);
test("llRemoveFromLandPassList"); llRemoveFromLandPassList(NULL_KEY);
test("llRemoveFromLandBanList"); llRemoveFromLandBanList(NULL_KEY);
test("llResetLandBanList"); llResetLandBanList();
test("llResetLandPassList"); llResetLandPassList();
test("llClearCameraParams"); llClearCameraParams();
test("llGetUnixTime"); integerResult = llGetUnixTime();
test("llGetParcelFlags"); integerResult = llGetParcelFlags(<1.1,2.2,3.3>);
test("llGetRegionFlags"); integerResult = llGetRegionFlags();
test("llGetObjectPrimCount"); integerResult = llGetObjectPrimCount(NULL_KEY);
test("llGetParcelPrimOwners"); listResult = llGetParcelPrimOwners(<1.1,2.2,3.3>);
test("llGetParcelPrimCount"); integerResult = llGetParcelPrimCount(<1.1,2.2,3.3>, 42, 42);
test("llGetParcelMaxPrims"); integerResult = llGetParcelMaxPrims(<1.1,2.2,3.3>, 42);
test("llSetLinkTexture"); llSetLinkTexture(42, "foo", 42);
test("llStringTrim"); stringResult = llStringTrim("foo", 42);
test("llRegionSay"); llRegionSay(42, "foo");
test("llListSort"); listResult = llListSort([3], 42, 42);
test("llList2List"); listResult = llList2List([3], 42, 42);
test("llDeleteSubList"); listResult = llDeleteSubList([3], 42, 42);
test("llGetListEntryType"); integerResult = llGetListEntryType([3], 42);
test("llList2CSV"); stringResult = llList2CSV([3]);
test("llListRandomize"); listResult = llListRandomize([3], 42);
test("llList2ListStrided"); listResult = llList2ListStrided([3], 42, 42, 42);
test("llListInsertList"); listResult = llListInsertList([3], [3], 42);
test("llListFindList"); integerResult = llListFindList([3], [3]);
test("llParseString2List"); listResult = llParseString2List("foo", [3], [3]);
test("llParticleSystem"); llParticleSystem([3]);
test("llGiveInventoryList"); llGiveInventoryList(NULL_KEY, "foo", [3]);
test("llDumpList2String"); stringResult = llDumpList2String([3], "foo");
test("llDialog"); llDialog(NULL_KEY, "foo", [3], 42);
test("llSetPrimitiveParams"); llSetPrimitiveParams([3]);
test("llGetPrimitiveParams"); listResult = llGetPrimitiveParams([3]);
test("llParseStringKeepNulls"); listResult = llParseStringKeepNulls("foo", [3], [3]);
test("llListReplaceList"); listResult = llListReplaceList([3], [3], 42, 42);
test("llParcelMediaCommandList"); llParcelMediaCommandList([3]);
test("llParcelMediaQuery"); listResult = llParcelMediaQuery([3]);
test("llSetPayPrice"); llSetPayPrice(42, [3]);
test("llSetCameraParams"); llSetCameraParams([3]);
test("llListStatistics"); floatResult = llListStatistics(42, [3]);
test("llGetParcelDetails"); listResult = llGetParcelDetails(<1.1,2.2,3.3>, [3]);
test("llSetLinkPrimitiveParams"); llSetLinkPrimitiveParams(42, [3]);
//test("llGetObjectDetails"); listResult = llGetObjectDetails(NULL_KEY, [3]);
}

default
{
touch_start(integer total_number)
{
llResetTime();
tests();
llSay(0, "Ran " + (string) gTests + " tests in " + (string) llGetTime() + " seconds");
gTests = 0;
}
}
</pre>

LSL Library Call Test 1

2008-02-05T01:03:59Z

Phoenix Linden:

[[Category:Conformance Test]]

* Tests that LSL library functions are callable and that parameter and return types are correct
* Does NOT test library call semantics
* To run, rez a prim, add this script, then touch the prim
* On successful completion says "Ran 172 tests in 50 seconds"
* Test should take ~50s due to sleep and energy delays
* Generates multiple script errors due to erroneous parameters, these errors should be ignored
* For more verbose reporting uncomment llSay call in test()

<pre>
integer gTests = 0;

test(string name)
{
++gTests;
//llSay(0, name);
}

tests()
{
float floatResult;
integer integerResult;
string stringResult;
key keyResult;
vector vectorResult;
rotation rotationResult;
list listResult;

test("llSin"); floatResult = llSin(0.5);
test("llCos"); floatResult = llCos(0.5);
test("llTan"); floatResult = llTan(0.5);
test("llAtan2"); floatResult = llAtan2(0.5, 0.5);
test("llSqrt"); floatResult = llSqrt(0.5);
test("llPow"); floatResult = llPow(0.5, 0.5);
test("llAbs"); integerResult = llAbs(42);
test("llFabs"); floatResult = llFabs(0.5);
test("llFrand"); floatResult = llFrand(0.5);
test("llFloor"); integerResult = llFloor(0.5);
test("llCeil"); integerResult = llCeil(0.5);
test("llRound"); integerResult = llRound(0.5);
test("llVecMag"); floatResult = llVecMag(<1.1,2.2,3.3>);
test("llVecNorm"); vectorResult = llVecNorm(<1.1,2.2,3.3>);
test("llVecDist"); floatResult = llVecDist(<1.1,2.2,3.3>, <1.1,2.2,3.3>);
test("llRot2Euler"); vectorResult = llRot2Euler(<1.1,2.2,3.3,4.4>);
test("llEuler2Rot"); rotationResult = llEuler2Rot(<1.1,2.2,3.3>);
test("llAxes2Rot"); rotationResult = llAxes2Rot(<1.1,2.2,3.3>, <1.1,2.2,3.3>, <1.1,2.2,3.3>);
test("llRot2Fwd"); vectorResult = llRot2Fwd(<1.1,2.2,3.3,4.4>);
test("llRot2Left"); vectorResult = llRot2Left(<1.1,2.2,3.3,4.4>);
test("llRot2Up"); vectorResult = llRot2Up(<1.1,2.2,3.3,4.4>);
test("llRotBetween"); rotationResult = llRotBetween(<1.1,2.2,3.3>, <1.1,2.2,3.3>);
test("llWhisper"); llWhisper(42, "foo");
test("llSay"); llSay(42, "foo");
test("llShout"); llShout(42, "foo");
test("llListen"); integerResult = llListen(42, "foo", NULL_KEY, "foo");
test("llListenControl"); llListenControl(42, 42);
test("llListenRemove"); llListenRemove(42);
test("llSensor"); llSensor("foo", NULL_KEY, 42, 0.5, 0.5);
test("llSensorRepeat"); llSensorRepeat("foo", NULL_KEY, 42, 0.5, 0.5, 0.5);
test("llSensorRemove"); llSensorRemove();
test("llDetectedName"); stringResult = llDetectedName(42);
test("llDetectedKey"); keyResult = llDetectedKey(42);
test("llDetectedOwner"); keyResult = llDetectedOwner(42);
test("llDetectedType"); integerResult = llDetectedType(42);
test("llDetectedPos"); vectorResult = llDetectedPos(42);
test("llDetectedVel"); vectorResult = llDetectedVel(42);
test("llDetectedGrab"); vectorResult = llDetectedGrab(42);
test("llDetectedRot"); rotationResult = llDetectedRot(42);
test("llDetectedGroup"); integerResult = llDetectedGroup(42);
test("llDetectedLinkNumber"); integerResult = llDetectedLinkNumber(42);
test("llDie"); //llDie();
test("llGround"); floatResult = llGround(<1.1,2.2,3.3>);
test("llCloud"); floatResult = llCloud(<1.1,2.2,3.3>);
test("llWind"); vectorResult = llWind(<1.1,2.2,3.3>);
test("llSetStatus"); llSetStatus(42, 42);
test("llGetStatus"); integerResult = llGetStatus(42);
test("llSetScale"); llSetScale(<1.1,2.2,3.3>);
test("llGetScale"); vectorResult = llGetScale();
test("llSetColor"); llSetColor(<1.1,2.2,3.3>, 42);
test("llGetColor"); vectorResult = llGetColor(0);
test("llSetAlpha"); llSetAlpha(0.5, 42);
test("llGetAlpha"); floatResult = llGetAlpha(42);
test("llSetTexture"); llSetTexture("foo", 42);
test("llScaleTexture"); llScaleTexture(0.5, 0.5, 42);
test("llOffsetTexture"); llOffsetTexture(0.5, 0.5, 42);
test("llRotateTexture"); llRotateTexture(0.5, 42);
test("llGetTexture"); stringResult = llGetTexture(42);
test("llSetPos"); //llSetPos(<1.1,2.2,3.3>);
test("llGetPos"); vectorResult = llGetPos();
test("llGetLocalPos"); vectorResult = llGetLocalPos();
test("llSetRot"); llSetRot(<1.1,2.2,3.3,4.4>);
test("llGetRot"); rotationResult = llGetRot();
test("llGetLocalRot"); rotationResult = llGetLocalRot();
test("llSetForce"); llSetForce(<1.1,2.2,3.3>, 42);
test("llGetForce"); vectorResult = llGetForce();
test("llMoveToTarget"); llMoveToTarget(<1.1,2.2,3.3>, 0.5);
test("llStopMoveToTarget"); llStopMoveToTarget();
test("llTarget"); integerResult = llTarget(<1.1,2.2,3.3>, 0.5);
test("llTargetRemove"); llTargetRemove(42);
test("llRotTarget"); integerResult = llRotTarget(<1.1,2.2,3.3,4.4>, 0.5);
test("llRotTargetRemove"); llRotTargetRemove(42);
test("llApplyImpulse"); llApplyImpulse(<1.1,2.2,3.3>, 42);
test("llApplyRotationalImpulse"); llApplyRotationalImpulse(<1.1,2.2,3.3>, 42);
test("llSetTorque"); llSetTorque(<1.1,2.2,3.3>, 42);
test("llGetTorque"); vectorResult = llGetTorque();
test("llSetForceAndTorque"); llSetForceAndTorque(<1.1,2.2,3.3>, <1.1,2.2,3.3>, 42);
test("llGetVel"); vectorResult = llGetVel();
test("llGetAccel"); vectorResult = llGetAccel();
test("llGetOmega"); vectorResult = llGetOmega();
test("llGetTimeOfDay"); floatResult = llGetTimeOfDay();
test("llGetWallclock"); floatResult = llGetWallclock();
test("llGetTime"); floatResult = llGetTime();
test("llResetTime"); //llResetTime();
test("llGetAndResetTime"); //floatResult = llGetAndResetTime();
test("llSound"); llSound("foo", 0.5, 42, 42);
test("llPlaySound"); llPlaySound(NULL_KEY, 0.5);
test("llLoopSound"); llLoopSound("foo", 0.5);
test("llLoopSoundMaster"); llLoopSoundMaster("foo", 0.5);
test("llLoopSoundSlave"); llLoopSoundSlave("foo", 0.5);
test("llPlaySoundSlave"); llPlaySoundSlave("foo", 0.5);
test("llTriggerSound"); llTriggerSound(NULL_KEY, 0.5);
test("llStopSound"); llStopSound();
test("llPreloadSound"); llPreloadSound("foo");
test("llGetSubString"); stringResult = llGetSubString("foo", 42, 42);
test("llDeleteSubString"); stringResult = llDeleteSubString("foo", 42, 42);
test("llInsertString"); stringResult = llInsertString("foo", 42, "foo");
test("llToUpper"); stringResult = llToUpper("foo");
test("llToLower"); stringResult = llToLower("foo");
test("llGiveMoney"); integerResult = llGiveMoney(NULL_KEY, 42);
//test("llMakeExplosion"); llMakeExplosion(42, 0.5, 0.5, 0.5, 0.5, "foo", <1.1,2.2,3.3>);
//test("llMakeFountain"); llMakeFountain(42, 0.5, 0.5, 0.5, 0.5, "foo", <1.1,2.2,3.3>);
test("llMakeSmoke"); llMakeSmoke(42, 0.5, 0.5, 0.5, 0.5, "foo", <1.1,2.2,3.3>);
test("llMakeFire"); llMakeFire(42, 0.5, 0.5, 0.5, 0.5, "foo", <1.1,2.2,3.3>);
test("llRezObject"); llRezObject("foo", <1.1,2.2,3.3>, <1.1,2.2,3.3>, <1.1,2.2,3.3,4.4>, 42);
test("llLookAt"); llLookAt(<1.1,2.2,3.3>, 0.5, 0.5);
test("llStopLookAt"); llStopLookAt();
test("llSetTimerEvent"); llSetTimerEvent(0.5);
test("llSleep"); llSleep(0.5);
test("llGetMass"); floatResult = llGetMass();
test("llCollisionFilter"); llCollisionFilter("foo", NULL_KEY, 42);
test("llTakeControls"); llTakeControls(42, 42, 42);
test("llReleaseControls"); llReleaseControls();
test("llAttachToAvatar"); llAttachToAvatar(42);
test("llDetachFromAvatar"); llDetachFromAvatar();
test("llGetOwner"); keyResult = llGetOwner();
test("llInstantMessage"); llInstantMessage(NULL_KEY, "foo");
test("llEmail"); llEmail("foo", "foo", "foo");
test("llGetNextEmail"); llGetNextEmail("foo", "foo");
test("llGetKey"); keyResult = llGetKey();
test("llSetBuoyancy"); llSetBuoyancy(0.5);
test("llSetHoverHeight"); llSetHoverHeight(0.5, 42, 0.5);
test("llStopHover"); llStopHover();
test("llMinEventDelay"); llMinEventDelay(0.5);
test("llSoundPreload"); llSoundPreload(NULL_KEY);
test("llRotLookAt"); llRotLookAt(<1.1,2.2,3.3,4.4>, 0.5, 0.5);
test("llStringLength"); integerResult = llStringLength("foo");
test("llStartAnimation"); llStartAnimation("foo");
test("llStopAnimation"); llStopAnimation("foo");
test("llPointAt"); llPointAt(<1.1,2.2,3.3>);
test("llStopPointAt"); llStopPointAt();
test("llTargetOmega"); llTargetOmega(<1.1,2.2,3.3>, 0.5, 0.5);
test("llGetStartParameter"); integerResult = llGetStartParameter();
//test("llGodLikeRezObject"); llGodLikeRezObject(NULL_KEY, <1.1,2.2,3.3>);
test("llRequestPermissions"); llRequestPermissions(NULL_KEY, 42);
test("llGetPermissionsKey"); keyResult = llGetPermissionsKey();
test("llGetPermissions"); integerResult = llGetPermissions();
test("llGetLinkNumber"); integerResult = llGetLinkNumber();
test("llSetLinkColor"); llSetLinkColor(42, <1.1,2.2,3.3>, 42);
test("llCreateLink"); llCreateLink(NULL_KEY, 42);
test("llBreakLink"); llBreakLink(42);
test("llLinks"); llBreakAllLinks();
test("llGetLinkKey"); keyResult = llGetLinkKey(42);
test("llGetLinkName"); stringResult = llGetLinkName(42);
test("llGetInventoryNumber"); integerResult = llGetInventoryNumber(42);
test("llGetInventoryName"); stringResult = llGetInventoryName(42, 42);
test("llSetScriptState"); llSetScriptState("foo", 42);
test("llGetEnergy"); floatResult = llGetEnergy();
test("llGiveInventory"); llGiveInventory(NULL_KEY, "foo");
test("llRemoveInventory"); llRemoveInventory("foo");
test("llSetText"); llSetText("foo", <1.1,2.2,3.3>, 0.5);
test("llWater"); floatResult = llWater(<1.1,2.2,3.3>);
test("llPassTouches"); llPassTouches(42);
test("llRequestAgentData"); keyResult = llRequestAgentData(NULL_KEY, 42);
test("llRequestInventoryData"); keyResult = llRequestInventoryData("foo");
test("llSetDamage"); llSetDamage(0.5);
test("llTeleportAgentHome"); llTeleportAgentHome(NULL_KEY);
test("llModifyLand"); llModifyLand(42, 42);
test("llCollisionSound"); llCollisionSound("foo", 0.5);
test("llCollisionSprite"); llCollisionSprite("foo");
test("llGetAnimation"); stringResult = llGetAnimation(NULL_KEY);
test("llGetAnimationList"); listResult = llGetAnimationList(NULL_KEY);
//test("llResetScript"); llResetScript();
test("llMessageLinked"); llMessageLinked(42, 42, "foo", NULL_KEY);
test("llPushObject"); llPushObject(NULL_KEY, <1.1,2.2,3.3>, <1.1,2.2,3.3>, 42);
test("llPassCollisions"); llPassCollisions(42);
test("llGetScriptName"); stringResult = llGetScriptName();
test("llGetNumberOfSides"); integerResult = llGetNumberOfSides();
test("llAxisAngle2Rot"); rotationResult = llAxisAngle2Rot(<1.1,2.2,3.3>, 0.5);
test("llRot2Axis"); vectorResult = llRot2Axis(<1.1,2.2,3.3,4.4>);
test("llRot2Angle"); floatResult = llRot2Angle(<1.1,2.2,3.3,4.4>);
test("llAcos"); floatResult = llAcos(0.5);
test("llAsin"); floatResult = llAsin(0.5);
test("llAngleBetween"); floatResult = llAngleBetween(<1.1,2.2,3.3,4.4>, <1.1,2.2,3.3,4.4>);
}

default
{
touch_start(integer total_number)
{
llResetTime();
tests();
llSay(0, "Ran " + (string) gTests + " tests in " + (string) llGetTime() + " seconds");
gTests = 0;
}
}
</pre>

LSL Language Test

2008-02-05T01:02:55Z

Phoenix Linden:

[[Category:Conformance Test]]

* Tests all LSL language features
* To run, rez a prim, add this script, then touch the prim
* On successful completion, says "Ran N tests in X seconds with 0 failures"
* For more verbose reporting, uncomment llSay call in testPassed

<lsl>integer gTestsPassed = 0;
integer gTestsFailed = 0;

testPassed(string description, string actual, string expected)
{
++gTestsPassed;
//llSay(0, description);
}

testFailed(string description, string actual, string expected)
{
++gTestsFailed;
llSay(0, "FAILED!: " + description + " (" + actual + " expected " + expected + ")");
}

ensureTrue(string description, integer actual)
{
if(actual)
{
testPassed(description, (string) actual, (string) TRUE);
}
else
{
testFailed(description, (string) actual, (string) TRUE);
}
}

ensureFalse(string description, integer actual)
{
if(actual)
{
testFailed(description, (string) actual, (string) FALSE);
}
else
{
testPassed(description, (string) actual, (string) FALSE);
}
}

ensureIntegerEqual(string description, integer actual, integer expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

integer floatEqual(float actual, float expected)
{
float error = llFabs(expected - actual);
float epsilon = 0.001;
if(error > epsilon)
{
llSay(0,"Float equality delta " + (string)error);
return FALSE;
}
return TRUE;
}

ensureFloatEqual(string description, float actual, float expected)
{
if(floatEqual(actual, expected))
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureStringEqual(string description, string actual, string expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureVectorEqual(string description, vector actual, vector expected)
{
if(floatEqual(actual.x, expected.x) &&
floatEqual(actual.y, expected.y) &&
floatEqual(actual.z, expected.z))
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureRotationEqual(string description, rotation actual, rotation expected)
{
if(floatEqual(actual.x, expected.x) &&
floatEqual(actual.y, expected.y) &&
floatEqual(actual.z, expected.z) &&
floatEqual(actual.s, expected.s))
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureListEqual(string description, list actual, list expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

integer gInteger = 5;
float gFloat = 1.5;
string gString = "foo";
vector gVector = <1, 2, 3>;
rotation gRot = <1, 2, 3, 4>;
list gList = [1, 2, 3];

integer testReturn()
{
return 1;
}

float testReturnFloat()
{
return 1;
}

string testReturnString()
{
return "Test string";
}

list testReturnList()
{
return [1,2,3];
}

vector testReturnVector()
{
return <1,2,3>;
}

rotation testReturnRotation()
{
return <1,2,3,4>;
}

vector testReturnVectorNested()
{
return testReturnVector();
}

vector testReturnVectorWithLibraryCall()
{
llSin(0);
return <1,2,3>;
}

rotation testReturnRotationWithLibraryCall()
{
llSin(0);
return <1,2,3,4>;
}

integer testParameters(integer param)
{
param = param + 1;
return param;
}

integer testRecursion(integer param)
{
if(param <= 0)
{
return 0;
}
else
{
return testRecursion(param - 1);
}
}

string testExpressionLists(list l)
{
return "foo" + (string)l;
}

tests()
{
// truth
ensureIntegerEqual("TRUE", TRUE, TRUE);
ensureIntegerEqual("FALSE", FALSE, FALSE);

if(0.0)
{
testFailed("if(0.0)", "TRUE", "FALSE");
}
else
{
testPassed("if(0.0)", "TRUE", "TRUE");
}
if(0.000001)
{
testPassed("if(0.000001)", "TRUE", "TRUE");
}
else
{
testFailed("if(0.000001)", "TRUE", "FALSE");
}
if(0.9)
{
testPassed("if(0.9)", "TRUE", "TRUE");
}
else
{
testFailed("if(0.9)", "TRUE", "FALSE");
}
if(ZERO_VECTOR)
{
testFailed("if(ZERO_VECTOR)", "TRUE", "FALSE");
}
else
{
testPassed("if(ZERO_VECTOR)", "TRUE", "TRUE");
}
if(ZERO_ROTATION)
{
testFailed("if(ZERO_ROTATION)", "TRUE", "FALSE");
}
else
{
testPassed("if(ZERO_ROTATION)", "TRUE", "TRUE");
}

if(NULL_KEY)
{
testPassed("if(NULL_KEY)", "TRUE", "TRUE");
}
else
{
testFailed("if(NULL_KEY)", "TRUE", "FALSE");
}
if((key)NULL_KEY)
{
testFailed("if((key)NULL_KEY)", "TRUE", "FALSE");
}
else
{
testPassed("if((key)NULL_KEY)", "TRUE", "TRUE");
}

if("")
{
testFailed("if(\"\")", "TRUE", "FALSE");
}
else
{
testPassed("if(\"\")", "TRUE", "TRUE");
}

if([])
{
testFailed("if([])", "TRUE", "FALSE");
}
else
{
testPassed("if([])", "TRUE", "TRUE");
}

// equality
ensureIntegerEqual("(TRUE == TRUE)", (TRUE == TRUE), TRUE);
ensureIntegerEqual("(TRUE == FALSE)", (TRUE == FALSE), FALSE);
ensureIntegerEqual("(FALSE == TRUE)", (FALSE == TRUE), FALSE);
ensureIntegerEqual("(FALSE == FALSE)", (FALSE == FALSE), TRUE);

// inequality
ensureIntegerEqual("(TRUE != TRUE)", (TRUE != TRUE), FALSE);
ensureIntegerEqual("(TRUE != FALSE)", (TRUE != FALSE), TRUE);
ensureIntegerEqual("(FALSE != TRUE)", (FALSE != TRUE), TRUE);
ensureIntegerEqual("(FALSE != FALSE)", (FALSE != FALSE), FALSE);

// and
ensureIntegerEqual("(TRUE && TRUE)", (TRUE && TRUE), TRUE);
ensureIntegerEqual("(TRUE && FALSE)", (TRUE && FALSE), FALSE);
ensureIntegerEqual("(FALSE && TRUE)", (FALSE && TRUE), FALSE);
ensureIntegerEqual("(FALSE && FALSE)", (FALSE && FALSE), FALSE);

// and
ensureIntegerEqual("(1 && 2)", (1 && 2), TRUE);
ensureIntegerEqual("(1 && 0)", (1 && 0), FALSE);
ensureIntegerEqual("(0 && 2)", (0 && 2), FALSE);
ensureIntegerEqual("(0 && 0)", (0 && 0), FALSE);

// or
ensureIntegerEqual("(TRUE || TRUE)", (TRUE || TRUE), TRUE);
ensureIntegerEqual("(TRUE || FALSE)", (TRUE || FALSE), TRUE);
ensureIntegerEqual("(FALSE || TRUE)", (FALSE || TRUE), TRUE);
ensureIntegerEqual("(FALSE || FALSE)", (FALSE || FALSE), FALSE);

// or
ensureIntegerEqual("(1 || 2)", (1 || 2), TRUE);
ensureIntegerEqual("(1 || 0)", (1 || 0), TRUE);
ensureIntegerEqual("(0 || 2)", (0 || 2), TRUE);
ensureIntegerEqual("(0 || 0)", (0 || 0), FALSE);

// not
ensureIntegerEqual("(! TRUE)", (! TRUE), FALSE);
ensureIntegerEqual("(! FALSE)", (! FALSE), TRUE);

// not
ensureIntegerEqual("(! 2)", (! 2), FALSE);
ensureIntegerEqual("(! 0)", (! 0), TRUE);

// greater than
ensureIntegerEqual("(1 > 0)", (1 > 0), TRUE);
ensureIntegerEqual("(0 > 1)", (0 > 1), FALSE);
ensureIntegerEqual("(1 > 1)", (1 > 1), FALSE);

// less than
ensureIntegerEqual("(0 < 1)", (0 < 1), TRUE);
ensureIntegerEqual("(1 < 0)", (1 < 0), FALSE);
ensureIntegerEqual("(1 < 1)", (1 < 1), FALSE);

// greater than or equal
ensureIntegerEqual("(1 >= 0)", (1 >= 0), TRUE);
ensureIntegerEqual("(0 >= 1)", (0 >= 1), FALSE);
ensureIntegerEqual("(1 >= 1)", (1 >= 1), TRUE);

// tess than or equal
ensureIntegerEqual("(0 <= 1)", (0 <= 1), TRUE);
ensureIntegerEqual("(1 <= 0)", (1 <= 0), FALSE);
ensureIntegerEqual("(1 <= 1)", (1 <= 1), TRUE);

// bitwise and
ensureIntegerEqual("(10 & 25)", (10 & 25), 8);

// bitwise or
ensureIntegerEqual("(10 | 25)", (10 | 25), 27);

// bitwise not
ensureIntegerEqual("~10", ~10, -11);

// xor
ensureIntegerEqual("(10 ^ 25)", (10 ^ 25), 19);

// right shift
ensureIntegerEqual("(523 >> 2)", (523 >> 2), 130);

// left shift
ensureIntegerEqual("(523 << 2)", (523 << 2), 2092);

// addition
ensureIntegerEqual("(1 + 1)", (1 + 1), 2);
ensureFloatEqual("(1 + 1.1)", (1 + 1.1), 2.1);
ensureFloatEqual("(1.1 + 1)", (1.1 + 1), 2.1);
ensureFloatEqual("(1.1 + 1.1)", (1.1 + 1.1), 2.2);
ensureStringEqual("\"foo\" + \"bar\"", "foo" + "bar", "foobar");
ensureVectorEqual("(<1.1, 2.2, 3.3> + <4.4, 5.5, 6.6>)", (<1.1, 2.2, 3.3> + <4.4, 5.5, 6.6>), <5.5, 7.7, 9.9>);
ensureRotationEqual("(<1.1, 2.2, 3.3, 4.4> + <4.4, 5.5, 6.6, 3.3>)", (<1.1, 2.2, 3.3, 4.4> + <4.4, 5.5, 6.6, 3.3>), <5.5, 7.7, 9.9, 7.7>);
ensureListEqual("([1] + 2)", ([1] + 2), [1,2]);
ensureListEqual("([] + 1.5)", ([] + 1.5), [1.5]);
ensureListEqual("([\"foo\"] + \"bar\")", (["foo"] + "bar"), ["foo", "bar"]);
ensureListEqual("([] + <1,2,3>)", ([] + <1,2,3>), [<1,2,3>]);
ensureListEqual("([] + <1,2,3,4>)", ([] + <1,2,3,4>), [<1,2,3,4>]);

ensureListEqual("(1 + [2])", (1 + [2]), [1,2]);
ensureListEqual("(1.0 + [2])", (1.0 + [2]), [1.0,2]);
ensureListEqual("(1 + [2])", ("one" + [2]), ["one",2]);
ensureListEqual("(<1.0,1.0,1.0,1.0> + [2])", (<1.0,1.0,1.0,1.0> + [2]), [<1.0,1.0,1.0,1.0>,2]);
ensureListEqual("(<1.0,1.0,1.0> + [2])", (<1.0,1.0,1.0> + [2]), [<1.0,1.0,1.0>,2]);

// subtraction
ensureIntegerEqual("(1 - 1)", (1 - 1), 0);
ensureFloatEqual("(1 - 0.5)", (1 - 0.5), 0.5);
ensureFloatEqual("(1.5 - 1)", (1.5 - 1), 0.5);
ensureFloatEqual("(2.2 - 1.1)", (2.2 - 1.1), 1.1);
ensureVectorEqual("(<1.5, 2.5, 3.5> - <4.5, 5.5, 6.5>)", (<1.5, 2.5, 3.5> - <4.5, 5.5, 6.5>), <-3.0, -3.0, -3.0>);
ensureRotationEqual("(<1.5, 2.5, 3.5, 4.5> - <4.5, 5.5, 6.5, 7.5>)", (<1.5, 2.5, 3.5, 4.5> - <4.5, 5.5, 6.5, 7.5>), <-3.0, -3.0, -3.0, -3.0>);

// multiplication
ensureIntegerEqual("(2 * 3)", (2 * 3), 6);
ensureFloatEqual("(2 * 3.5)", (2 * 3.5), 7.0);
ensureFloatEqual("(2.5 * 3)", (2.5 * 3), 7.5);
ensureFloatEqual("(2.5 * 3.5)", (2.5 * 3.5), 8.75);
ensureVectorEqual("(<1.1, 2.2, 3.3> * 2)", (<1.1, 2.2, 3.3> * 2), <2.2, 4.4, 6.6>);
ensureVectorEqual("(2 * <1.1, 2.2, 3.3>)", (<1.1, 2.2, 3.3> * 2), (2 * <1.1, 2.2, 3.3>));
ensureVectorEqual("(<2.2, 4.4, 6.6> * 2.0)", (<2.2, 4.4, 6.6> * 2.0), <4.4, 8.8, 13.2>);
ensureVectorEqual("(2.0 * <2.2, 4.4, 6.6>)", (<2.2, 4.4, 6.6> * 2.0), (2.0 * <2.2, 4.4, 6.6>));
ensureFloatEqual("<1,3,-5> * <4,-2,-1>", <1,3,-5> * <4,-2,-1>, 3.0);
ensureVectorEqual("<-1,0,0> * <0, 0, 0.707, 0.707>", <-1,0,0> * <0, 0, 0.707, 0.707>, <0,-1, 0>);
ensureRotationEqual("(<1.0, 2.0, 3.0, 4.0> * <5.0, 6.0, 7.0, 8.0>)", (<1.0, 2.0, 3.0, 4.0> * <5.0, 6.0, 7.0, 8.0>), <32.0, 32.0, 56.0, -6.0>);

// division
ensureIntegerEqual("(2 / 2)", (2 / 2), 1);
ensureFloatEqual("(2.2 / 2)", (2.2 / 2), 1.1);
ensureFloatEqual("(3 / 1.5)", (3 / 1.5), 2.0);
ensureFloatEqual("(2.2 / 2.0)", (2.2 / 2.0), 1.1);
ensureVectorEqual("(<1.0, 2.0, 3.0> / 2)", (<1.0, 2.0, 3.0> / 2), <0.5, 1.0, 1.5>);
ensureVectorEqual("(<3.0, 6.0, 9.0> / 1.5)", (<3.0, 6.0, 9.0> / 1.5), <2.0, 4.0, 6.0>);
ensureVectorEqual("<-1,0,0> / <0, 0, 0.707, 0.707>", <-1,0,0> / <0, 0, 0.707, 0.707>, <0,1, 0>);
ensureRotationEqual("(<1.0, 2.0, 3.0, 4.0> / <5.0, 6.0, 7.0, 8.0>)", (<1.0, 2.0, 3.0, 4.0> / <5.0, 6.0, 7.0, 8.0>), <-16.0, 0.0, -8.0, 70.0>);

// modulo
ensureIntegerEqual("(3 % 1)", (3 % 1), 0);
ensureVectorEqual("(<1.0, 2.0, 3.0> % <4.0, 5.0, 6.0>)", (<1.0, 2.0, 3.0> % <4.0, 5.0, 6.0>), <-3.0, 6.0, -3.0>);

// assignment
integer i = 1;
ensureIntegerEqual("i = 1;", i, 1);

// addition assignment
i = 1;
i += 1;
ensureIntegerEqual("i = 1; i += 1;", i, 2);

// subtraction assignment
i = 1;
i -= 1;
ensureIntegerEqual("i = 1; i -= 1;", i, 0);

// multiplication assignment integer *= integer
i = 2;
i *= 2;
ensureIntegerEqual("i = 2; i *= 2;", i, 4);

// multiplication assignment integer *= float
i = 1;
i *= 0.5;
ensureIntegerEqual("i = 1; i *= 0.5;", i, 0);

// division assignment
i = 2;
i /= 2;
ensureIntegerEqual("i = 2; i /= 2;", i, 1);

// modulo assignment
i = 3;
i %= 1;
ensureIntegerEqual("i = 3; i %= 1;", i, 0);

// post increment.
i = 1;
ensureIntegerEqual("i = 1; (i == 2) && (i++ == 1)", (i == 2) && (i++ == 1), TRUE);

// pre increment.
i = 1;
ensureIntegerEqual("i = 1; (i == 2) && (++i == 2)", (i == 2) && (++i == 2), TRUE);

// post decrement.
i = 2;
ensureIntegerEqual("i = 2; (i == 1) && (i-- == 2)", (i == 1) && (i-- == 2), TRUE);

// pre decrement.
i = 2;
ensureIntegerEqual("i = 2; (i == 1) && (--i == 1)", (i == 1) && (--i == 1), TRUE);
i = 2; --i;
ensureIntegerEqual("i = 2; --i", i, 1);

// casting
ensureFloatEqual("((float)2)", ((float)2), 2.0);
ensureStringEqual("((string)2)", ((string)2), "2");
ensureIntegerEqual("((integer) 1.5)", ((integer) 1.5), 1);
ensureStringEqual("((string) 1.5)", ((string) 1.5), "1.500000");
ensureIntegerEqual("((integer) \"0xF\")", ((integer) "0xF"), 15);
ensureIntegerEqual("((integer) \"2\")", ((integer) "2"), 2);
ensureFloatEqual("((float) \"1.5\")", ((float) "1.5"), 1.5);
ensureVectorEqual("((vector) \"<1,2,3>\")", ((vector) "<1,2,3>"), <1,2,3>);
ensureRotationEqual("((quaternion) \"<1,2,3,4>\")", ((quaternion) "<1,2,3,4>"), <1,2,3,4>);
ensureStringEqual("((string) <1,2,3>)", ((string) <1,2,3>), "<1.00000, 2.00000, 3.00000>");
ensureStringEqual("((string) <1,2,3,4>)", ((string) <1,2,3,4>), "<1.00000, 2.00000, 3.00000, 4.00000>");
ensureStringEqual("((string) [1,2.5,<1,2,3>])", ((string) [1,2.5,<1,2,3>]), "12.500000<1.000000, 2.000000, 3.000000>");

// while
i = 0;
while(i < 10) ++i;
ensureIntegerEqual("i = 0; while(i < 10) ++i", i, 10);

// do while
i = 0;
do {++i;} while(i < 10);
ensureIntegerEqual("i = 0; do {++i;} while(i < 10);", i, 10);

// for
for(i = 0; i < 10; ++i);
ensureIntegerEqual("for(i = 0; i < 10; ++i);", i, 10);

// jump
i = 1;
jump SkipAssign;
llSetText("Error", <1,0,0>, 1); // Inserting this library call causes a save point to be added.
i = 2;
@SkipAssign;
ensureIntegerEqual("i = 1; jump SkipAssign; i = 2; @SkipAssign;", i, 1);

// return
ensureIntegerEqual("testReturn()", testReturn(), 1);
ensureFloatEqual("testReturnFloat()", testReturnFloat(), 1.0);
ensureStringEqual("testReturnString()", testReturnString(), "Test string");
ensureVectorEqual("testReturnVector()", testReturnVector(), <1,2,3>);
ensureRotationEqual("testReturnRotation()", testReturnRotation(), <1,2,3,4>);
ensureVectorEqual("testReturnVectorNested()", testReturnVectorNested(), <1,2,3>);
ensureVectorEqual("testReturnVectorWithLibraryCall()", testReturnVectorWithLibraryCall(), <1,2,3>);
ensureRotationEqual("testReturnRotationWithLibraryCall()", testReturnRotationWithLibraryCall(), <1,2,3,4>);

// parameters
ensureIntegerEqual("testParameters(1)", testParameters(1), 2);

// variable parameters
i = 1;
ensureIntegerEqual("i = 1; testParameters(i)", testParameters(i), 2);

// recursion
ensureIntegerEqual("testRecursion(10)", testRecursion(10), 0);

// globals
ensureIntegerEqual("gInteger", gInteger, 5);
ensureFloatEqual("gFloat", gFloat, 1.5);
ensureStringEqual("gString", gString, "foo");
ensureVectorEqual("gVector", gVector, <1, 2, 3>);
ensureRotationEqual("gRot", gRot, <1, 2, 3, 4>);
ensureListEqual("gList", gList, [1, 2, 3]);

// global assignment
gInteger = 1;
ensureIntegerEqual("gInteger = 1", gInteger, 1);

gFloat = 0.5;
ensureFloatEqual("gFloat = 0.5", gFloat, 0.5);

gString = "bar";
ensureStringEqual("gString = \"bar\"", gString, "bar");

gVector = <3,3,3>;
ensureVectorEqual("gVector = <3,3,3>", gVector, <3,3,3>);

gRot = <3,3,3,3>;
ensureRotationEqual("gRot = <3,3,3,3>", gRot, <3,3,3,3>);

gList = [4,5,6];
ensureListEqual("gList = [4,5,6]", gList, [4,5,6]);

// negation
gVector = <3,3,3>;
ensureVectorEqual("-gVector = <-3,-3,-3>", -gVector, <-3,-3,-3>);

gRot = <3,3,3,3>;
ensureRotationEqual("-gRot = <-3,-3,-3,-3>", -gRot, <-3,-3,-3,-3>);

// vector accessor
vector v;
v.x = 3;
ensureFloatEqual("v.x", v.x, 3);

// rotation accessor
rotation q;
q.s = 5;
ensureFloatEqual("q.s", q.s, 5);

// global vector accessor
gVector.y = 17.5;
ensureFloatEqual("gVector.y = 17.5", gVector.y, 17.5);

// global rotation accessor
gRot.z = 19.5;
ensureFloatEqual("gRot.z = 19.5", gRot.z, 19.5);

// list equality
list l = (list) 5;
list l2 = (list) 5;
ensureListEqual("list l = (list) 5; list l2 = (list) 5", l, l2);
ensureListEqual("list l = (list) 5", l, [5]);
ensureListEqual("[1.5, 6, <1,2,3>, <1,2,3,4>]", [1.5, 6, <1,2,3>, <1,2,3,4>], [1.5, 6, <1,2,3>, <1,2,3,4>]);

// String escaping
ensureIntegerEqual("llStringLength(\"\\\") == 1", llStringLength("\\"), 1);
ensureIntegerEqual("llStringLength(\"\\t\") == 4", llStringLength("\t"), 4);
ensureIntegerEqual("llStringLength(\"\\n\") == 1", llStringLength("\n"), 1);
ensureIntegerEqual("llStringLength(\"\\\"\") == 1", llStringLength("\""), 1);

// Nested expression lists
ensureStringEqual("testExpressionLists([testExpressionLists([]), \"bar\"]) == \"foofoobar\"", testExpressionLists([testExpressionLists([]), "bar"]), "foofoobar");

}

default
{
touch_start(integer total_number)
{
llResetTime();
tests();
llSay(0, "Ran " + (string)(gTestsPassed + gTestsFailed) + " tests in " + (string) llGetTime() + " seconds with " + (string)gTestsFailed + " failures");

// reset globals
gInteger = 5;
gFloat = 1.5;
gString = "foo";
gVector = <1, 2, 3>;
gRot = <1, 2, 3, 4>;
gList = [1, 2, 3];
gTestsPassed = 0;
gTestsFailed = 0;
}

http_response(key request_id, integer status, list metadata, string body)
{

}
}
</lsl>

LSL Test Harness

2008-02-04T23:00:19Z

Phoenix Linden:

{{Multi-lang}}{{LSL Header}}
The LSL Test Harness is a platform for testing LSL scripts developed for Linden Lab by i3D Inc. Second Life developers may want to use this to confirm that their scripts function consistently from update to update. The test harness is freely available (under Creative Commons license: [http://creativecommons.org/licenses/by-sa/2.5/ Attribution-ShareAlike 2.5]) to download and use.

The LSL Test Harness consists of three or more inworld objects. You can create any object, even use the default plywood cube prim, just ensure that you place the appropriate scripts and notecards in the proper objects.

= The Controller =
The controller provides the interface for you to issue instructions to the test harness. It will listen to your commands on a chat channel and execute them. Alternatively you can make a touch-based controller.

* Rez or create an object, name it Controller.
* Add the script Controller_Controller (available to copy/paste [[Controller_Controller.lsl | here]]).

= The Coordinator =
The coordinator handles the communication between the controller and the actual test units themselves.

* Rez or create an object, name it Coordinator
* Add the following scripts: (available to copy/paste at the linked locations)
** [[Coordinator_Coordinator.lsl | Coordinator.Coordinator]]
** [[Coordinator_TestUnits.lsl | Coordinator_TestUnits]]
** [[Coordinator_TestUnitsReports.lsl | Coordinator_TestUnitsReports]]
* Now add the notecard [[Coordinator_nc | Coordinator_nc]] and open it
** If you wish to have the harness send you reports via email, add your email address to the email field
** If you want the harness to http post the reports, add your url to the Http: field

= The Test Unit(s) =
The Test Units actually conduct the LSL tests. Therefore they consist of a generic script for running tests, plus the specific script (which you write) which holds the testing code. You may create as many test units as you need. To facilitate development of test scripts, several examples are included in the code repository (here) and these may be used as templates.

* Rez or create an object and call it something descriptive (e.g. Test Unit - Rotations).
* Add the script [[TestUnit_TestHarness.lsl | TestUnit_TestHarness]]
* Add the notecard [[TestUnit_nc | TestUnit_nc]]
** Open the notecard and edit the UnitName and GroupName fields
*** UnitName is the name you want for this particular test
*** GroupName specifies a family of tests, in case you want to do something like run all your math testing test units (you'd define a groupName "Math").
* Add your test script which should be called [GroupName]_[UnitName]
** You can use [[TestUnit_TestScript.lsl | TestUnit_TestScript.lsl]] as a template
** Just add your test lsl to the indicated section and report the result
* Alternatively, there are some sample test scripts at [[Test_Harness_Test_Units | Test Harness Sample Tests]]

= Commands =
Once you have the Controller, Coordinator, and all your Test Units rezzed, ensure that they are within chat distance of each other, and then you can issue the following commands in the control channel (default is 1234)

* '''ActivateRegistration''' will make the coordinator round up all test units in chat range
* '''ActivateTest''' will start all selected test units
* '''ActivateReport''' will generate your specified report (chat, email, http)
* '''Reset''' will reset all test units
* '''SetTestSelected''' will specify which test units should execute
** SetTestSelected::All all test units in range
** SetTestSelected::[GroupName] all units in that group
** SetTestSelected::[UnitName] a specific unit
* '''SetReportMethod''' you can choose from three report methods
** SetReportMethod::CHAT::channel::0 for open chat
** SetReportMethod::EMAIL::address::you@yourdomain.com
** SetReportMethod::HTTP::url::www.yoururl.com
* '''SetReportType''' - specify report type as NORMAL, QUITE, VERBOSE, STATS
** SetReportType::NORMAL
* '''SetControlChannel''' used to change the internal comm channel
* '''SetBroadcastChannel''' chat channel for report output (typically 0)

=Repository for the LSL test harness=
This is the repository for the LSL test harness - update this wiki as you update the harness!

[[Test Harness Control Buttons]]

[[Test Harness Controller]]

[[Test Harness Test Units]]

[[Test Harness PHP]]

= Tests =
All known tests should be in [[:Category:Conformance Test]].

TestUnit TestScript LSL Language.lsl

2008-02-04T22:58:46Z

Phoenix Linden:

[[Category:Conformance Test]]

<pre>
///////////////////////////////////////////////////////////////////////////////////
///////
///////
///////
/////// TestUnit_TestScript
///////
///////
///////
/////// This is the test script that should include the code you want to test.
///////
///////
//////////////////////////////////////////////////////////////////////////////////////

//TestUnit_TestScript .1 -> initial framework 6.23.2007
//TestUnit_TestScript .2 -> tested with minor bug fixes 7.2.2007

//////////////////////////////////////////////////////////////////////////////////////
//
// Command Protocol
//
//////////////////////////////////////////////////////////////////////////////////////
//
//////////////////////////////////////////////
// CHAT commands
//////////////////////////////////////////////
//
// Chat commands will be on the specified broadcastChannel
//
//////// OUTPUT ///////////
//
// AddUnitReport - send Report update to Coordinator on the chat broadcastChannel
// format example -> AddUnitReport::unitKey::00000-0000-0000-00000::Report::Successful Completion of Test
//
//////////////////////////////////////////////
// LINK MESSAGE commands
//////////////////////////////////////////////
//
// link message commands will be sent out on the toAllChannel, and recieved on the passFailChannel
//
//////// INPUT ///////////
//
// RunTest - activation command to start test
// format example -> RunTest
//
// Report - channel and report type
// format example -> Report::controlChannel::0::reportType::NORMAL
//
// Reset - rest the scripts
// format example -> Reset
//
//////// OUTPUT ///////////
//
// passFail - status of test sent on passFailChannel
// format example -> PASS
//
//////////////////////////////////////////////////////////////////////////////////////////

// Global Variables

integer toAllChannel = -255; // general channel - linked message
integer passFailChannel = -355; // test scripts channel for cummunicating pass/fail - linked message

integer debug = 0; // level of debug message
integer debugChannel = DEBUG_CHANNEL; // output channel for debug messages

integer gTestsPassed = 0;
integer gTestsFailed = 0;

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: ParseCommand
//////////
////////// Input: string message - command to be parsed
//////////
////////// Output: no return value
//////////
////////// Purpose: This function calls various other functions or sets globals
////////// depending on message string. Allows external command calls.
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
ParseCommand(string message)
{
if(debug > 1)llSay(debugChannel, llGetScriptName()+ "->ParseCommand: " + message);

//reset all scripts
if(message == "Reset")
{
//reset this script
llResetScript();
}

//RunTest()
else if(message == "RunTest")
{
RunTest();
}

//Report()
//Example format -> Report::broadcastChannel::0::reportType::NORMAL
else if( llSubStringIndex(message, "Report") != -1 )
{
//parse the string command into a list
list reportParameters = llParseString2List( message, ["::"], [""] );

//find the broadcastChannel label and increment by one
integer tempIndex = llListFindList( reportParameters, ["controlChannel"] ) + 1;
//pull the broadcastChannel from the list with the index just calculated
integer controlChannel = llList2Integer( reportParameters , tempIndex);

//find the reportType label and increment by one
tempIndex = llListFindList( reportParameters, ["reportType"] ) + 1;
//pull the reportType from the list with the index just calculated
string reportType = llList2String( reportParameters , tempIndex);

//call the Report function with new parameters
Report( controlChannel, reportType );
}

} //end ParseCommand

///////////////////////////////////////////////////////////////////////////////////////////////////
// supporting functions
testPassed(string description, string actual, string expected)
{
++gTestsPassed;
//llSay(0, description);
}

testFailed(string description, string actual, string expected)
{
++gTestsFailed;
llSay(0, "FAILED!: " + description + " (" + actual + " expected " + expected + ")");
}

ensureTrue(string description, integer actual)
{
if(actual)
{
testPassed(description, (string) actual, (string) TRUE);
}
else
{
testFailed(description, (string) actual, (string) TRUE);
}
}

ensureFalse(string description, integer actual)
{
if(actual)
{
testFailed(description, (string) actual, (string) FALSE);
}
else
{
testPassed(description, (string) actual, (string) FALSE);
}
}

ensureIntegerEqual(string description, integer actual, integer expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureFloatEqual(string description, float actual, float expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureStringEqual(string description, string actual, string expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureVectorEqual(string description, vector actual, vector expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureRotationEqual(string description, rotation actual, rotation expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

ensureListEqual(string description, list actual, list expected)
{
if(actual == expected)
{
testPassed(description, (string) actual, (string) expected);
}
else
{
testFailed(description, (string) actual, (string) expected);
}
}

integer gInteger = 5;
float gFloat = 1.5;
string gString = "foo";
vector gVector = <1, 2, 3>;
rotation gRot = <1, 2, 3, 4>;

integer testReturn()
{
return 1;
}

integer testParameters(integer param)
{
param = param + 1;
return param;
}

integer testRecursion(integer param)
{
if(param <= 0)
{
return 0;
}
else
{
return testRecursion(param - 1);
}
}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: RunTest
//////////
////////// Input: no input paramaters
//////////
////////// Output: link message on passFailChannel test status
//////////
////////// Purpose: This function is where you put the scripts that you want to test
////////// with this unit.
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
RunTest()
{

// truth
ensureIntegerEqual("TRUE", TRUE, TRUE);
ensureIntegerEqual("FALSE", FALSE, FALSE);

// equality
ensureIntegerEqual("(TRUE == TRUE)", (TRUE == TRUE), TRUE);
ensureIntegerEqual("(TRUE == FALSE)", (TRUE == FALSE), FALSE);
ensureIntegerEqual("(TRUE == FALSE)", (TRUE == FALSE), FALSE);
ensureIntegerEqual("(FALSE == FALSE)", (FALSE == FALSE), TRUE);

// inequality
ensureIntegerEqual("(TRUE != TRUE)", (TRUE != TRUE), FALSE);
ensureIntegerEqual("(TRUE != FALSE)", (TRUE != FALSE), TRUE);
ensureIntegerEqual("(TRUE != FALSE)", (TRUE != FALSE), TRUE);
ensureIntegerEqual("(FALSE != FALSE)", (FALSE != FALSE), FALSE);

// and
ensureIntegerEqual("(TRUE && TRUE)", (TRUE && TRUE), TRUE);
ensureIntegerEqual("(TRUE && FALSE)", (TRUE && FALSE), FALSE);
ensureIntegerEqual("(FALSE && TRUE)", (FALSE && TRUE), FALSE);
ensureIntegerEqual("(FALSE && FALSE)", (FALSE && FALSE), FALSE);

// or
ensureIntegerEqual("(TRUE || TRUE)", (TRUE || TRUE), TRUE);
ensureIntegerEqual("(TRUE || FALSE)", (TRUE || FALSE), TRUE);
ensureIntegerEqual("(FALSE || TRUE)", (FALSE || TRUE), TRUE);
ensureIntegerEqual("(FALSE || FALSE)", (FALSE || FALSE), FALSE);

// not
ensureIntegerEqual("(! TRUE)", (! TRUE), FALSE);
ensureIntegerEqual("(! FALSE)", (! FALSE), TRUE);

// greater than
ensureIntegerEqual("(1 > 0)", (1 > 0), TRUE);
ensureIntegerEqual("(0 > 1)", (0 > 1), FALSE);
ensureIntegerEqual("(1 > 1)", (1 > 1), FALSE);

// less than
ensureIntegerEqual("(0 < 1)", (0 < 1), TRUE);
ensureIntegerEqual("(1 < 0)", (1 < 0), FALSE);
ensureIntegerEqual("(1 < 1)", (1 < 1), FALSE);

// greater than or equal
ensureIntegerEqual("(1 >= 0)", (1 >= 0), TRUE);
ensureIntegerEqual("(0 >= 1)", (0 >= 1), FALSE);
ensureIntegerEqual("(1 >= 1)", (1 >= 1), TRUE);

// tess than or equal
ensureIntegerEqual("(0 <= 1)", (0 <= 1), TRUE);
ensureIntegerEqual("(1 <= 0)", (1 <= 0), FALSE);
ensureIntegerEqual("(1 <= 1)", (1 <= 1), TRUE);

// bitwise and
ensureIntegerEqual("(10 & 25)", (10 & 25), 8);

// bitwise or
ensureIntegerEqual("(10 | 25)", (10 | 25), 27);

// bitwise not
ensureIntegerEqual("~10", ~10, -11);

// xor
ensureIntegerEqual("(10 ^ 25)", (10 ^ 25), 19);

// right shift
ensureIntegerEqual("(523 >> 2)", (523 >> 2), 130);

// left shift
ensureIntegerEqual("(523 << 2)", (523 << 2), 2092);

// addition
ensureIntegerEqual("(1 + 1)", (1 + 1), 2);
ensureFloatEqual("(1 + 1.1)", (1 + 1.1), 2.1);
ensureFloatEqual("(1.1 + 1)", (1.1 + 1), 2.1);
ensureFloatEqual("(1.1 + 1.1)", (1.1 + 1.1), 2.2);
ensureStringEqual("\"foo\" + \"bar\"", "foo" + "bar", "foobar");
ensureVectorEqual("(<1.1, 2.2, 3.3> + <4.4, 5.5, 6.6>)", (<1.1, 2.2, 3.3> + <4.4, 5.5, 6.6>), <5.5, 7.7, 9.9>);
ensureRotationEqual("(<1.1, 2.2, 3.3, 4.4> + <4.4, 5.5, 6.6, 3.3>)", (<1.1, 2.2, 3.3, 4.4> + <4.4, 5.5, 6.6, 3.3>), <5.5, 7.7, 9.9, 7.7>);
ensureListEqual("([1] + 2)", ([1] + 2), [1,2]);
ensureListEqual("([] + 1.5)", ([] + 1.5), [1.5]);
ensureListEqual("([\"foo\"] + \"bar\")", (["foo"] + "bar"), ["foo", "bar"]);
ensureListEqual("([] + <1,2,3>)", ([] + <1,2,3>), [<1,2,3>]);
ensureListEqual("([] + <1,2,3,4>)", ([] + <1,2,3,4>), [<1,2,3,4>]);

// subtraction
ensureIntegerEqual("(1 - 1)", (1 - 1), 0);
ensureFloatEqual("(1 - 0.5)", (1 - 0.5), 0.5);
ensureFloatEqual("(1.5 - 1)", (1.5 - 1), 0.5);
ensureFloatEqual("(2.2 - 1.1)", (2.2 - 1.1), 1.1);
ensureVectorEqual("(<1.5, 2.5, 3.5> - <4.5, 5.5, 6.5>)", (<1.5, 2.5, 3.5> - <4.5, 5.5, 6.5>), <-3.0, -3.0, -3.0>);
ensureRotationEqual("(<1.5, 2.5, 3.5, 4.5> - <4.5, 5.5, 6.5, 7.5>)", (<1.5, 2.5, 3.5, 4.5> - <4.5, 5.5, 6.5, 7.5>), <-3.0, -3.0, -3.0, -3.0>);

// multiplication
ensureIntegerEqual("(2 * 3)", (2 * 3), 6);
ensureFloatEqual("(2 * 3.5)", (2 * 3.5), 7.0);
ensureFloatEqual("(2.5 * 3)", (2.5 * 3), 7.5);
ensureFloatEqual("(2.5 * 3.5)", (2.5 * 3.5), 8.75);
ensureVectorEqual("(<1.1, 2.2, 3.3> * 2)", (<1.1, 2.2, 3.3> * 2), <2.2, 4.4, 6.6>);
ensureVectorEqual("(<2.2, 4.4, 6.6> * 2.0)", (<2.2, 4.4, 6.6> * 2.0), <4.4, 8.8, 13.2>);
ensureFloatEqual("(<1.0, 2.0, 3.0> * <4.0, 5.0, 6.0>)", (<1.0, 2.0, 3.0> * <4.0, 5.0, 6.0>), 32.0);

// division
ensureIntegerEqual("(2 / 2)", (2 / 2), 1);
ensureFloatEqual("(2.2 / 2)", (2.2 / 2), 1.1);
ensureFloatEqual("(3 / 1.5)", (3 / 1.5), 2.0);
ensureFloatEqual("(2.2 / 2.0)", (2.2 / 2.0), 1.1);
ensureVectorEqual("(<1.0, 2.0, 3.0> / 2)", (<1.0, 2.0, 3.0> / 2), <0.5, 1.0, 1.5>);
ensureVectorEqual("(<3.0, 6.0, 9.0> / 1.5)", (<3.0, 6.0, 9.0> / 1.5), <2.0, 4.0, 6.0>);

// modulo
ensureIntegerEqual("(3 % 1)", (3 % 1), 0);
ensureVectorEqual("(<1.0, 2.0, 3.0> % <4.0, 5.0, 6.0>)", (<1.0, 2.0, 3.0> % <4.0, 5.0, 6.0>), <-3.0, 6.0, -3.0>);

// assignment
integer i = 1;
ensureIntegerEqual("i = 1;", i, 1);

// addition assignment
i = 1;
i += 1;
ensureIntegerEqual("i = 1; i += 1;", i, 2);

// subtraction assignment
i = 1;
i -= 1;
ensureIntegerEqual("i = 1; i -= 1;", i, 0);

// multiplication assignment
i = 2;
i *= 2;
ensureIntegerEqual("i = 2; i *= 2;", i, 4);

// division assignment
i = 2;
i /= 2;
ensureIntegerEqual("i = 2; i /= 2;", i, 1);

// modulo assignment
i = 3;
i %= 1;
ensureIntegerEqual("i = 3; i %= 1;", i, 0);

// post increment.
i = 1;
ensureIntegerEqual("i = 1; (i == 2) && (i++ == 1)", (i == 2) && (i++ == 1), TRUE);

// pre increment.
i = 1;
ensureIntegerEqual("i = 1; (i == 2) && (++i == 2)", (i == 2) && (++i == 2), TRUE);

// post decrement.
i = 1;
ensureIntegerEqual("i = 1; (i == 0) && (i-- == 1)", (i == 0) && (i-- == 1), TRUE);

// pre decrement.
i = 1;
ensureIntegerEqual("i = 1; (i == 0) && (--i == 0)", (i == 0) && (--i == 0), TRUE);

// casting
ensureFloatEqual("((float)2)", ((float)2), 2.0);
ensureStringEqual("((string)2)", ((string)2), "2");
ensureIntegerEqual("((integer) 1.5)", ((integer) 1.5), 1);
ensureStringEqual("((string) 1.5)", ((string) 1.5), "1.500000");
ensureIntegerEqual("((integer) \"0xF\")", ((integer) "0xF"), 15);
ensureIntegerEqual("((integer) \"2\")", ((integer) "2"), 2);
ensureFloatEqual("((float) \"1.5\")", ((float) "1.5"), 1.5);
ensureVectorEqual("((vector) \"<1,2,3>\")", ((vector) "<1,2,3>"), <1,2,3>);
ensureRotationEqual("((quaternion) \"<1,2,3,4>\")", ((quaternion) "<1,2,3,4>"), <1,2,3,4>);
ensureStringEqual("((string) <1,2,3>)", ((string) <1,2,3>), "<1.00000, 2.00000, 3.00000>");
ensureStringEqual("((string) <1,2,3,4>)", ((string) <1,2,3,4>), "<1.00000, 2.00000, 3.00000, 4.00000>");
ensureStringEqual("((string) [1,2.5,<1,2,3>])", ((string) [1,2.5,<1,2,3>]), "12.500000<1.000000, 2.000000, 3.000000>");

// while
i = 0;
while(i < 10) ++i;
ensureIntegerEqual("i = 0; while(i < 10) ++i", i, 10);

// do while
i = 0;
do {++i;} while(i < 10);
ensureIntegerEqual("i = 0; do {++i;} while(i < 10);", i, 10);

// for
for(i = 0; i < 10; ++i);
ensureIntegerEqual("for(i = 0; i < 10; ++i);", i, 10);

// jump
i = 1;
jump SkipAssign;
i = 2;
@SkipAssign;
ensureIntegerEqual("i = 1; jump SkipAssign; i = 2; @SkipAssign;", i, 1);

// return
ensureIntegerEqual("testReturn()", testReturn(), 1);

// parameters
ensureIntegerEqual("testParameters(1)", testParameters(1), 2);

// variable parameters
i = 1;
ensureIntegerEqual("i = 1; testParameters(i)", testParameters(i), 2);

// recursion
ensureIntegerEqual("testRecursion(10)", testRecursion(10), 0);

// globals
ensureIntegerEqual("gInteger", gInteger, 5);
ensureFloatEqual("gFloat", gFloat, 1.5);
ensureStringEqual("gString", gString, "foo");
ensureVectorEqual("gVector", gVector, <1, 2, 3>);
ensureRotationEqual("gRot", gRot, <1, 2, 3, 4>);

// global assignment
gInteger = 1;
ensureIntegerEqual("gInteger = 1", gInteger, 1);

gFloat = 0.5;
ensureFloatEqual("gFloat = 0.5", gFloat, 0.5);

gString = "bar";
ensureStringEqual("gString = \"bar\"", gString, "bar");

gVector = <3,3,3>;
ensureVectorEqual("gVector = <3,3,3>", gVector, <3,3,3>);

gRot = <3,3,3,3>;
ensureRotationEqual("gRot = <3,3,3,3>", gRot, <3,3,3,3>);

// vector accessor
vector v;
v.x = 3;
ensureFloatEqual("v.x", v.x, 3);

// rotation accessor
rotation q;
q.s = 5;
ensureFloatEqual("q.s", q.s, 5);

// global vector accessor
gVector.y = 17.5;
ensureFloatEqual("gVector.y = 17.5", gVector.y, 17.5);

// global rotation accessor
gRot.z = 19.5;
ensureFloatEqual("gRot.z = 19.5", gRot.z, 19.5);

// list equality
list l = (list) 5;
list l2 = (list) 5;
ensureListEqual("list l = (list) 5; list l2 = (list) 5", l, l2);
ensureListEqual("list l = (list) 5", l, [5]);
ensureListEqual("[1.5, 6, <1,2,3>, <1,2,3,4>]", [1.5, 6, <1,2,3>, <1,2,3,4>], [1.5, 6, <1,2,3>, <1,2,3,4>]);

if (gTestsFailed > 0) {
llMessageLinked(LINK_SET, passFailChannel, "FAIL", NULL_KEY);
} else {
llMessageLinked(LINK_SET, passFailChannel, "PASS", NULL_KEY);
}

// reset globals
gInteger = 5;
gFloat = 1.5;
gString = "foo";
gVector = <1, 2, 3>;
gRot = <1, 2, 3, 4>;
gTestsPassed = 0;
gTestsFailed = 0;

}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: Report
//////////
////////// Input: broadcastChannel - chat channel to send report
////////// reportType - determines length and content of report type
////////// -> NORMAL - failures and summary information
////////// -> QUITE - summary information only
////////// -> VERBOSE - everything
//////////
////////// Output: llSay on broadcastChannel
//////////
////////// Purpose: This function is where you design the three level of reports
////////// avaliable upon request by the Coordinator
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
Report( integer broadcastChannel, string reportType )
{
string reportString;

//Normal - moderate level of reporting
if( reportType == "NORMAL" )
{
reportString = ""; //add what you would like to report here !!!!!!
}

//QUITE - shortest level of reporting
if( reportType == "QUIET" )
{
reportString = ""; //add what you would like to report here !!!!!!
}

//VERBOSE - highest level of reporting
if( reportType == "VERBOSE" )
{
reportString = ""; //add what you would like to report here !!!!!!
}

//AddUnitReport()
//send to Coordinator on the broadcastChannel the selected report
//format example -> AddUnitReport::unitKey::00000-0000-0000-00000::Report::Successful Completion of Test
llSay( broadcastChannel, "AddUnitReport::unitKey::" + (string)llGetKey() + "::Report::" + reportString);

}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: Initialize
//////////
////////// Input: no input paramaters
//////////
////////// Output: no return value
//////////
////////// Purpose: This function initializes any variables or functions necessary
////////// to get us started
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
Initialize()
{

}

///////////////////////////////////////////////////////////////////////////////////////
//STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE//
///////////////////////////////////////////////////////////////////////////////////////
// //
// //
// DEFAULT STATE //
// //
// //
///////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////
default
{
///////////////////////////////////////////////////////
// State Entry of default state //
///////////////////////////////////////////////////////
state_entry()
{
Initialize();
}
////////////////////////////////////////////////////////
// On Rez of default state //
////////////////////////////////////////////////////////
on_rez(integer start_param)
{
Initialize();
}

///////////////////////////////////////////////////////
// Link Message of default state //
///////////////////////////////////////////////////////
link_message(integer sender_number, integer number, string message, key id)
{
//if link message is on the correct channel
if(number == toAllChannel)
{
//treat as command input
ParseCommand(message);
}

} //end of link message

} // end default
</pre>

TestUnit TestScript Math TRIG.lsl

2008-02-04T22:58:29Z

Phoenix Linden:

[[Category:Conformance Test]]

<pre>
///////////////////////////////////////////////////////////////////////////////////
///////
///////
///////
/////// TestUnit_TestScript
///////
/////// Math_TRIG
///////
/////// This is the test script for the trigonometry math functions.
///////
///////
//////////////////////////////////////////////////////////////////////////////////////

//TestUnit_TestScript .1 -> initial framework 6.23.2007
//TestUnit_TestScript .2 -> tested with minor bug fixes 7.2.2007

//Math_TRIG .1 -> modified from TestUnit_TestScript base to test trig math functions 7.3.2007

//////////////////////////////////////////////////////////////////////////////////////
//
// Command Protocol
//
//////////////////////////////////////////////////////////////////////////////////////
//
//////////////////////////////////////////////
// CHAT commands
//////////////////////////////////////////////
//
// Chat commands will be on the specified broadcastChannel
//
//////// OUTPUT ///////////
//
// AddUnitReport - send Report update to Coordinator on the chat broadcastChannel
// format example -> AddUnitReport::unitKey::00000-0000-0000-00000::Report::Successful Completion of Test
//
//////////////////////////////////////////////
// LINK MESSAGE commands
//////////////////////////////////////////////
//
// link message commands will be sent out on the toAllChannel, and recieved on the passFailChannel
//
//////// INPUT ///////////
//
// RunTest - activation command to start test
// format example -> RunTest
//
// Report - channel and report type
// format example -> Report::controlChannel::0::reportType::NORMAL
//
// Reset - rest the scripts
// format example -> Reset
//
//////// OUTPUT ///////////
//
// passFail - status of test sent on passFailChannel
// format example -> PASS
//
//////////////////////////////////////////////////////////////////////////////////////////

// Global Variables

integer toAllChannel = -255; // general channel - linked message
integer passFailChannel = -355; // test scripts channel for cummunicating pass/fail - linked message

integer debug = 0; // level of debug message
integer debugChannel = DEBUG_CHANNEL; // output channel for debug messages

integer llAcosPASS; // These are global pass/fail
integer llAsinPASS; // indicators for the various
integer llAtan2PASS; // Math trig functions that are
integer llCosPASS; // being tested. These variables
integer llSinPASS; // are used in the Run Test and
integer llTanPASS; // Report Functions of this script.

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: ParseCommand
//////////
////////// Input: string message - command to be parsed
//////////
////////// Output: no return value
//////////
////////// Purpose: This function calls various other functions or sets globals
////////// depending on message string. Allows external command calls.
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
ParseCommand(string message)
{
if(debug > 1)llSay(debugChannel, llGetScriptName()+ "->ParseCommand: " + message);

//reset all scripts
if(message == "Reset")
{
//reset this script
llResetScript();
}

//RunTest()
else if(message == "RunTest")
{
RunTest();
}

//Report()
//Example format -> Report::broadcastChannel::0::reportType::NORMAL
else if( llSubStringIndex(message, "Report") != -1 )
{
//parse the string command into a list
list reportParameters = llParseString2List( message, ["::"], [""] );

//find the broadcastChannel label and increment by one
integer tempIndex = llListFindList( reportParameters, ["controlChannel"] ) + 1;
//pull the broadcastChannel from the list with the index just calculated
integer controlChannel = llList2Integer( reportParameters , tempIndex);

//find the reportType label and increment by one
tempIndex = llListFindList( reportParameters, ["reportType"] ) + 1;
//pull the reportType from the list with the index just calculated
string reportType = llList2String( reportParameters , tempIndex);

//call the Report function with new parameters
Report( controlChannel, reportType );
}

} //end ParseCommand

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: RunTest
//////////
////////// Input: no input paramaters
//////////
////////// Output: link message on passFailChannel test status
//////////
////////// Purpose: This function is where you put the scripts that you want to test
////////// with this unit.
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
RunTest()
{

///////////////////////////////////////////////////////////////////////////////////////////
// Function: float llAcos( float val );
// Returns a float that is the arccosine in radians of val
// • float val – val must fall in the range [-1.0, 1.0]. (-1.0 <= val <= 1.0)
///////////////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llAcosPASS = 0;

//compare known cosine of some angles
if( (string)3.141593 == (string)llAcos( -1.0 ) &
(string)1.570796 == (string)llAcos( 0.0 ) &
(string)0.0 == (string)llAcos( 1.0 ) )
{
llAcosPASS = 1;
}

///////////////////////////////////////////////////////////////////////////////////////
// Function: float llAsin( float val );
// Returns a float that is the arcsine in radians of val
// • float val – must fall in the range [-1.0, 1.0]. (-1.0 <= val <= 1.0)
////////////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llAsinPASS = 0;

//test four sets of vector configurations to hardcoded values
if( (string)-1.570796 == (string)llAsin( -1.0) &
(string)0.0 == (string)llAsin( 0.0 ) &
(string)1.570796 == (string)llAsin( 1.0 ) )
{
llAsinPASS = 1;
}

/////////////////////////////////////////////////////////////////////////
// Function: float llAtan2( float y, float x );
// Returns a float that is the arctangent2 of y, x.
// • float y
// • float x
// Similar to the arctangent(y/x) except it utilizes the signs of x & y to
// determine the quadrant. Returns zero if x and y are zero.
////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llAtan2PASS = 0;

//test four sets of configurations to hardcoded values
if( (string)0.0 == (string)llAtan2( 0.0, 0.0) &
(string)0.0 == (string)llAtan2( 0.0, 1.0 ) &
(string)0.785398 == (string)llAtan2( 1.0, 1.0 ) )
{
llAtan2PASS = 1;
}

//////////////////////////////////////////////////////////////////////////////
// Function: float llCos( float theta );
// Returns a float that is the cosine of theta.
// • float theta – angle expressed in radians.
/////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llCosPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)1.0 == (string)llCos( 0.0 ) &
(string)0.540302 == (string)llCos( 1.0 ) &
(string)0.540302 == (string)llCos( -1.0 ) )
{
llCosPASS = 1;
}

///////////////////////////////////////////////////////////////////////////////////
// Function: float llSin( float theta );
// Returns a float that is the sine of theta.
// • float theta – angle expressed in radians.
//////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llSinPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)0.0 == (string)llSin( 0.0 ) &
(string)0.841471 == (string)llSin( 1.0 ) &
(string)-0.841471 == (string)llSin( -1.0 ) )
{
llSinPASS = 1;
}

/////////////////////////////////////////////////////////////////////////////////
// Function: float llTan( float theta );
// Returns a float that is the tangent of theta.
// • float theta – angle expressed in radians.
/////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llTanPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)0.0 == (string)llTan( 0.0 ) &
(string)1.557408 == (string)llTan( 1.0 ) &
(string)-1.557408 == (string)llTan( -1.0 ) )
{
llTanPASS = 1;
}

//check to see if any failures occured.
integer pass = llAcosPASS &
llAsinPASS &
llAtan2PASS &
llCosPASS &
llSinPASS &
llTanPASS;

// if all of the individual
if( pass )
{
llMessageLinked(LINK_SET, passFailChannel, "PASS", NULL_KEY);
}
else
{
llMessageLinked(LINK_SET, passFailChannel, "FAIL", NULL_KEY);
}
}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: Report
//////////
////////// Input: broadcastChannel - chat channel to send report
////////// reportType - determines length and content of report type
////////// -> NORMAL - failures and summary information
////////// -> QUITE - summary information only
////////// -> VERBOSE - everything
//////////
////////// Output: llSay on broadcastChannel
//////////
////////// Purpose: This function is where you design the three level of reports
////////// avaliable upon request by the Coordinator
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
Report( integer controlChannel, string reportType )
{
//this string will be sent out reguardless of reporting mode
string reportString;

// PASS or FAIL wording for the report
string llAcosPASSstring = "FAIL";
string llAsinPASSstring = "FAIL";
string llAtan2PASSstring = "FAIL";
string llCosPASSstring = "FAIL";
string llSinPASSstring = "FAIL";
string llTanPASSstring = "FAIL";

//translate integer conditional into text string for the report.
if ( llAcosPASS )
{
llAcosPASSstring = "PASS";
}
if ( llAsinPASS )
{
llAsinPASSstring = "PASS";
}
if ( llAtan2PASS )
{
llAtan2PASSstring = "PASS";
}
if ( llCosPASS )
{
llCosPASSstring = "PASS";
}
if ( llSinPASS )
{
llSinPASSstring = "PASS";
}
if ( llTanPASS )
{
llTanPASSstring = "PASS";
}

//Normal - moderate level of reporting
if( reportType == "NORMAL" )
{
reportString = "Function: float llAcos( float val ) -> "
+ llAcosPASSstring + "\n"
+ "Function: float llAsin( float val ) ->"
+ llAsinPASSstring + "\n"
+ "Function: float llAtan2( float y, float x ) -> "
+ llAtan2PASSstring + "\n"
+ "Function: float llCos( float theta ) -> "
+ llCosPASSstring + "\n"
+ "Function: float llSin( float theta ) -> "
+ llSinPASSstring + "\n"
+ "Function: float llTan( float theta ) -> "
+ llTanPASSstring + "\n";

} // end normal

//VERBOSE - highest level of reporting
if( reportType == "VERBOSE" )
{
reportString = "///////////////////////////////////////////////////////////////////////////////////////////" + "\n"+
"// Function: float llAcos( float val );" + "\n" +
"// Returns a float that is the arccosine in radians of val" + "\n" +
"// • float val – val must fall in the range [-1.0, 1.0]. (-1.0 <= val <= 1.0) " + "\n" +
"///////////////////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llAcosPASSstring + "\n\n" +

"///////////////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: float llAsin( float val );" + "\n" +
"// Returns a float that is the arcsine in radians of val" + "\n" +
"// • float val – must fall in the range [-1.0, 1.0]. (-1.0 <= val <= 1.0) " + "\n" +
"////////////////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llAsinPASSstring + "\n\n" +

"/////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: float llAtan2( float y, float x );" + "\n" +
"// Returns a float that is the arctangent2 of y, x." + "\n" +
"// • float y " + "\n" +
"// • float x " + "\n" +
"// Similar to the arctangent(y/x) except it utilizes the signs of x & y to " + "\n" +
"// determine the quadrant. Returns zero if x and y are zero. " + "\n" +
"////////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llAtan2PASSstring + "\n\n" +

"//////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: float llCos( float theta );" + "\n" +
"// Returns a float that is the cosine of theta." + "\n" +
"// • float theta – angle expressed in radians. " + "\n" +
"/////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llCosPASSstring + "\n\n" +

"///////////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: float llSin( float theta );" + "\n" +
"// Returns a float that is the sine of theta." + "\n" +
"// • float theta – angle expressed in radians. " + "\n" +
"//////////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llSinPASSstring + "\n\n" +

"/////////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: float llTan( float theta );" + "\n" +
"// Returns a float that is the tangent of theta." + "\n" +
"// • float theta – angle expressed in radians." + "\n" +
"/////////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llTanPASSstring + "\n\n";

} // end verbose

//AddUnitReport()
//send to Coordinator on the broadcastChannel the selected report
//format example -> AddUnitReport::unitKey::00000-0000-0000-00000::Report::Successful Completion of Test
llSay( controlChannel, "AddUnitReport::unitKey::" + (string)llGetKey() + "::Report::" + reportString);

}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: Initialize
//////////
////////// Input: no input paramaters
//////////
////////// Output: no return value
//////////
////////// Purpose: This function initializes any variables or functions necessary
////////// to get us started
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
Initialize()
{
llSetText( "Math Trig", <255,255,255>, 1);
}

///////////////////////////////////////////////////////////////////////////////////////
//STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE//
///////////////////////////////////////////////////////////////////////////////////////
// //
// //
// DEFAULT STATE //
// //
// //
///////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////
default
{
///////////////////////////////////////////////////////
// State Entry of default state //
///////////////////////////////////////////////////////
state_entry()
{
Initialize();
}
////////////////////////////////////////////////////////
// On Rez of default state //
////////////////////////////////////////////////////////
on_rez(integer start_param)
{
Initialize();
}

///////////////////////////////////////////////////////
// Link Message of default state //
///////////////////////////////////////////////////////
link_message(integer sender_number, integer number, string message, key id)
{
//if link message is on the correct channel
if(number == toAllChannel)
{
//treat as command input
ParseCommand(message);
}

} //end of link message

} // end default
</pre>

TestUnit TestScript Math 3D.lsl

2008-02-04T22:58:20Z

Phoenix Linden:

[[Category:Conformance Test]]

<pre>
///////////////////////////////////////////////////////////////////////////////////
///////
///////
///////
/////// TestUnit_TestScript
///////
/////// Math_3D
///////
/////// This is the test script for the 3D math functions.
///////
///////
//////////////////////////////////////////////////////////////////////////////////////

//TestUnit_TestScript .1 -> initial framework 6.23.2007
//TestUnit_TestScript .2 -> tested with minor bug fixes 7.2.2007

//Math_3D .1 -> modified from TestUnit_TestScript base to test 3D math functions 7.3.2007

//////////////////////////////////////////////////////////////////////////////////////
//
// Command Protocol
//
//////////////////////////////////////////////////////////////////////////////////////
//
//////////////////////////////////////////////
// CHAT commands
//////////////////////////////////////////////
//
// Chat commands will be on the specified broadcastChannel
//
//////// OUTPUT ///////////
//
// AddUnitReport - send Report update to Coordinator on the chat broadcastChannel
// format example -> AddUnitReport::unitKey::00000-0000-0000-00000::Report::Successful Completion of Test
//
//////////////////////////////////////////////
// LINK MESSAGE commands
//////////////////////////////////////////////
//
// link message commands will be sent out on the toAllChannel, and recieved on the passFailChannel
//
//////// INPUT ///////////
//
// RunTest - activation command to start test
// format example -> RunTest
//
// Report - channel and report type
// format example -> Report::controlChannel::0::reportType::NORMAL
//
// Reset - rest the scripts
// format example -> Reset
//
//////// OUTPUT ///////////
//
// passFail - status of test sent on passFailChannel
// format example -> PASS
//
//////////////////////////////////////////////////////////////////////////////////////////

// Global Variables

integer toAllChannel = -255; // general channel - linked message
integer passFailChannel = -355; // test scripts channel for cummunicating pass/fail - linked message

integer debug = 0; // level of debug message
integer debugChannel = DEBUG_CHANNEL; // output channel for debug messages

integer llAngleBetweenPASS; //
integer llAxes2RotPASS; //
integer llAxisAngle2RotPASS; // These are global pass/fail
integer llEuler2RotPASS; // indicators for the various
integer llRot2EulerPASS; // Math 3D functions that are
integer llRotBetweenPASS; // being tested. These variables
integer llVecDistPASS; // are used in the Run Test
integer llVecMagPASS; // and Report Functions of this
integer llVecNormPASS; // script.

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: ParseCommand
//////////
////////// Input: string message - command to be parsed
//////////
////////// Output: no return value
//////////
////////// Purpose: This function calls various other functions or sets globals
////////// depending on message string. Allows external command calls.
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
ParseCommand(string message)
{
if(debug > 1)llSay(debugChannel, llGetScriptName()+ "->ParseCommand: " + message);

//reset all scripts
if(message == "Reset")
{
//reset this script
llResetScript();
}

//RunTest()
else if(message == "RunTest")
{
RunTest();
}

//Report()
//Example format -> Report::broadcastChannel::0::reportType::NORMAL
else if( llSubStringIndex(message, "Report") != -1 )
{
//parse the string command into a list
list reportParameters = llParseString2List( message, ["::"], [""] );

//find the broadcastChannel label and increment by one
integer tempIndex = llListFindList( reportParameters, ["controlChannel"] ) + 1;
//pull the broadcastChannel from the list with the index just calculated
integer controlChannel = llList2Integer( reportParameters , tempIndex);

//find the reportType label and increment by one
tempIndex = llListFindList( reportParameters, ["reportType"] ) + 1;
//pull the reportType from the list with the index just calculated
string reportType = llList2String( reportParameters , tempIndex);

//call the Report function with new parameters
Report( controlChannel, reportType );
}

} //end ParseCommand

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: RunTest
//////////
////////// Input: no input paramaters
//////////
////////// Output: link message on passFailChannel test status
//////////
////////// Purpose: This function is where you put the scripts that you want to test
////////// with this unit.
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
RunTest()
{

/////////////////////////////////////////////////////////////////
// Function: float llAngleBetween( rotation a, rotation b );
// Returns a float that is the angle between rotation a and b.
// • rotation a – start rotation
// • rotation b – end rotation
/////////////////////////////////////////////////////////////////
//initialize a pass variable to TRUE
llAngleBetweenPASS = 0;

//compare two rotations with no angle in between
if( (string)0.0 == (string)llAngleBetween( <0.0, 0.0, 0.0, 1.0>, <0.0, 0.0, 0.0, 1.0> ) &
(string)2.094395 == (string)llAngleBetween( <1.0, 1.0, 1.0, 1.0>, <0.0, 0.0, 0.0, 1.0> ) &
(string)2.094395 == (string)llAngleBetween( <0.0, 0.0, 0.0, 1.0>, <1.0, 1.0, 1.0, 1.0> ) )
{
llAngleBetweenPASS = 1;
}

/////////////////////////////////////////////////////////////////////////
// Function: rotation llAxes2Rot( vector fwd, vector left, vector up );
// Returns a rotation that is defined by the 3 coordinate axes
// • vector fwd
// • vector left
// • vector up
/////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llAxes2RotPASS = 0;

//test four sets of vector configurations to hardcoded values
if( (string)<1.00000, 0.00000, 0.00000, 0.00000> == (string)llAxes2Rot( <0.0, 0.0, 0.0>, <0.0, 0.0, 0.0>, <0.0, 0.0, 0.0>) &
(string)<0.00000, -0.35355, 0.35355, 0.70711> == (string)llAxes2Rot( <1.0, 1.0, 1.0>, <0.0, 0.0, 0.0>, <0.0, 0.0, 0.0>) &
(string)<0.35355, 0.00000, -0.35355, 0.70711> == (string)llAxes2Rot( <0.0, 0.0, 0.0>, <1.0, 1.0, 1.0>, <0.0, 0.0, 0.0>) &
(string)<-0.35355, 0.35355, 0.00000, 0.70711> == (string)llAxes2Rot( <0.0, 0.0, 0.0>, <0.0, 0.0, 0.0>, <1.0, 1.0, 1.0>) )
{
llAxes2RotPASS = 1;
}

/////////////////////////////////////////////////////////////////////////
// Function: rotation llAxisAngle2Rot( vector axis, float angle );
// Returns a rotation that is a generated angle about axis
// • vector axis
// • float angle – expressed in radians.
/////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llAxisAngle2RotPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)<0.00000, 0.00000, 0.00000, 1.00000> == (string)llAxisAngle2Rot( < 0.0, 0.0, 0.0>, 0.0 ) &
(string)<0.84147, 0.00000, 0.00000, 0.54030> == (string)llAxisAngle2Rot( < 1.0, 0.0, 0.0>, 2.0 ) &
(string)<0.27680, 0.27680, 0.27680, 0.87758> == (string)llAxisAngle2Rot( < 1.0, 1.0, 1.0>, 1.0 ) &
(string)<0.00000, 0.00000, 0.47943, 0.87758> == (string)llAxisAngle2Rot( < 0.0, 0.0, 1.0>, 1.0 ) )
{
llAxisAngle2RotPASS = 1;
}

////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

//////////////////////////////////////////////////////////////////////////////
// Function: rotation llEuler2Rot( vector v );
// Returns a rotation representation of Euler Angles v.
// • vector v
//////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llEuler2RotPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)<0.00000, 0.00000, 0.00000, 1.00000> == (string)llEuler2Rot( < 0.0, 0.0, 0.0> ) &
(string)<0.47943, 0.00000, 0.00000, 0.87758> == (string)llEuler2Rot( < 1.0, 0.0, 0.0> ) &
(string)<0.57094, 0.16752, 0.57094, 0.56568> == (string)llEuler2Rot( < 1.0, 1.0, 1.0> ) &
(string)<0.00000, 0.00000, 0.47943, 0.87758> == (string)llEuler2Rot( < 0.0, 0.0, 1.0> ) )
{
llEuler2RotPASS = 1;
}

///////////////////////////////////////////////////////////////////////////////////
// Function: vector llRot2Euler( rotation quat );
// Returns a vector that is the Euler representation (roll, pitch, yaw) of quat.
// • rotation quat – Any valid rotation
///////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llRot2EulerPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)<-0.00000, 0.00000, -0.00000> == (string)llRot2Euler( <0.00000, 0.00000, 0.00000, 1.00000> ) &
(string)<1.57574, 0.11067, -0.08922> == (string)llRot2Euler( <1.00000, 0.10000, 0.01100, 1.00000> ) &
(string)<-1.10715, 0.72973, 2.03444> == (string)llRot2Euler( <0.00000, 1.00000, 1.00000, 1.00000> ) &
(string)<0.00000, 1.57080, 1.57080> == (string)llRot2Euler( <1.00000, 1.00000, 1.00000, 1.00000> ) )
{
llRot2EulerPASS = 1;
}

/////////////////////////////////////////////////////////////////////////////////
// Function: rotation llRotBetween( vector start, vector end );
// Returns a rotation that is the rotation between start to end
// • vector start
// • vector end
/////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llRotBetweenPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)<0.00000, 0.00000, 0.00000, 1.00000> == (string)llRotBetween( < 0.0, 0.0, 0.0>, < 0.0, 0.0, 0.0> ) &
(string)<0.00000, 0.03531, -0.70622, 0.70711> == (string)llRotBetween( < -10.0, 0.0, 0.0>, < 0.0, 10.0, 0.5> ) &
(string)<0.62796, 0.62796, 0.00000, 0.45970> == (string)llRotBetween( < 10.0, -10.0, 10.0>, < 0.0, 0.0, -1.0> ) &
(string)<0.00000, -0.99969, 0.00000, 0.02498> == (string)llRotBetween( < 0.0, 0.0, -10.0>, < 0.5, 0.0, 10.0> ) )
{
llRotBetweenPASS = 1;
}

/////////////////////////////////////////////////////////////////////////////////////////////////////
// Function: float llVecDist( vector vec_a, vector vec_b );
// Returns a float that is the distance between vec_a and vec_b (llVecMag(vec_a - vec_b)).
// • vector vec_a – Any valid vector
// • vector vec_b – Any valid vector
//////////////////////////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llVecDistPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)0.0 == (string)llVecDist( < 0.0, 0.0, 0.0>, < 0.0, 0.0, 0.0> ) &
(string)1.0 == (string)llVecDist( < 1.0, 0.0, 0.0>, < 0.0, 0.0, 0.0> ) &
(string)1.732051 == (string)llVecDist( < 1.0, 1.0, 1.0>, < 0.0, 0.0, 0.0> ) &
(string)1.0 == (string)llVecDist( < 0.0, 0.0, -1.0>, < 0.0, 0.0, 0.0> ) )
{
llVecDistPASS = 1;
}

//////////////////////////////////////////////////////////////////////////////////////////////////////
// Function: float llVecMag( vector vec );
// Returns a float that is the magnitude of the vector (the distance from vec to <0.0, 0.0, 0.0>).
// • vector vec
//////////////////////////////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llVecMagPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)0.0 == (string)llVecMag( < 0.0, 0.0, 0.0>) &
(string)1.0 == (string)llVecMag( < 1.0, 0.0, 0.0>) &
(string)1.732051 == (string)llVecMag( < 1.0, 1.0, 1.0> ) &
(string)1.414214 == (string)llVecMag( < 1.0, 0.0, -1.0> ) )
{
llVecMagPASS = 1;
}

///////////////////////////////////////////////////////////////////////////////
// Function: vector llVecNorm( vector vec );
// Returns a vector that is the normal of the vector (vec / llVecMag(vec)).
// • vector vec – Any valid vector
///////////////////////////////////////////////////////////////////////////////

//initialize a pass variable to TRUE
llVecNormPASS = 0;

//test four sets of configurations to hardcoded values
if( (string)< 0.0, 0.0, 0.0> == (string)llVecNorm( < 0.0, 0.0, 0.0>) &
(string)< 1.0, 0.0, 0.0> == (string)llVecNorm( < 1.0, 0.0, 0.0>) &
(string)<0.57735, 0.57735, 0.57735> == (string)llVecNorm( < 1.0, 1.0, 1.0> ) &
(string)<0.70711, 0.00000, -0.70711> == (string)llVecNorm( < 1.0, 0.0, -1.0> ) )
{
llVecNormPASS = 1;
}

//multiple all of the individual pass variables together to check for any failures.
integer pass = llAngleBetweenPASS *
llAxes2RotPASS *
llAxisAngle2RotPASS *
llEuler2RotPASS *
llRot2EulerPASS *
llRotBetweenPASS *
llVecDistPASS *
llVecMagPASS *
llVecNormPASS;

// if all of the individual
if( pass == 1)
{
llMessageLinked(LINK_SET, passFailChannel, "PASS", NULL_KEY);
}
else
{
llMessageLinked(LINK_SET, passFailChannel, "FAIL", NULL_KEY);
}
}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: Report
//////////
////////// Input: broadcastChannel - chat channel to send report
////////// reportType - determines length and content of report type
////////// -> NORMAL - failures and summary information
////////// -> QUITE - summary information only
////////// -> VERBOSE - everything
//////////
////////// Output: llSay on broadcastChannel
//////////
////////// Purpose: This function is where you design the three level of reports
////////// avaliable upon request by the Coordinator
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
Report( integer controlChannel, string reportType )
{
//this string will be sent out reguardless of reporting mode
string reportString;

// Initialize with FAIL
string llAngleBetweenPASSstring = "FAIL";
string llAxes2RotPASSstring = "FAIL";
string llAxisAngle2RotPASSstring = "FAIL";
string llEuler2RotPASSstring = "FAIL";
string llRot2EulerPASSstring = "FAIL";
string llRotBetweenPASSstring = "FAIL";
string llVecDistPASSstring = "FAIL";
string llVecMagPASSstring = "FAIL";
string llVecNormPASSstring = "FAIL";

//translate integer conditional into text string for the report.
if ( llAngleBetweenPASS )
{
llAngleBetweenPASSstring = "PASS";
}
if ( llAxes2RotPASS )
{
llAxes2RotPASSstring = "PASS";
}
if ( llAxisAngle2RotPASS )
{
llAxisAngle2RotPASSstring = "PASS";
}
if ( llEuler2RotPASS)
{
llEuler2RotPASSstring = "PASS";
}
if ( llRot2EulerPASS )
{
llRot2EulerPASSstring = "PASS";
}
if ( llRotBetweenPASS )
{
llRotBetweenPASSstring = "PASS";
}
if ( llVecDistPASS )
{
llVecDistPASSstring = "PASS";
}
if ( llVecMagPASS )
{
llVecMagPASSstring = "PASS";
}
if ( llVecNormPASS )
{
llVecNormPASSstring = "PASS";
}

//Normal - moderate level of reporting
if( reportType == "NORMAL" )
{
reportString = "Function: float llAngleBetween( rotation a, rotation b ) -> "
+ llAngleBetweenPASSstring + "\n"
+ "Function: rotation llAxes2Rot( vector fwd, vector left, vector up) ->"
+ llAxes2RotPASSstring + "\n"
+ "Function: rotation llAxisAngle2Rot( vector axis, float angle ) -> "
+ llAxisAngle2RotPASSstring + "\n"
+ "Function: rotation llEuler2Rot( vector v ) -> "
+ llEuler2RotPASSstring + "\n"
+ "Function: vector llRot2Euler( rotation quat ) -> "
+ llRot2EulerPASSstring + "\n"
+ "Function: rotation llRotBetween( vector start, vector end ) -> "
+ llRotBetweenPASSstring + "\n"
+ "Function: float llVecDist( vector vec_a, vector vec_b ) -> "
+ llVecDistPASSstring + "\n"
+ "Function: float llVecMag( vector vec ) -> "
+ llVecMagPASSstring + "\n"
+ "Function: vector llVecNorm( vector vec ) -> "
+ llVecNormPASSstring + "\n";

} // end normal

//VERBOSE - highest level of reporting
if( reportType == "VERBOSE" )
{
reportString = "/////////////////////////////////////////////////////////////////" + "\n" +
"// Function: float llAngleBetween( rotation a, rotation b ) + " + "\n" +
"// Returns a float that is the angle between rotation a and b." + "\n" +
"// • rotation a – start rotation " + "\n" +
"// • rotation b – end rotation " + "\n" +
"/////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llAngleBetweenPASSstring + "\n\n" +

"/////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: rotation llAxes2Rot( vector fwd, vector left, vector up ) +" + "\n" +
"// Returns a rotation that is defined by the 3 coordinate axes" + "\n" +
"// • vector fwd " + "\n" +
"// • vector left " + "\n" +
"// • vector up" + "\n" +
"/////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llAxes2RotPASSstring + "\n\n" +

"/////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: rotation llAxisAngle2Rot( vector axis, float angle );" + "\n" +
"// Returns a rotation that is a generated angle about axis" + "\n" +
"// • vector axis " + "\n" +
"// • float angle – expressed in radians. " + "\n" +
"/////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llAxisAngle2RotPASSstring + "\n\n" +

"//////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: rotation llEuler2Rot( vector v );" + "\n" +
"// Returns a rotation representation of Euler Angles v." + "\n" +
"// • vector v " + "\n" +
"//////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llEuler2RotPASSstring + "\n\n" +

"/////////////////////////////////////////////////////////////////////////////////// " + "\n" +
"// Function: vector llRot2Euler( rotation quat );" + "\n" +
"// Returns a vector that is the Euler representation (roll, pitch, yaw) of quat." + "\n" +
"// • rotation quat – Any valid rotation " + "\n" +
"/////////////////////////////////////////////////////////////////////////////////// " + "\n" +
"PASS/FAIL -> " + llRot2EulerPASSstring + "\n\n" +

"/////////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: rotation llRotBetween( vector start, vector end );" + "\n" +
"// Returns a rotation that is the rotation between start to end" + "\n" +
"// • vector start " + "\n" +
"// • vector end" + "\n" +
"/////////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llRotBetweenPASSstring + "\n\n" +

"/////////////////////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: float llVecDist( vector vec_a, vector vec_b );" + "\n" +
"// Returns a float that is the distance between vec_a and vec_b (llVecMag(vec_a - vec_b))." + "\n" +
"// • vector vec_a – Any valid vector " + "\n" +
"// • vector vec_b – Any valid vector" + "\n" +
"//////////////////////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llVecDistPASSstring + "\n\n" +

"///////////////////////////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: float llVecMag( vector vec );" + "\n" +
"// Returns a float that is the magnitude of the vector (the distance from vec to <0.0, 0.0, 0.0>)." + "\n" +
"// • vector vec " + "\n" +
"///////////////////////////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llVecMagPASSstring + "\n\n" +

"///////////////////////////////////////////////////////////////////////////////" + "\n" +
"// Function: vector llVecNorm( vector vec );" + "\n" +
"// Returns a vector that is the normal of the vector (vec / llVecMag(vec))." + "\n" +
"// • vector vec – Any valid vector " + "\n" +
"///////////////////////////////////////////////////////////////////////////////" + "\n" +
"PASS/FAIL -> " + llVecNormPASSstring + "\n\n";

}// end verbose

//AddUnitReport()
//send to Coordinator on the broadcastChannel the selected report
//format example -> AddUnitReport::unitKey::00000-0000-0000-00000::Report::Successful Completion of Test
llSay( controlChannel, "AddUnitReport::unitKey::" + (string)llGetKey() + "::Report::" + reportString);

}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: Initialize
//////////
////////// Input: no input paramaters
//////////
////////// Output: no return value
//////////
////////// Purpose: This function initializes any variables or functions necessary
////////// to get us started
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
Initialize()
{
//why
llSetText( "Math 3D", <255,255,255>, 1);

}

///////////////////////////////////////////////////////////////////////////////////////
//STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE//
///////////////////////////////////////////////////////////////////////////////////////
// //
// //
// DEFAULT STATE //
// //
// //
///////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////
default
{
///////////////////////////////////////////////////////
// State Entry of default state //
///////////////////////////////////////////////////////
state_entry()
{
Initialize();
}
////////////////////////////////////////////////////////
// On Rez of default state //
////////////////////////////////////////////////////////
on_rez(integer start_param)
{
Initialize();
}

///////////////////////////////////////////////////////
// Link Message of default state //
///////////////////////////////////////////////////////
link_message(integer sender_number, integer number, string message, key id)
{
//if link message is on the correct channel
if(number == toAllChannel)
{
//treat as command input
ParseCommand(message);
}

} //end of link message

} // end default

</pre>

TestUnit TestScript DataServer Notecard.lsl

2008-02-04T22:57:51Z

Phoenix Linden:

TestUnit TestScript Communication Rpc.lsl

2008-02-04T22:57:37Z

Phoenix Linden:

Category:Conformance Test

2008-02-04T22:56:24Z

Phoenix Linden:

These are the unit tests we run for LSL using the [[LSL Test Harness]]. Some of the tests are based on the [[Template:LSL_conformance_test]] while others are free-form. If you want to add new unit tests, prefer using the [[Template:LSL_conformance_test|template]] since it will allow the engineering staff the opportunity to more quickly approve and adopt the test.

Category:Conformance Test

2008-02-04T22:54:03Z

Phoenix Linden:

These are the unit tests we run for LSL using the [[LSL Test Harness]].

TestUnit TestScript Communication Http.lsl

2008-02-04T22:49:58Z

Phoenix Linden:

[[Category:Conformance_Test]]

<pre>
///////////////////////////////////////////////////////////////////////////////////
///////
///////
///////
/////// TestUnit_TestScript
///////
///////
///////
/////// This is the test script for the HTTP communication function
///////
///////
//////////////////////////////////////////////////////////////////////////////////////

//TestUnit_TestScript .1 -> initial framework 6.23.2007
//TestUnit_TestScript .2 -> tested with minor bug fixes 7.2.2007

//Communication_Http .1 -> modified from TestUnit_TestScript base to test http functions 7.6.2007

//////////////////////////////////////////////////////////////////////////////////////
//
// Command Protocol
//
//////////////////////////////////////////////////////////////////////////////////////
//
//////////////////////////////////////////////
// CHAT commands
//////////////////////////////////////////////
//
// Chat commands will be on the specified broadcastChannel
//
//////// OUTPUT ///////////
//
// AddUnitReport - send Report update to Coordinator on the chat broadcastChannel
// format example -> AddUnitReport::unitKey::00000-0000-0000-00000::Report::Successful Completion of Test
//
//////////////////////////////////////////////
// LINK MESSAGE commands
//////////////////////////////////////////////
//
// link message commands will be sent out on the toAllChannel, and recieved on the passFailChannel
//
//////// INPUT ///////////
//
// RunTest - activation command to start test
// format example -> RunTest
//
// Report - channel and report type
// format example -> Report::controlChannel::0::reportType::NORMAL
//
// Reset - rest the scripts
// format example -> Reset
//
//////// OUTPUT ///////////
//
// passFail - status of test sent on passFailChannel
// format example -> PASS
//
//////////////////////////////////////////////////////////////////////////////////////////

// Global Variables

integer toAllChannel = -255; // general channel - linked message
integer passFailChannel = -355; // test scripts channel for cummunicating pass/fail - linked message

integer debug = 0; // level of debug message
integer debugChannel = DEBUG_CHANNEL; // output channel for debug messages

key HTTP_CONTROL; // HTTP Handler
string HTTP_URL = "TODO: add your server url here"; // url for the HTTP test

string http_body; // temp storage for the http response

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: ParseCommand
//////////
////////// Input: string message - command to be parsed
//////////
////////// Output: no return value
//////////
////////// Purpose: This function calls various other functions or sets globals
////////// depending on message string. Allows external command calls.
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
ParseCommand(string message)
{
if(debug > 1)llSay(debugChannel, llGetScriptName()+ "->ParseCommand: " + message);

//reset all scripts
if(message == "reset")
{
//reset this script
llResetScript();
}

//RunTest()
else if(message == "RunTest")
{
RunTest();
}

//Report()
//Example format -> Report::broadcastChannel::0::reportType::NORMAL
else if( llSubStringIndex(message, "Report") != -1 )
{
//parse the string command into a list
list reportParameters = llParseString2List( message, ["::"], [""] );

//find the broadcastChannel label and increment by one
integer tempIndex = llListFindList( reportParameters, ["controlChannel"] ) + 1;
//pull the broadcastChannel from the list with the index just calculated
integer controlChannel = llList2Integer( reportParameters , tempIndex);

//find the reportType label and increment by one
tempIndex = llListFindList( reportParameters, ["reportType"] ) + 1;
//pull the reportType from the list with the index just calculated
string reportType = llList2String( reportParameters , tempIndex);

//call the Report function with new parameters
Report( controlChannel, reportType );
}

} //end ParseCommand

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: RunTest
//////////
////////// Input: no input paramaters
//////////
////////// Output: link message on passFailChannel test status
//////////
////////// Purpose: This function is where you put the scripts that you want to test
////////// with this unit.
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
RunTest()
{
//initiate a http request
HTTP_CONTROL = llHTTPRequest( HTTP_URL, [HTTP_METHOD,"PUT"],"");

}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: Report
//////////
////////// Input: broadcastChannel - chat channel to send report
////////// reportType - determines length and content of report type
////////// -> NORMAL - failures and summary information
////////// -> QUITE - summary information only
////////// -> VERBOSE - everything
//////////
////////// Output: llSay on broadcastChannel
//////////
////////// Purpose: This function is where you design the three level of reports
////////// avaliable upon request by the Coordinator
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
Report( integer broadcastChannel, string reportType )
{
string reportString;

if(debug > 1)llSay(debugChannel, llGetScriptName()+ "->Report() type=" + reportType);

//Normal - moderate level of reporting
if( reportType == "NORMAL" )
{
//parse http response to useful list
//format example -> ownername::objectname::objectkey::ownerkey::region::location
list unitParameters = llParseString2List( http_body , ["::"], [""]);

reportString += "http_ownername: " + llList2String( unitParameters, 0) + "\n";
reportString += "http_objectname: " + llList2String( unitParameters, 1)+ "\n";
reportString += "http_objectkey: " + llList2String( unitParameters, 2)+ "\n";
reportString += "http_ownerkey: " + llList2String( unitParameters, 3)+ "\n";
reportString += "http_region: " + llList2String( unitParameters, 4)+ "\n";
reportString += "http_location: " + llList2String( unitParameters, 5)+ "\n";

}

//QUITE - shortest level of reporting
if( reportType == "QUIET" )
{
reportString = http_body;
}

//VERBOSE - highest level of reporting
if( reportType == "VERBOSE" )
{

//parse http response to useful list
//format example -> ownername::objectname::objectkey::ownerkey::region::location
list unitParameters= llParseString2List( http_body, ["::"], [""]);

reportString += "http_body: " + llDumpList2String( unitParameters , ",") + "\n";
reportString += "http_ownername: " + llList2String( unitParameters, 0) + " --- ownername: " + llKey2Name( llGetOwner() ) + "\n";
reportString += "http_objectname: " + llList2String( unitParameters, 1)+ " --- objectname: " + llGetObjectName() + "\n";
reportString += "http_objectkey: " + llList2String( unitParameters, 2)+ " --- objectkey: " + (string)llGetKey() + "\n";
reportString += "http_ownerkey: " + llList2String( unitParameters, 3)+ " --- ownerkey: " + (string)llGetOwner() + "\n";
reportString += "http_region: " + llList2String( unitParameters, 4)+ " --- region: " + llGetRegionName() + "\n";
reportString += "http_location: " + llList2String( unitParameters, 5)+ " --- location: " + (string)llGetLocalPos() + "\n";
}

//AddUnitReport()
//send to Coordinator on the broadcastChannel the selected report
//format example -> AddUnitReport::unitKey::00000-0000-0000-00000::Report::Successful Completion of Test
llSay( broadcastChannel, "AddUnitReport::unitKey::" + (string)llGetKey() + "::Report::" + reportString);

}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: errorcheck
//////////
////////// Input: the body of a http response
//////////
////////// Output: 0 -> error detected
////////// 1 -> no error in message
//////////
////////// Purpose: This function is used to test the body of a http response for a
////////// error message
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
integer errorcheck(string message)
{
if(debug > 1){llSay(debugChannel, llGetScriptName()+ ":errorcheck ");}

//if the word "error" is found in the body
if( llSubStringIndex( llToLower(message), "error" ) != -1)
{
llSay(0, message);
//return an error detected reponse
return 0;
}
//if the "404 not found" is present in the body
if( llSubStringIndex( llToLower(message), "404 not found" ) != -1)
{
llSay(0, message);
//return an error detected reponse
return 0;
}

//if it made it past the error detection test, return a passed response
return 1;
}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: HttpVerification
//////////
////////// Input: the body of a http response
//////////
////////// Output: sends pass/fail message out via linked message
//////////
//////////
////////// Purpose: This function is used to verify the body of a http response
//////////
//////////
////////// Issues: format and float precision issue with the location compare
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
HttpVerification(string message)
{

//expect a :: seperated list of the information transmitted in the http headers
//format example -> ownername::objectname::objectkey::ownerkey::region::location

// dump string parameters into usable list
list unitParameters= llParseString2List( message, ["::"], [""]);

//initialize a status variable
string passIndication = "PASS";

//ownername
if( llList2String( unitParameters, 0) != llKey2Name( llGetOwner() ) )
{
passIndication = "FAIL";
if(debug > 1){llSay(debugChannel, llGetScriptName()+ ":GetOwnerFAIL ");}
}

//objectname
if( llList2String( unitParameters, 1) != llGetObjectName() )
{
passIndication = "FAIL";
if(debug > 1){llSay(debugChannel, llGetScriptName()+ ":GetObjectNameFAIL ");}
}

//objectkey
if( llList2String( unitParameters, 2) != (string)llGetKey() )
{
passIndication = "FAIL";
if(debug > 1){llSay(debugChannel, llGetScriptName()+ ":GetKeyFAIL ");}
}

//ownerkey
if( llList2String( unitParameters, 3) != (string)llGetOwner() )
{
passIndication = "FAIL";
if(debug > 1){llSay(debugChannel, llGetScriptName()+ ":GetOwnerFAIL ");}
}

//region
//because the response contains the region grid numbers,
//you can not do a direct compare
if( llSubStringIndex( llList2String( unitParameters, 4), llGetRegionName() ) == -1)
{
passIndication = "FAIL";
}

//location
// if( llList2String( unitParameters, 5) != (string)llGetLocalPos() )
// {
// passIndication = "FAIL";
// }

//One of the following messages needs to be sent at the end of this function
//each time that it is run
//
// llMessageLinked(LINK_SET, passFailChannel, "PASS", NULL_KEY);
// llMessageLinked(LINK_SET, passFailChannel, "FAIL", NULL_KEY);
llMessageLinked(LINK_SET, passFailChannel, passIndication, NULL_KEY);

}

//////////////////////////////////////////////////////////////////////////////////////////////////
//////////
////////// Function: Initialize
//////////
////////// Input: no input paramaters
//////////
////////// Output: no return value
//////////
////////// Purpose: This function initializes any variables or functions necessary
////////// to get us started
//////////
////////// Issues: no known issues
//////////
//////////
/////////////////////////////////////////////////////////////////////////////////////////////////
Initialize()
{

llSetText( "Communication_Http", <255,255,255>, 1);
}

///////////////////////////////////////////////////////////////////////////////////////
//STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE STATE//
///////////////////////////////////////////////////////////////////////////////////////
// //
// //
// DEFAULT STATE //
// //
// //
///////////////////////////////////////////////////////////////////////////////////////
///////////////////////////////////////////////////////////////////////////////////////
default
{
///////////////////////////////////////////////////////
// State Entry of default state //
///////////////////////////////////////////////////////
state_entry()
{
Initialize();
}
////////////////////////////////////////////////////////
// On Rez of default state //
////////////////////////////////////////////////////////
on_rez(integer start_param)
{
Initialize();
}

///////////////////////////////////////////////////////
// Link Message of default state //
///////////////////////////////////////////////////////
link_message(integer sender_number, integer number, string message, key id)
{
if(debug > 1)llSay(debugChannel, llGetScriptName()+ "->link_message: " + message);

//if link message is on the correct channel
if(number == toAllChannel)
{
//treat as command input
ParseCommand(message);
}

} //end of link message

///////////////////////////////////////////////////////
// Http Response of default state //
///////////////////////////////////////////////////////
http_response(key id, integer status, list metadata, string body)
{
// if(debug > 10){llSay(debugChannel, llGetScriptName()+ ":FUNCTION: DEFAULT HTTP");}
// if(debug > 10){llSay(debugChannel, body);}

//if it was a call to setup
if(id == HTTP_CONTROL)
{ //if we can pass the error check
if( errorcheck(body) )
{
//expect a :: seperated list of the information transmitted in the http headers
//format example -> ownername::objectname::objectkey::ownerkey::region::location
HttpVerification( body );

http_body = body;
}
}

} // end http_reponse

} // end default
</pre>

LlUnescapeURL

2008-02-02T00:29:54Z

Phoenix Linden:

{{LSL_Function
|func_id=308|func_sleep=0.0|func_energy=10.0
|func=llUnescapeURL|return_type=string|p1_type=string|p1_name=url
|func_footnote
|func_desc
|return_text=that is an unescaped/unencoded version of url, replacing %20 with spaces etc.
|spec
|caveats=
|constants
|examples
|helpers
|also_functions={{LSL DefineRow||[[llEscapeURL]]| Opposite of llUnescapeURL}}
|also_events
|also_tests
|also_articles=
{{LSL DefineRow||[[UTF-8]]|}}
{{LSL DefineRow||{{LSLGC|Base64}}|}}
|notes
|permission
|negative_index
|sort=UnescapeURL
|cat1=Encoding
|cat2=String
|cat3
|cat4
}}

LlEscapeURL

2008-02-01T21:33:11Z

Phoenix Linden:

{{LSL_Function
|func_id=307|func_sleep=0.0|func_energy=10.0
|func=llEscapeURL|return_type=string|p1_type=string|p1_name=url
|func_footnote
|func_desc
|return_text=that is the escaped/encoded version of '''url''', replacing spaces with %20 etc. The function will escape any character not in [a-zA-Z0-9] to %xx where xx is the hexadecimal value of the byte.
|spec
|caveats=* The function is not appropriate for escaping an URL all at once since the ': ' after the protocol and all of the '/' delimiting the various parts.
*See: {{LSLG|string#Caveats|String:Caveats}}
|constants
|examples
|helpers
|also_functions={{LSL DefineRow|[[llUnescapeURL]]}}
|also_events
|also_tests
|also_articles={{LSL DefineRow|[[UTF-8]]}}
{{LSL DefineRow|[[Base64]]}}
|notes
|permission
|negative_index
|cat1=Encoding
|cat2=String
|cat3
|cat4
}}

LlSetObjectDesc

2008-02-01T19:41:07Z

Phoenix Linden:

{{LSL_Function
|func=llSetObjectDesc
|func_id=271|func_sleep=0.0|func_energy=10.0
|p1_type=string|p1_name=desc
|func_footnote
|func_desc=Sets the prims description
|return_text
|spec
|caveats=*The object description is limited to 127 bytes, any string longer then that will be truncated.
*According to [http://jira.secondlife.com/browse/VWR-437 VWR-437] if you set the description to longer then 256 bytes the object may no longer be rezzable. Use caution if using this field to store data.
|constants
|examples=<pre>
//store the owner's name in the prim description
touch_start(integer total_number)
{
string temp;

temp = llKey2Name(llGetOwner());

llSetObjectDesc(temp);
}

</pre>
|helpers
|also_functions=
{{LSL DefineRow||{{LSLG|llGetObjectDesc}}|Returns the object description.}}
{{LSL DefineRow||{{LSLG|llGetObjectName}}|Gets the object name.}}
{{LSL DefineRow||{{LSLG|llSetObjectName}}|Sets the object name.}}
|also_tests
|also_events
|also_articles=
{{LSL DefineRow||[[Prim Attribute Overloading]]}}
|notes
|cat1=Prim
|cat2=Object
|cat3
|cat4
}}

LlSetObjectName

2008-02-01T19:37:46Z

Phoenix Linden:

{{LSL Function
|func_id=203
|func_sleep=0.0
|func_energy=10.0
|func=llSetObjectName|sort=SetObjectName
|p1_type=string
|p1_name=name
|func_desc=Sets the prim's name according to the '''name''' parameter.
|func_footnote=If this function is called from a child prim in a linked set, it will change the name of the child prim and not the root prim.
|return_text
|spec
|caveats=
#The name is limited to 63 characgters. Longer prim names appeared cut short.
#The LL client did not reliably show the current name. Misleadingly old names sometimes appeared at Edit > General > Name until you closed and reopened the Edit dialog of the prim.
|constants
|examples=<pre>
default
{
state_entry()
{
string yyyy1mm1dd = llGetDate();
string name = yyyy1mm1dd + " " + llGetObjectName();
llOwnerSay("llSetObjectName(\"" + name + "\")");
llSetObjectName(name);
}
}
</pre>
|helpers
|also_functions=
{{LSL DefineRow||[[llGetObjectName]]|Get the prims name}}
{{LSL DefineRow||[[llGetLinkName]]|Get a linked prims name}}
{{LSL DefineRow||[[llGetObjectDesc]]|Get the prims description}}
{{LSL DefineRow||[[llSetObjectDesc]]|Set the prims description}}
|also_tests
|also_events
|also_articles
|notes
|cat1=Prim
|cat2
|cat3
|cat4
|}}

LLSD

2007-12-29T00:49:14Z

Phoenix Linden: /* Binary Serialization */

= The LLSD flexible data system =

The following text is from the comments in the source of the file:
linden\indra\common\llsd.cpp

LLSD stands [http://blog.secondlife.com/2006/07/19/web-services-serialization-format/#comment-101218][according to Andrew Linden] for '''Linden Lab Structured Data'''.

== Summary ==

LLSD provides a flexible data system similar to the data facilities of dynamic languages like Perl and Python. It is created to support exchange of structured data between loosly coupled systems. (Here, "loosly coupled" means not compiled together into the same module.)

Data in such exchanges must be highly tolerant of changes on either side such as:
- recompilation
- implementation in a different langauge
- addition of extra parameters
- execution of older versions (with fewer parameters)

To this aim, the C++ API of LLSD strives to be very easy to use, and to default to "the right thing" whereever possible. It is extremely tolerant of errors and unexpected situations.

The fundamental class is LLSD. LLSD is a value holding object. It holds one value that is either undefined, one of the scalar types, or a map or an array. LLSD objects have value semantics (copying them copies the value, though it can be considered efficient, due to sharing.), and mutable.

Undefined is the singular value given to LLSD objects that are not initialized with any data. It is also used as the return value for operations that return an LLSD,

The scalar data types are:
* Boolean - true or false
* Integer - a 32 bit signed integer
* Real - a 64 IEEE 754 floating point value
* UUID - a 128 unique value
* String - a sequence of zero or more Unicode chracters
* Date - an absolute point in time, UTC, with resolution to the second
* URI - a String that is a URI
* Binary - a sequence of zero or more octets (unsigned bytes)

A map is a dictionary mapping String keys to LLSD values. The keys are unique within a map, and have only one value (though that value could be an LLSD array).

An array is a sequence of zero or more LLSD values.

== Scalar Accessors ==

Function: Fetch a scalar value, converting if needed and possible.

Conversion among the basic types, Boolean, Integer, Real and String, is fully defined. Each type can be converted to another with a reasonable interpretation. These conversions can be used as a convenience even when you know the data is in one format, but you want it in another. Of course, many of these conversions lose information.

Note: These conversions are not the same as Perl's. In particular, when converting a String to a Boolean, only the empty string converts to false. Converting the String "0" to Boolean results in true.

Conversion to and from UUID, Date, and URI is only defined to and from String. Conversion is defined to be information preserving for valid values of those types. These conversions can be used when one needs to convert data to or from another system that cannot handle these types natively, but can handle strings.

Conversion to and from Binary isn't defined.

Conversion of the Undefined value to any scalar type results in a reasonable null or zero value for the type.

== Automatic Cast Protection ==

These are not implemented on purpose. Without them, C++ can perform some conversions that are clearly not what the programmer intended.

If you get a linker error about these being missing, you have made mistake in your code. DO NOT IMPLEMENT THESE FUNCTIONS as a fix.

All of thse problems stem from trying to support char* in LLSD or in std::string. There are too many automatic casts that will lead to using an arbitrary pointer or scalar type to std::string.

== Attributes and Data ==
Attributes are only used for encoding parser and formatting instructions. The data in the elements is always data.

== Root Element ==
The root element is llsd. The root must have only one child element which can be any container or atomic type.

== Atomic Types ==
Each atomic type represents one value with type information. An atomic does not have a name, but may have attributes to specify format or processing considerations for the parser.
Consumers of atomics are encouraged to massage the data into the preferred native representation, but further serialization should honor the original type information if possible.

=== undefined ===
The undefined type is a placeholder to indicate something is there, but it has no value, and cannot be converted to any other atomic type. Though limited in this way, an undefined is still considered a first-class atomic, and is expected to behave like any other atomic structured data type at runtime.
==== Serialization example ====
<code>
<undef />
</code>

=== boolean ===
A true or false value.
==== Conversion ====
{|
|'''type'''||'''rules'''||
|-
|boolean||unity||
|-
|integer||true => 1, false => 0||
|-
|real||true => 1.0, false => 0.0||
|-
|uuid||n/a||
|-
|string||'true', 'false'||
|-
|binary||one byte us-ascii where true => 1, false => 0||
|-
|date||n/a||
|-
|uri||n/a||
|}

==== Serialization examples ====
<pre>

<boolean>1</boolean>
<boolean>true</boolean>


<boolean>0</boolean>
<boolean>false</boolean>
<boolean />
</pre>

=== integer ===
A signed integer value with a representation of 32 bits.
==== Conversion ====
{|
|'''type'''||'''rules'''||
|-
|boolean||0 => false, all other values => true||
|-
|integer||unity||
|-
|real||closest representable number||
|-
|uuid||n/a||
|-
|string||human readable string||
|-
|binary||8 byte network byte order representation||
|-
|date||seconds since epoch||
|-
|uri||n/a||
|}

==== Serialization examples ====
<pre>
<integer>289343</integer>
<integer>-3</integer>
<integer /> 
</pre>

=== real ===
A 64 bit double as defined by IEEE.
==== Conversion ====
{|
|'''type'''||'''rules'''||
|-
|boolean||exactly 0 => false, all other values => true||
|-
|integer||rounded to closest representable number||
|-
|real||unity||
|-
|uuid||n/a||
|-
|string||human readable string||
|-
|binary||8 byte network byte order representation||
|-
|date||seconds since epoch||
|-
|uri||n/a||
|}

==== Serialization examples ====
<pre>
<real>-0.28334</real>
<real>2983287453.3848387</real>
<real /> 
</pre>

=== uuid ===
A 128 byte unsigned integer.
==== Conversion ====
{|
|'''type'''||'''rules'''||
|-
|boolean||null uuid => false, all other values => true||
|-
|integer||n/a||
|-
|real||n/a||
|-
|uuid||unity||
|-
|string||standard 8-4-4-4-12 serialization format||
|-
|binary||16 byte raw representation||
|-
|date||n/a||
|-
|uri||n/a||
|}

==== Serialization examples ====
<pre>
<uuid>d7f4aeca-88f1-42a1-b385-b9db18abb255</uuid>
<uuid /> 
</pre>

=== string ===
A simple string of any character data which is intended to be human comprehensible.

Strings in the system that hold text a user might see or enter (chat, IM, notecards, AV names, region names,... basically almost everything!) should move to using a consistent set of acceptable characters. This set is:

* Unicode code points U+20 through U+10FFFD
** except U+D800 through U+DFFF
** except U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFE, U+2FFF ... U+10FFFE, U+10FFFF
** except U+FDDD through U+FDEF
* U+9 (tab, '\t')
* U+A (newline or line feed, '\n')
* U+D (carriage return, '\r')

Strings may be sequences of zero or more of these characters. Strings *may* be normalized by mapping line ending sequences to U+A. Do not rely on differences in strings that normalize to the same string.

These choices of valid strings are chosen from Unicode 4.0 which defines the following valid code points:
* Unicode code points U+0 through U+10FFFD
** except U+D800 through U+DFFF (the UTF-16 surrogate pair range)
** except U+FFFE, U+FFFF, U+1FFFE, U+1FFFF, U+2FFE, U+2FFF ... U+10FFFE, U+10FFFF
** except U+FDDD through U+FDEF (some historical screw up with Arabic)

The choice for special characters < U+20 is because XML defines acceptable text as all valid Unicode code points >= U+20, and U+9, U+A and U+D. The normalization is because XML defines that all line ending sequences are normalized to U+A.

==== Conversion ====
{|
|'''type'''||'''rules'''||
|-
|boolean||empty => false, all other values => true||
|-
|integer||A simple conversion of the initial characters to an integer||
|-
|real||A simple conversion of the initial characters to a real number||
|-
|uuid||A valid 8-4-4-4-12 is converted to a uuid, all other values => null uuid||
|-
|string||unity||
|-
|binary||raw representation of the characters||
|-
|date||An interpretation of the string as a date||
|-
|uri||An interpretation of the string as a link||
|}

==== Serialization examples ====
<pre>
<string>The quick brown fox jumped over the lazy dog.</string>
<string>540943c1-7142-4fdd-996f-fc90ed5dd3fa</string>
<string /> 
</pre>

=== binary data ===
A chunk of binary data.
The serialization format is allowed to specify an encoding. Parsers must support base64 encoding. Parsers may support base16 and base85.
==== Conversion ====
{|
||'''type'''||'''rules'''||
|-
||boolean||empty => false, all other values => true||
|-
||integer||len < 4 => 0, otherwise first four bytes are interpreted as a network byte order integer||
|-
||real||len < 8 => 0, otherwise first eight bytes are interpreted as a network byte order double||
|-
||uuid||len < 16 => null uuid, otherwise first sixteen bytes are interpreted as the raw binary uuid||
|-
||string||the raw binary data interpreted as utf-8 character data||
|-
||binary||unity||
|-
||date||n/a||
|-
||uri||the raw binary data interpreted as a utf-8 serialized link||
|}

==== Serialization examples ====
<pre>
<binary encoding="base64">cmFuZG9t</binary> 
<binary>dGhlIHF1aWNrIGJyb3duIGZveA==</binary> 
<binary /> 
</pre>

=== date ===
A specific point in time. Intervals or relative dates are not supported. The serialization and parser only understand ISO-8601 numeric encoding in UTC. The time may be omitted which will be interpreted as midnight at the start of the day.
==== Conversion ====
{|
|'''type'''||'''rules'''||
|-
|boolean||n/a||
|-
|integer||seconds since epoch||
|-
|real||seconds since epoch||
|-
|uuid||n/a||
|-
|string||standard serialization format||
|-
|binary||n/a||
|-
|date||unity||
|-
|uri||n/a||
|}

==== Serialization examples ====
<pre>
<date>2006-02-01T14:29:53Z</date>
<date /> 
</pre>

=== uri ===
A link to an external resource. The data is expected to conform to [http://www.ietf.org/rfc/rfc2396.txt rfc 2396] for interpretation, meaning, serialization, and deserialization.
==== Conversion ====
{|
||'''type'''||'''rules'''||
|-
||boolean||n/a||
|-
||integer||n/a||
|-
||real||n/a||
|-
||uuid||n/a||
|-
||string||standard serialization format||
|-
||binary||n/a||
|-
||date||n/a||
|-
||uri||unity||
|}

==== Serialization examples ====
<pre>
<uri>http://sim956.agni.lindenlab.com:12035/runtime/agents</uri>
<uri /> 
</pre>

== Containers ==
Containers is a special data type which can contain any other data type including other containers.

=== map ===
A map of key and value pairs where key ordering is unspecified and keys are unique. The key is always interpreted as a character string and any character string is acceptable. If there are any elements in the map, it is serialized as a key followed by an atomic or container value. For every key, there must be one value.
Well formed and valid serialized maps may contain more non-unique keys. When a deserialized, the implementation should choose one of the the value objects, but that choice is not specified.
==== Serialization example ====
<pre>
<map>
<key>foo</key>
<string>bar</string>
<key>agent info</key>
<map>
<key>agent_id</key>
<uuid>93c73b16-cd86-434d-8b4a-76e12eee950a</uuid>
<key>name</key>
<string>testtest tester</string>
</map>
</map>
</pre>

=== array ===
An ordered collection of data members. Any member can be any atomic or container type.
==== Serialization example ====
<pre>
<array>
<real>7343.0194</real>
<array>
<map>
<key>offset</key>
<integer>9847</integer>
</map>
<string>da boom</string>
</array>
</array>
</pre>

= xml-llsd DTD =
<pre>
<!DOCTYPE llsd [
<!ELEMENT llsd (DATA)>
<!ELEMENT DATA (ATOMIC|map|array)>
<!ELEMENT ATOMIC (undef|boolean|integer|real|uuid|string|date|uri|binary)>
<!ELEMENT KEYDATA (key,DATA)>
<!ELEMENT key (#PCDATA)>
<!ELEMENT map (KEYDATA*)>
<!ELEMENT array (DATA*)>
<!ELEMENT undef (EMPTY)>
<!ELEMENT boolean (#PCDATA)>
<!ELEMENT integer (#PCDATA)>
<!ELEMENT real (#PCDATA)>
<!ELEMENT uuid (#PCDATA)>
<!ELEMENT string (#PCDATA)>
<!ELEMENT date (#PCDATA)>
<!ELEMENT uri (#PCDATA)>
<!ELEMENT binary (#PCDATA)>

<!ATTLIST string xml:space (default|preserve) 'preserve'>
<!ATTLIST binary encoding CDATA "base64">
]>
</pre>

= Example XML Output =
This is a sample from a recently running sim (indention for readability):

<pre>
$ curl http://localhost:12035/runtime/statistics
<?xml version="1.0" encoding="UTF-8"?>
<llsd>
<map>
<key>region_id</key>
<uuid>67153d5b-3659-afb4-8510-adda2c034649</uuid>
<key>scale</key>
<string>one minute</string>
<key>simulator statistics</key>
<map>
<key>time dilation</key><real>0.9878624</real>
<key>sim fps</key><real>44.38898</real>
<key>pysics fps</key><real>44.38906</real>
<key>agent updates per second</key><real>nan</real>
<key>lsl instructions per second</key><real>0</real>
<key>total task count</key><real>4</real>
<key>active task count</key><real>0</real>
<key>active script count</key><real>4</real>
<key>main agent count</key><real>0</real>
<key>child agent count</key><real>0</real>
<key>inbound packets per second</key><real>1.228283</real>
<key>outbound packets per second</key><real>1.277508</real>
<key>pending downloads</key><real>0</real>
<key>pending uploads</key><real>0.0001096525</real>
<key>frame ms</key><real>0.7757886</real>
<key>net ms</key><real>0.3152919</real>
<key>sim other ms</key><real>0.1826937</real>
<key>sim physics ms</key><real>0.04323055</real>
<key>agent ms</key><real>0.01599029</real>
<key>image ms</key><real>0.01865955</real>
<key>script ms</key><real>0.1338836</real>
</map>
</map>
</llsd>
</pre>

= Binary Serialization =
We also have support for binary serialization and deserialization in c++ and python. The binary format is useful when dealing where optimal parse time is necessary. Binary LLSD is the binary llsd prefix followed by a single LLSD element of any type.

<pre>
<?llsd/binary?>\n
</pre>

{| border="1"
|+ Binary element serialization
! type !! serialization !! notes
|-
| undef || '!'
|-
| true || '1'
|-
| false || '0'
|-
| integer || 'i' + htonl(value)
|-
| real || 'r' + htond(value)
|-
| uuid || 'u' + uuid || uuid is 16 bytes
|-
| binary || 'b' + htonl(binary.size()) + binary
|-
| string || 's' + htonl(string.size()) + string || notation serialization is considered valid
|-
| uri || 'l' + htonl(uri.size()) + uri
|-
| date || 'd' + htond(seconds_since_epoch)
|-
| array || '[' + htonl(array.length()) + (child0, child1, ...) + ']' || order is always preserved
|-
| map || '{' + htonl(map.length()) + ((key0,value0), (key1, value1), ...)+ '}' || order is not always preserved.
|}

<b>size()</b> is a byte count.

<b>length()</b> is a child count.

<b>htonl()</b> is a function to generate a 4 byte network byte order integer.

<b>htond()</b> is a function to generate an 8 byte network byte order double. htond is not a standard system call, but you can find a c implementation in <code>indra/llcommon/llsdserialize.cpp</code>.

= Notation Serialization =
We also have support for a serialization format meant for human readability. Parsing and formatting are currently only available in c++. Notation LLSD is the notation llsd prefix followed by a single LLSD element of any type.

<pre>
<?llsd/notation?>\n
</pre>

{| border="1"
|+ Binary element serialization
! type !! serialization !! notes
|-
| undef || '!'
|-
| true || <nowiki>'1' | 't' | 'T' | 'true' | 'TRUE'</nowiki>
|-
| false || <nowiki>'0' | 'f' | 'F' | 'false' | 'FALSE'</nowiki>
|-
| integer || 'i' str(value)
|-
| real || 'r' str(value)
|-
| uuid || 'u' str(uuid)
|-
| binary || <nowiki>'b(' str(size) ')"' raw_data '"' | 'b' base '"' encoded_data '"'</nowiki> || Base 16 and 64 encodings are supported.
|-
| string || <nowiki>" escaped_string " | ' escaped_string ' | 's(' str(size) ')"' raw_string '"'</nowiki> || When using single quotes, double quotes do not need escaping and vice versa.
|-
| uri || 'l"' escaped_uri '"' || See [http://www.faqs.org/rfcs/rfc1738.html rfc 1738] for encoding rules.
|-
| date || 'd"' YYYY-MM-DD 'T' HH:MM:SS [.FF] 'Z"' || Fractional seconds are optional
|-
| array || '[' object0 ',' object1 ',' ... ']' || order is always preserved
|-
| map || '{' string0:object0 ',' string1:object1 ',' ... '}' || order is not always preserved. The string is any supported string serialization format
|}

== String Escaping ==
Strings which contain non-printable characters delimited with quotes or double quotes require escaping. If a single quote delimited string contains single quotes, those must be escaped. If a double quote delimited string contains double quotes, the double quotes must be escaped.

To escape the delimiter character, prefix a backslash. Backslashes must always be escaped with another backslash.

"And then he said, \"I have nothing more to say on the subject.\""

'Look in "C:\\linden\\"'

The most generic escaping is to specify a hex value of the byte after a literal backslash and character 'x'. This can be used for any character and is required for all non-printable characters which do not have an abbreviation. For example:

\x0C

Serialized strings should only contain UTF-8 characters, so non-printable characters other than tab, newline, and carriage return should be avoided. However, common non-printable characters have short-hand abbreviations.

{| border="1"
|+ Notation abbreviations
! character !! value !! serialization
|-
| alert/bell || 0x7 || \a
|-
| backspace || 0x8 || \b
|-
| form feed || 0xc || \f
|-
| newline || 0xa || \n
|-
| carriage return || 0xd || \r
|-
| horizontal tab || 0x9 || \t
|-
| vertical tab || 0xb || \v
|}

== Example Notation Output ==
This is an excerpt from an agent request to enter a region serialized as notation:
<pre>
[
{'destination':'http://secondlife.com'},
{'version':i1},
{
'agent_id':u3c115e51-04f4-523c-9fa6-98aff1034730,
'session_id':u2c585cec-038c-40b0-b42e-a25ebab4d132,
'circuit_code':i1075,
'first_name':'Phoenix',
'last_name':'Linden',
'position':[r70.9247,r254.378,r38.7304],
'look_at':[r-0.043753,r-0.999042,r0],
'granters':[ua2e76fcd-9360-4f6d-a924-000000000003],
'attachment_data':
[
{
'attachment_point':i2,
'item_id':ud6852c11-a74e-309a-0462-50533f1ef9b3,
'asset_id':uc69b29b1-8944-58ae-a7c5-2ca7b23e22fb
},
{
'attachment_point':i10,
'item_id':uff852c22-a74e-309a-0462-50533f1ef900,
'asset_id':u5868dd20-c25a-47bd-8b4c-dedc99ef9479
}
]
}
]
</pre>

<pre>
[
{
'creation-date':d"2007-03-15T18:30:18Z",
'creator-id':u3c115e51-04f4-523c-9fa6-98aff1034730
},
s(10)"0123456789",
"Where's the beef?",
'Over here.',
b(160)"default
{
state_entry()
{
llSay(0, "Hello, Avatar!");
}

touch_start(integer total_number)
{
llSay(0, "Touched.");
}
}",
b64"AABAAAAAAAAAAAIAAAA//wAAP/8AAADgAAAA5wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AABkAAAAZAAAAAAAAAAAAAAAZAAAAAAAAAABAAAAAAAAAAAAAAAAAAAABQAAAAEAAAAQAAAAAAAA
AAUAAAAFAAAAABAAAAAAAAAAPgAAAAQAAAAFAGNbXgAAAABgSGVsbG8sIEF2YXRhciEAZgAAAABc
XgAAAAhwEQjRABeVAAAABQBjW14AAAAAYFRvdWNoZWQuAGYAAAAAXF4AAAAIcBEI0QAXAZUAAEAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
]
</pre>

= Guidelines =
== XML Encoding ==
When possible, prefer using us-ascii or or UTF-8 xml encoding.

=== Questions & Things To Do ===

Would Binary be more convenient as usigned char* buffer semantics?

Should Binary be convertable to/from String, and if so how?
* as UTF8 encoded strings (making not like UUID<->String)
* as Base64 or Base96 encoded (making like UUID<->String)

Conversions to std::string and LLUUID do not result in easy assignment to std::string, LLString or LLUUID due to non-unique conversion paths.

Certified HTTP

2007-12-02T18:19:02Z

Phoenix Linden: /* X-Message-URL */

= Goals =
The basic goal of Certified HTTP (colloquially known as chttp) is to perform exactly-once messaging between two hosts.

From a standard http client perspective, if the client reads a whole response, then it knows for certain the server handled the request. However, for all other failure modes, the client can't be sure if the server did, or did-not perform the request function. On the server side, the server can never know if the client ever got the answer or not. For some operations, we need the ability for the client to perform a data-altering operation and be insistent that it occur. In particular, if it isn't certain that it happened, then it must be able to try again safely.

The bigger picture goal is to make a simple way to conduct reliable delivery and receipt such that general adoption by the wider community is possible. This means that we have to respect HTTP where we can to take advantage of existing tools and methodology and to never contradict common conventions in a REST world.

'''Join the [https://lists.secondlife.com/cgi-bin/mailman/listinfo/chttpdev mailing list].'''

= Workflow =

The workflow is a specification/pseudocode for what actions both ends of chttp communication need to take to fulfill the requirements.

== Interaction Sequence ==

Here's a diagram that describes an everything-works certified http communication.

[[Image:Interaction_sequence.png]]

Of note are the failure points. These are the effective crash locations of the participants (the failure points on the arrows represent communication failures). Actions that intervene between two failure points should be deterministic and/or atomic enough that a crash occurring midway through them is functionally identical to a crash occurring at the immediately prior failure point.

The [[Certified HTTP Failure Diagrams]] page (warning: '''very''' image-heavy) has a relatively-exhaustive exploration of the way a Certified HTTP implementation should behave in the face of failures.

== Sending a Message ==

The sending-side API looks very much like a normal HTTP method call:
response = certified_http.put(url, body)

What happens under the covers is:
# Generate a globally unique message ID for the message
# Store the outgoing request (headers and all), including the message id, in a durable store "outbox", and waits for a response.
# A potentially asynchronous process performs the following steps:
## Retrieves the request from the outbox.
## Performs the HTTP request specified by the outbox request and waits for a response.
## If a response is not forthcoming, for whatever reason, the process retries after a certain period.
## If the server sends an error code that indicates that the reliable message will never complete (e.g. 501), or a long timeout expires indicating that an absurd amount of time has elapsed, the method throws an exception.
# Opens a transaction on the durable store
# Stores the incoming response in a durable inbox.
# 'Tombstones' the message in the outbox, which essentially marks the message as having been received, so that if the application resumes again, it doesn't resend.
# Closes the transaction on the durable store
# If the response contains a header indicating a confirmation url on the recipient, performs an HTTP DELETE on the resource to ack the incoming message.

There are no explicit semantics for the response body, like HTTP itself. The content will vary depending on the application.

== Receiving a Message ==

The receiver sets up a node in the url hierarchy, just like a regular http node. When an incoming request comes in, the receiver:

# Stores the incoming request in a durable store "inbox", if it doesn't already contain a message with the same ID.
# A potentially asynchronous process performs the following steps:
## Looks for responses in the outbox matching the incoming message id, and if it finds one, sends it as the response without invoking anything else.
## Opens a transaction on the database, locking the inbox request
## Calls the handler method on the receiving node:
### <code>def handle_put(body, txn):<br/>return "My Response"</code>
### The handler method can use the open transaction to perform actions in the database that are atomic with the receipt of the message. Any non-idempotent operation must be done atomically in this way.
## Stores the return value of the handle method as an outgoing response in the outbox, without closing the transaction.
## Removes the incoming request from the inbox
## Closes the transaction
# Discovers a new item in the outbox, responds to the incoming http request with the response from the outbox, including a url that, if DELETEd, will remove the item from the outbox.

= Requirements =

We have the concept of a "long" time (LT). The purpose of this time is to ensure that any clients will stop trying a particular request long before the server discards state associated with the request. This is not a very theoretically "pure" concept, since it relies on all parties conforming to certain (reasonable) assumptions, but we believe that we get significant benefits (lack of explicit negotiation), at little risk of actually entering an incorrect state. chttp is expected to generate a small amount of bookkeeping data for each message, and there needs to be a way to expire this data in a way that doesn't involve additional negotiation between servers and clients. The server should keep data for LT, and clients should not retry messages that are older than LT/2 or similar, so that there is at least LT/2 for a Reliable Host to recover from errors, and LT/2 for clock skew. LT therefore should be orders of magnitude longer than the longest downtime we expect to see in the system and the largest clock skew we expect to see. Off the cuff, 30 days seems like a reasonable value for LT.

* chttp is based on http, and can use any facility provided by http 1.1 where not otherwise contradicted.
** this includes the use of https, pipelining, chunked encoding, proxies, redirects, caches, and headers such as Accept, Accept-Encoding, Expect, and Content-Type.
** any normal http verb appropriate to context should be accepted, eg POST, PUT, GET, DELETE
** unless otherwise specified, the http feature set in use is orthogonal and effectively transparent to chttp
* in any complete chttp exchange the client and server can eventually agree on success or failure of delivery, though it is more important that no ill effects arise when they disagree
* any message will be effectively received once and only once or not at all
* the content of the http body must be opaque to chttp
* the URI of the original request must be opaque to chttp
* chttp enabled clients and servers can integrate with unreliable tools
** the chttp server can differentiate reliable requests and respond without reliability guarantees (i.e. act as a normal http server)
** chttp clients can differentiate reliable responses and handle unreliable servers (i.e. act as a normal http client)
* the client will persist the local time of sending
* if there is one the client must either have the persisted outgoing body or the exact same body can be regenerated on the fly
* the server will persist the local time of message receipt
* the server must persist the response body or have a mechanism to idempotently generate the same response to the same request
* all urls with a chttp server behind them are effectively idempotent for all uniquely identified messages
** the client can retry steadily over a period of LT/2 days
** the client and server are assumed to almost always be running
** over that window of opportunity, the same message will always get the same response
* all persisted data on a single host is ACID

== requirements on top of http ==
* if the body of the request is non-zero length, the client MUST include a Content-Length header, unless prohibited by section 4.4 of [http://www.w3.org/Protocols/rfc2616/rfc2616.html RFC 2616]
** the server will look for \r\n\r\n and content length body to consider the request complete
** an incomplete request will result in 4XX status code
* if the body of the response is non-zero length, the server must include a Content-Length header
** the client will look for \r\n\r\n and content length body to consider the response complete
** the client will retry on an incomplete response
* Messages can not be terminated by closing the connection -- only positive expressions of message termination (such as Content-Length) can guarantee that a full message is received.

== assumptions ==

* The client and server will not have any significant time discontinuity, i.e., the clock difference between them should be less than LT/100.
* The client and server will not have clock drift more than LT/100 per day.
* Both parties exchanging messages are Reliable Hosts (defined below).
* Generating a globally unique message ID is inexpensive.
* It is possible to store a large amount of 'small' data (such as [[UUID]]s, urls, and date/timestamps) for LT. "Large" in this case means "as many items as the throughput of a host implies that you could create during LT". In other words, storing this small data will never be a resource problem.
* Any transaction or data handled by this system will become useless well before LT has elapsed.

; Reliable Host : A reliable host has the following properties:
* The host has a durable data store of finite size, which can store data in such a way that it is guaranteed to be recoverable even in the face of a certain number of hardware failures.
* The host will not be down forever. Either a clone will be brought up on different hardware, or the machine itself will reappear within a day or so.
* The host can perform {{Wikipedia|ACID|w=n}} operations on the data it contains.

= Implementation =
Requiring an opaque body and URI pretty much requires either negotiating an URL beforehand or adding new headers. Since the former was discarded earlier (reliable delivery after setup), we will focus on adding request and response headers.

This is a suggested implementation:
# chttp enabled servers will behave idempotently with a unique message id on the request
# the server can request acknowledgment from the client if the request consumes server resources

== Request ==
A client will start a reliable message by making an HTTP request to a url on a reliable http server. The url may be known in advance or returned as part of an earlier application protocol exchange. The request must contain two headers on top of the headers required by HTTP/1.1: X-Message-Id and Date.

=== X-Message-ID ===
A globally unique id. It must match the regular expression <code>^[A-Za-z0-9-_:]{30,100}$</code>. This header is required for all Certified HTTP interactions.

The best practice for generating this id is to combine a client host identifier with a cryptographically secure uuid and a sequence number.

Sending a message with the same message id but a a different body has an undefined result.

Sending a message with the same message id but with a different header which implies a different response body, eg, the first request specifies "Accept: text/plain" and the second request specifies "Accept: text/html", the response can be one of:

* The original response.
* A 4xx indicating that the server has detected the incompatability

It is preferable to return the original response rather than the 4xx, but some implementations may not be able to achieve that.

=== Date ===

The Date header, as specified in RFC2616. Certified HTTP requires a date header on all requests, which differs somewhat from RFC2616.

== Response ==
Generally, when the client gets the 2XX back from the server, the message has been delivered. If the server has a response body, then the client will need to acknowledge receipt of the entire body. If the entire body is not read, the client can safely resubmit the exact same request. The server will include a message url in the headers if the client specified a message id on request and the body requires persistence by the server.

=== X-Message-URL ===
This will be a unique url on the server for the client message id which the client will DELETE upon receipt of the entire response to the request. This will only exist if there is a non-null response body or the server is consuming significant resources to maintain that url. When the client performs the delete, the server can flush all persisted resources other than the fact that the message was sent at some point.

== Status Codes ==

The semantics of Certified HTTP are to retry until the message goes through. HTTP status codes provide one way of determining whether the message made it or not; we've grouped these status codes into 'success' or 'retry'. In many cases they can signify that the client is attempting to send an invalid message, an error in the application logic; these are labeled as 'fail'. There is a third class, where the status code may be ambiguous; e.g. 404, which is often emitted by temporarily-misconfigured webservers, but may also indicate that an incorrect url was chosen.

=== Success ===

These status codes, when received, give the client permission to do whatever cleanup it needs to do, and to return to caller, safe in the assumption that the message was delivered.

* 200 OK
* 201 Created
* 203 Non-Authoritative Information
* 204 No Content
* 205 Reset Content
* 206 Partial Content
* 304 Not Modified

=== Retry ===

These status codes indicate a temporary failure or misconfiguration on the server side, and therefore the client should retry until it gets something different. All the redirected/proxied messages carry the same message-id.

* 202 Accepted (potentially delaying longer than normal)
* 300 Multiple Choices (follow redirect)
* 302 Found (follow redirect)
* 305 Use Proxy (use proxy)
* 307 Temporary Redirect (follow redirect only if GET)
* 408 Request Timeout (retry with a new message-id and date)
* 413 Request Entity Too Large (if Retry-After header present)
* 502 Bad Gateway
* 503 Service Unavailable
* 504 Gateway Timeout

=== Fail ===

If your application logic screws up and picks an improper content-type or messes up the url, then the Certified HTTP subsystem shouldn't be burdened with retrying forever for a message that will never be delivered. If it receives these status codes, it will raise an exception to the caller and nuke the outgoing request.

* 400 Bad Request
* 401 Unauthorized
* 402 Payment Required
* 403 Forbidden
* 410 Gone
* 411 Length Required
* 413 Request Entity Too Large (if no Retry-After header present)
* 414 Request-URI Too Long
* 415 Unsupported Media Type
* 416 Requested Range Not Satisfiable
* 417 Expectation Failed
* 501 Not Implemented
* 505 HTTP Version Not Supported

=== Ambiguous ===

It's a little ambiguous what to do when the client gets one of these status codes, so we think that the application should decide. There are a few ways to do that:
# The client raises an exception with a retry() method that can be caught by the application, and retried if the application determines that the exception represented a temporary failure.
# The application passes a list to the Certified HTTP subsystem that sorts these status codes into 'retry' or 'fail'.
# The subsystem uses a heuristic such as retrying for a short period of time then converting to a Fail if still not successful.
Here's the list of status codes:

* 303 See Other (retry will use GET even if original used POST)
* 307 Temporary Redirect (only if POST)
* 404 Not Found
* 406 Not Acceptable
* 407 Proxy Authentication Required
* 409 Conflict
* 412 Precondition Failed
* 500 Internal Server Error

= Related Technologies =
I believe that all competitors to this fall into one of three categories, specialized message queues, reliable logic tunneled through HTTP, and delivery over HTTP with setup charges.

== traditional message queue technology ==
This includes products like [http://www-306.ibm.com/software/integration/wmq/ MQ], [http://www.microsoft.com/windowsserver2003/technologies/msmq/default.mspx MSMQ], and [http://activemq.apache.org/ ActiveMQ].

These technologies are useful, but provide a number of hurdles:
* No common standards.
* Integrates a new technology with unknown performance characteristics.
* Requires significant operational overhead.

Because of this, we have opted to use HTTP as a foundation of the technology.

== reliable application logic in body ==
This includes technologies like [http://www.ibm.com/developerworks/library/ws-httprspec/ httpr] and [http://www.ibm.com/developerworks/library/specification/ws-rm/ ws-reliable].

These tend to be thoroughly engineered protocol specifications which regrettably repeat the mistakes of the nearly defunct XMLRPC and the soon to join it SOAP -- namely, treating services as a function call. This is a reasonable approach, and is probably the most obvious to the engineers working on the problem. The most obvious path, which is followed in both of the examples, is to package a traditional message queue body into an HTTP body sent via POST. Treating web services as function calls severely limits the expressive nature of HTTP and should be avoided.

Consumers of web services prefer REST APIs rather than function calls over HTTP. I believe this is because REST is inherently more comprehensible to consumers since all of the data is data the consumer requested. In one telling data point, Amazon has both SOAP and REST interfaces to their web services, and 85% of their usage is of the REST interface[http://www.oreillynet.com/pub/wlg/3005]. I believe ceding power to the consumer is the only path to make wide adoption possible. In doing so, we must drop the entire concept of burying data the consumer wants inside application data.

== reliable delivery after setup ==
There appear to be a few proposals of this nature around the web and a shining example can be found in [http://www.dehora.net/doc/httplr/draft-httplr-01.html httplr].

These are http reliability mechanisms which require a round trip to begin the reliable transfer and then follow through with some permutation of acknowledging the transfer. This setup can be cheap since the setup does not have the same reliability constraints as long as all clients correctly handle 404. Also, some of this overhead can be optimized away by batching the setup requests.

However, a protocol which requires setup for all messaging will always be more expensive than other options.

Certified HTTP

2007-11-30T18:19:15Z

Phoenix Linden: /* X-Message-ID */

= Goals =
The basic goal of Certified HTTP (colloquially known as chttp) is to perform exactly-once messaging between two hosts.

From a standard http client perspective, if the client reads a whole response, then it knows for certain the server handled the request. However, for all other failure modes, the client can't be sure if the server did, or did-not perform the request function. On the server side, the server can never know if the client ever got the answer or not. For some operations, we need the ability for the client to perform a data-altering operation and be insistent that it occur. In particular, if it isn't certain that it happened, then it must be able to try again safely.

The bigger picture goal is to make a simple way to conduct reliable delivery and receipt such that general adoption by the wider community is possible. This means that we have to respect HTTP where we can to take advantage of existing tools and methodology and to never contradict common conventions in a REST world.

'''Join the [https://lists.secondlife.com/cgi-bin/mailman/listinfo/chttpdev mailing list].'''

= Workflow =

The workflow is a specification/pseudocode for what actions both ends of chttp communication need to take to fulfill the requirements.

== Interaction Sequence ==

Here's a diagram that describes an everything-works certified http communication.

[[Image:Interaction_sequence.png]]

Of note are the failure points. These are the effective crash locations of the participants (the failure points on the arrows represent communication failures). Actions that intervene between two failure points should be deterministic and/or atomic enough that a crash occurring midway through them is functionally identical to a crash occurring at the immediately prior failure point.

The [[Certified HTTP Failure Diagrams]] page (warning: '''very''' image-heavy) has a relatively-exhaustive exploration of the way a Certified HTTP implementation should behave in the face of failures.

== Sending a Message ==

The sending-side API looks very much like a normal HTTP method call:
response = certified_http.put(url, body)

What happens under the covers is:
# Generate a globally unique message ID for the message
# Store the outgoing request (headers and all), including the message id, in a durable store "outbox", and waits for a response.
# A potentially asynchronous process performs the following steps:
## Retrieves the request from the outbox.
## Performs the HTTP request specified by the outbox request and waits for a response.
## If a response is not forthcoming, for whatever reason, the process retries after a certain period.
## If the server sends an error code that indicates that the reliable message will never complete (e.g. 501), or a long timeout expires indicating that an absurd amount of time has elapsed, the method throws an exception.
# Opens a transaction on the durable store
# Stores the incoming response in a durable inbox.
# 'Tombstones' the message in the outbox, which essentially marks the message as having been received, so that if the application resumes again, it doesn't resend.
# Closes the transaction on the durable store
# If the response contains a header indicating a confirmation url on the recipient, performs an HTTP DELETE on the resource to ack the incoming message.

There are no explicit semantics for the response body, like HTTP itself. The content will vary depending on the application.

== Receiving a Message ==

The receiver sets up a node in the url hierarchy, just like a regular http node. When an incoming request comes in, the receiver:

# Stores the incoming request in a durable store "inbox", if it doesn't already contain a message with the same ID.
# A potentially asynchronous process performs the following steps:
## Looks for responses in the outbox matching the incoming message id, and if it finds one, sends it as the response without invoking anything else.
## Opens a transaction on the database, locking the inbox request
## Calls the handler method on the receiving node:
### <code>def handle_put(body, txn):<br/>return "My Response"</code>
### The handler method can use the open transaction to perform actions in the database that are atomic with the receipt of the message. Any non-idempotent operation must be done atomically in this way.
## Stores the return value of the handle method as an outgoing response in the outbox, without closing the transaction.
## Removes the incoming request from the inbox
## Closes the transaction
# Discovers a new item in the outbox, responds to the incoming http request with the response from the outbox, including a url that, if DELETEd, will remove the item from the outbox.

= Requirements =

We have the concept of a "long" time (LT). The purpose of this time is to ensure that any clients will stop trying a particular request long before the server discards state associated with the request. This is not a very theoretically "pure" concept, since it relies on all parties conforming to certain (reasonable) assumptions, but we believe that we get significant benefits (lack of explicit negotiation), at little risk of actually entering an incorrect state. chttp is expected to generate a small amount of bookkeeping data for each message, and there needs to be a way to expire this data in a way that doesn't involve additional negotiation between servers and clients. The server should keep data for LT, and clients should not retry messages that are older than LT/2 or similar, so that there is at least LT/2 for a Reliable Host to recover from errors, and LT/2 for clock skew. LT therefore should be orders of magnitude longer than the longest downtime we expect to see in the system and the largest clock skew we expect to see. Off the cuff, 30 days seems like a reasonable value for LT.

* chttp is based on http, and can use any facility provided by http 1.1 where not otherwise contradicted.
** this includes the use of https, pipelining, chunked encoding, proxies, redirects, caches, and headers such as Accept, Accept-Encoding, Expect, and Content-Type.
** any normal http verb appropriate to context should be accepted, eg POST, PUT, GET, DELETE
** unless otherwise specified, the http feature set in use is orthogonal and effectively transparent to chttp
* in any complete chttp exchange the client and server can eventually agree on success or failure of delivery, though it is more important that no ill effects arise when they disagree
* any message will be effectively received once and only once or not at all
* the content of the http body must be opaque to chttp
* the URI of the original request must be opaque to chttp
* chttp enabled clients and servers can integrate with unreliable tools
** the chttp server can differentiate reliable requests and respond without reliability guarantees (i.e. act as a normal http server)
** chttp clients can differentiate reliable responses and handle unreliable servers (i.e. act as a normal http client)
* the client will persist the local time of sending
* if there is one the client must either have the persisted outgoing body or the exact same body can be regenerated on the fly
* the server will persist the local time of message receipt
* the server must persist the response body or have a mechanism to idempotently generate the same response to the same request
* all urls with a chttp server behind them are effectively idempotent for all uniquely identified messages
** the client can retry steadily over a period of LT/2 days
** the client and server are assumed to almost always be running
** over that window of opportunity, the same message will always get the same response
* all persisted data on a single host is ACID

== requirements on top of http ==
* if the body of the request is non-zero length, the client MUST include a Content-Length header, unless prohibited by section 4.4 of [http://www.w3.org/Protocols/rfc2616/rfc2616.html RFC 2616]
** the server will look for \r\n\r\n and content length body to consider the request complete
** an incomplete request will result in 4XX status code
* if the body of the response is non-zero length, the server must include a Content-Length header
** the client will look for \r\n\r\n and content length body to consider the response complete
** the client will retry on an incomplete response
* Messages can not be terminated by closing the connection -- only positive expressions of message termination (such as Content-Length) can guarantee that a full message is received.

== assumptions ==

* The client and server will not have any significant time discontinuity, i.e., the clock difference between them should be less than LT/100.
* The client and server will not have clock drift more than LT/100 per day.
* Both parties exchanging messages are Reliable Hosts (defined below).
* Generating a globally unique message ID is inexpensive.
* It is possible to store a large amount of 'small' data (such as [[UUID]]s, urls, and date/timestamps) for LT. "Large" in this case means "as many items as the throughput of a host implies that you could create during LT". In other words, storing this small data will never be a resource problem.
* Any transaction or data handled by this system will become useless well before LT has elapsed.

; Reliable Host : A reliable host has the following properties:
* The host has a durable data store of finite size, which can store data in such a way that it is guaranteed to be recoverable even in the face of a certain number of hardware failures.
* The host will not be down forever. Either a clone will be brought up on different hardware, or the machine itself will reappear within a day or so.
* The host can perform {{Wikipedia|ACID|w=n}} operations on the data it contains.

= Implementation =
Requiring an opaque body and URI pretty much requires either negotiating an URL beforehand or adding new headers. Since the former was discarded earlier (reliable delivery after setup), we will focus on adding request and response headers.

This is a suggested implementation:
# chttp enabled servers will behave idempotently with a unique message id on the request
# the server can request acknowledgment from the client if the request consumes server resources

== Request ==
A client will start a reliable message with a GET, POST, or PUT to an url on a reliable http server. The url may be known in advance or returned as part of an earlier application protocol exchange. The message itself will be uniquely identified by a new header for the message id.

=== X-Message-ID ===
A combination of client host identifier with a uuid or sequence number which specifies the reliability client ID for the request. When a server detects the X-Message-ID, it can guarantee reliable message delivery.

Since the message id must be unique, implementations should generate an id of the form <nowiki>$random_uuid@$client_host</nowiki> where the uuid is from a cryptographically secure generator and client_host is the name of the host.

Sending a message with the same message id but a a different body has an undefined result.

Sending a message with the same message id but with a different header which implies a different response body, eg, the first request specifies "Accept: text/plain" and the second request specifies "Accept: text/html", the response can be any one of:

* The original response.
* A transcoded response conforming to the new headers.
* A 4xx indicating that the server has detected the incompatability
* A 5xx indicating failure to transcode the original response.

== Response ==
Generally, when the client gets the 2XX back from the server, the message has been delivered. If the server has a response body, then the client will need to acknowledge receipt of the entire body. If the entire body is not read, the client can safely resubmit the exact same request. The server will include a message url in the headers if the client specified a message id on request and the body requires persistence by the server.

=== X-Message-URL ===
This will be a unique url on the server for the client message id which the client will DELETE upon receipt of the entire response to the request. This will only exist if there is a non-null response body or the server is consuming significant resources to maintain that url. When the client performs the delete, the server can flush all persisted resources other than the fact that the message was sent at some point.

If the client performs a GET to the message url prior to DELETE, the server must return the same body as the original response, including the X-Message-URL.

== Status Codes ==

The semantics of Certified HTTP are to retry until the message goes through. HTTP status codes provide one way of determining whether the message made it or not; we've grouped these status codes into 'success' or 'retry'. In many cases they can signify that the client is attempting to send an invalid message, an error in the application logic; these are labeled as 'fail'. There is a third class, where the status code may be ambiguous; e.g. 404, which is often emitted by temporarily-misconfigured webservers, but may also indicate that an incorrect url was chosen.

=== Success ===

These status codes, when received, give the client permission to do whatever cleanup it needs to do, and to return to caller, safe in the assumption that the message was delivered.

* 200 OK
* 201 Created
* 203 Non-Authoritative Information
* 204 No Content
* 205 Reset Content
* 206 Partial Content
* 304 Not Modified

=== Retry ===

These status codes indicate a temporary failure or misconfiguration on the server side, and therefore the client should retry until it gets something different. All the redirected/proxied messages carry the same message-id.

* 202 Accepted (potentially delaying longer than normal)
* 300 Multiple Choices (follow redirect)
* 302 Found (follow redirect)
* 305 Use Proxy (use proxy)
* 307 Temporary Redirect (follow redirect only if GET)
* 408 Request Timeout
* 413 Request Entity Too Large (if Retry-After header present)
* 502 Bad Gateway
* 503 Service Unavailable
* 504 Gateway Timeout

=== Fail ===

If your application logic screws up and picks an improper content-type or messes up the url, then the Certified HTTP subsystem shouldn't be burdened with retrying forever for a message that will never be delivered. If it receives these status codes, it will raise an exception to the caller and nuke the outgoing request.

* 400 Bad Request
* 401 Unauthorized
* 402 Payment Required
* 403 Forbidden
* 410 Gone
* 411 Length Required
* 413 Request Entity Too Large (if no Retry-After header present)
* 414 Request-URI Too Long
* 415 Unsupported Media Type
* 416 Requested Range Not Satisfiable
* 417 Expectation Failed
* 501 Not Implemented
* 505 HTTP Version Not Supported

=== Ambiguous ===

It's a little ambiguous what to do when the client gets one of these status codes, so we think that the application should decide. There are a few ways to do that:
# The client raises an exception with a retry() method that can be caught by the application, and retried if the application determines that the exception represented a temporary failure.
# The application passes a list to the Certified HTTP subsystem that sorts these status codes into 'retry' or 'fail'.
# The subsystem uses a heuristic such as retrying for a short period of time then converting to a Fail if still not successful.
Here's the list of status codes:

* 303 See Other (retry will use GET even if original used POST)
* 307 Temporary Redirect (only if POST)
* 404 Not Found
* 406 Not Acceptable
* 407 Proxy Authentication Required
* 409 Conflict
* 412 Precondition Failed
* 500 Internal Server Error

= Related Technologies =
I believe that all competitors to this fall into one of three categories, specialized message queues, reliable logic tunneled through HTTP, and delivery over HTTP with setup charges.

== traditional message queue technology ==
This includes products like [http://www-306.ibm.com/software/integration/wmq/ MQ], [http://www.microsoft.com/windowsserver2003/technologies/msmq/default.mspx MSMQ], and [http://activemq.apache.org/ ActiveMQ].

These technologies are useful, but provide a number of hurdles:
* No common standards.
* Integrates a new technology with unknown performance characteristics.
* Requires significant operational overhead.

Because of this, we have opted to use HTTP as a foundation of the technology.

== reliable application logic in body ==
This includes technologies like [http://www.ibm.com/developerworks/library/ws-httprspec/ httpr] and [http://www.ibm.com/developerworks/library/specification/ws-rm/ ws-reliable].

These tend to be thoroughly engineered protocol specifications which regrettably repeat the mistakes of the nearly defunct XMLRPC and the soon to join it SOAP -- namely, treating services as a function call. This is a reasonable approach, and is probably the most obvious to the engineers working on the problem. The most obvious path, which is followed in both of the examples, is to package a traditional message queue body into an HTTP body sent via POST. Treating web services as function calls severely limits the expressive nature of HTTP and should be avoided.

Consumers of web services prefer REST APIs rather than function calls over HTTP. I believe this is because REST is inherently more comprehensible to consumers since all of the data is data the consumer requested. In one telling data point, Amazon has both SOAP and REST interfaces to their web services, and 85% of their usage is of the REST interface[http://www.oreillynet.com/pub/wlg/3005]. I believe ceding power to the consumer is the only path to make wide adoption possible. In doing so, we must drop the entire concept of burying data the consumer wants inside application data.

== reliable delivery after setup ==
There appear to be a few proposals of this nature around the web and a shining example can be found in [http://www.dehora.net/doc/httplr/draft-httplr-01.html httplr].

These are http reliability mechanisms which require a round trip to begin the reliable transfer and then follow through with some permutation of acknowledging the transfer. This setup can be cheap since the setup does not have the same reliability constraints as long as all clients correctly handle 404. Also, some of this overhead can be optimized away by batching the setup requests.

However, a protocol which requires setup for all messaging will always be more expensive than other options.

Certified HTTP

2007-11-29T18:01:37Z

Phoenix Linden: /* Request */

= Goals =
The basic goal of Certified HTTP (colloquially known as chttp) is to perform exactly-once messaging between two hosts.

From a standard http client perspective, if the client reads a whole response, then it knows for certain the server handled the request. However, for all other failure modes, the client can't be sure if the server did, or did-not perform the request function. On the server side, the server can never know if the client ever got the answer or not. For some operations, we need the ability for the client to perform a data-altering operation and be insistent that it occur. In particular, if it isn't certain that it happened, then it must be able to try again safely.

The bigger picture goal is to make a simple way to conduct reliable delivery and receipt such that general adoption by the wider community is possible. This means that we have to respect HTTP where we can to take advantage of existing tools and methodology and to never contradict common conventions in a REST world.

'''Join the [https://lists.secondlife.com/cgi-bin/mailman/listinfo/chttpdev mailing list].'''

= Workflow =

The workflow is a specification/pseudocode for what actions both ends of chttp communication need to take to fulfill the requirements.

== Interaction Sequence ==

Here's a diagram that describes an everything-works certified http communication.

[[Image:Interaction_sequence.png]]

Of note are the failure points. These are the effective crash locations of the participants (the failure points on the arrows represent communication failures). Actions that intervene between two failure points should be deterministic and/or atomic enough that a crash occurring midway through them is functionally identical to a crash occurring at the immediately prior failure point.

The [[Certified HTTP Failure Diagrams]] page (warning: '''very''' image-heavy) has a relatively-exhaustive exploration of the way a Certified HTTP implementation should behave in the face of failures.

== Sending a Message ==

The sending-side API looks very much like a normal HTTP method call:
response = certified_http.put(url, body)

What happens under the covers is:
# Generate a globally unique message ID for the message
# Store the outgoing request (headers and all), including the message id, in a durable store "outbox", and waits for a response.
# A potentially asynchronous process performs the following steps:
## Retrieves the request from the outbox.
## Performs the HTTP request specified by the outbox request and waits for a response.
## If a response is not forthcoming, for whatever reason, the process retries after a certain period.
## If the server sends an error code that indicates that the reliable message will never complete (e.g. 501), or a long timeout expires indicating that an absurd amount of time has elapsed, the method throws an exception.
# Opens a transaction on the durable store
# Stores the incoming response in a durable inbox.
# 'Tombstones' the message in the outbox, which essentially marks the message as having been received, so that if the application resumes again, it doesn't resend.
# Closes the transaction on the durable store
# If the response contains a header indicating a confirmation url on the recipient, performs an HTTP DELETE on the resource to ack the incoming message.

There are no explicit semantics for the response body, like HTTP itself. The content will vary depending on the application.

== Receiving a Message ==

The receiver sets up a node in the url hierarchy, just like a regular http node. When an incoming request comes in, the receiver:

# Stores the incoming request in a durable store "inbox", if it doesn't already contain a message with the same ID.
# A potentially asynchronous process performs the following steps:
## Looks for responses in the outbox matching the incoming message id, and if it finds one, sends it as the response without invoking anything else.
## Opens a transaction on the database, locking the inbox request
## Calls the handler method on the receiving node:
### <code>def handle_put(body, txn):<br/>return "My Response"</code>
### The handler method can use the open transaction to perform actions in the database that are atomic with the receipt of the message. Any non-idempotent operation must be done atomically in this way.
## Stores the return value of the handle method as an outgoing response in the outbox, without closing the transaction.
## Removes the incoming request from the inbox
## Closes the transaction
# Discovers a new item in the outbox, responds to the incoming http request with the response from the outbox, including a url that, if DELETEd, will remove the item from the outbox.

= Requirements =

We have the concept of a "long" time (LT). The purpose of this time is to ensure that any clients will stop trying a particular request long before the server discards state associated with the request. This is not a very theoretically "pure" concept, since it relies on all parties conforming to certain (reasonable) assumptions, but we believe that we get significant benefits (lack of explicit negotiation), at little risk of actually entering an incorrect state. chttp is expected to generate a small amount of bookkeeping data for each message, and there needs to be a way to expire this data in a way that doesn't involve additional negotiation between servers and clients. The server should keep data for LT, and clients should not retry messages that are older than LT/2 or similar, so that there is at least LT/2 for a Reliable Host to recover from errors, and LT/2 for clock skew. LT therefore should be orders of magnitude longer than the longest downtime we expect to see in the system and the largest clock skew we expect to see. Off the cuff, 30 days seems like a reasonable value for LT.

* chttp is based on http, and can use any facility provided by http 1.1 where not otherwise contradicted.
** this includes the use of https, pipelining, chunked encoding, proxies, redirects, caches, and headers such as Accept, Accept-Encoding, Expect, and Content-Type.
** any normal http verb appropriate to context should be accepted, eg POST, PUT, GET, DELETE
** unless otherwise specified, the http feature set in use is orthogonal and effectively transparent to chttp
* in any complete chttp exchange the client and server can eventually agree on success or failure of delivery, though it is more important that no ill effects arise when they disagree
* any message will be effectively received once and only once or not at all
* the content of the http body must be opaque to chttp
* the URI of the original request must be opaque to chttp
* chttp enabled clients and servers can integrate with unreliable tools
** the chttp server can differentiate reliable requests and respond without reliability guarantees (i.e. act as a normal http server)
** chttp clients can differentiate reliable responses and handle unreliable servers (i.e. act as a normal http client)
* the client will persist the local time of sending
* if there is one the client must either have the persisted outgoing body or the exact same body can be regenerated on the fly
* the server will persist the local time of message receipt
* the server must persist the response body or have a mechanism to idempotently generate the same response to the same request
* all urls with a chttp server behind them are effectively idempotent for all uniquely identified messages
** the client can retry steadily over a period of LT/2 days
** the client and server are assumed to almost always be running
** over that window of opportunity, the same message will always get the same response
* all persisted data on a single host is ACID

== requirements on top of http ==
* if the body of the request is non-zero length, the client MUST include a Content-Length header, unless prohibited by section 4.4 of [http://www.w3.org/Protocols/rfc2616/rfc2616.html RFC 2616]
** the server will look for \r\n\r\n and content length body to consider the request complete
** an incomplete request will result in 4XX status code
* if the body of the response is non-zero length, the server must include a Content-Length header
** the client will look for \r\n\r\n and content length body to consider the response complete
** the client will retry on an incomplete response
* Messages can not be terminated by closing the connection -- only positive expressions of message termination (such as Content-Length) can guarantee that a full message is received.

== assumptions ==

* The client and server will not have any significant time discontinuity, i.e., the clock difference between them should be less than LT/100.
* The client and server will not have clock drift more than LT/100 per day.
* Both parties exchanging messages are Reliable Hosts (defined below).
* Generating a globally unique message ID is inexpensive.
* It is possible to store a large amount of 'small' data (such as [[UUID]]s, urls, and date/timestamps) for LT. "Large" in this case means "as many items as the throughput of a host implies that you could create during LT". In other words, storing this small data will never be a resource problem.
* Any transaction or data handled by this system will become useless well before LT has elapsed.

; Reliable Host : A reliable host has the following properties:
* The host has a durable data store of finite size, which can store data in such a way that it is guaranteed to be recoverable even in the face of a certain number of hardware failures.
* The host will not be down forever. Either a clone will be brought up on different hardware, or the machine itself will reappear within a day or so.
* The host can perform {{Wikipedia|ACID|w=n}} operations on the data it contains.

= Implementation =
Requiring an opaque body and URI pretty much requires either negotiating an URL beforehand or adding new headers. Since the former was discarded earlier (reliable delivery after setup), we will focus on adding request and response headers.

This is a suggested implementation:
# chttp enabled servers will behave idempotently with a unique message id on the request
# the server can request acknowledgment from the client if the request consumes server resources

== Request ==
A client will start a reliable message with a GET, POST, or PUT to an url on a reliable http server. The url may be known in advance or returned as part of an earlier application protocol exchange. The message itself will be uniquely identified by a new header for the message id.

=== X-Message-ID ===
A combination of client host identifier with a uuid or sequence number which specifies the reliability client ID for the request. When a server detects the X-Message-ID, it can guarantee reliable message delivery.

Since the message id must be unique, implementations should generate an id of the form <nowiki>$random_uuid@$client_host</nowiki> where the uuid is from a cryptographically secure generator and client_host is the name of the host.

Sending a message with the same message id but a a different body has an undefined result.

Sending a message with the same message id but with a different header which implies a different response body, eg, the first request specifies "Accept: text/plain" and the second request specifies "Accept: text/html", the response is undefined. The server may respond with the original response, a 4xx indicating client error, or even a 5xx if the server attempted but failed to service the equivalent response with a different content body.

== Response ==
Generally, when the client gets the 2XX back from the server, the message has been delivered. If the server has a response body, then the client will need to acknowledge receipt of the entire body. If the entire body is not read, the client can safely resubmit the exact same request. The server will include a message url in the headers if the client specified a message id on request and the body requires persistence by the server.

=== X-Message-URL ===
This will be a unique url on the server for the client message id which the client will DELETE upon receipt of the entire response to the request. This will only exist if there is a non-null response body or the server is consuming significant resources to maintain that url. When the client performs the delete, the server can flush all persisted resources other than the fact that the message was sent at some point.

If the client performs a GET to the message url prior to DELETE, the server must return the same body as the original response, including the X-Message-URL.

== Status Codes ==

The semantics of Certified HTTP are to retry until the message goes through. HTTP status codes provide one way of determining whether the message made it or not; we've grouped these status codes into 'success' or 'retry'. In many cases they can signify that the client is attempting to send an invalid message, an error in the application logic; these are labeled as 'fail'. There is a third class, where the status code may be ambiguous; e.g. 404, which is often emitted by temporarily-misconfigured webservers, but may also indicate that an incorrect url was chosen.

=== Success ===

These status codes, when received, give the client permission to do whatever cleanup it needs to do, and to return to caller, safe in the assumption that the message was delivered.

* 200 OK
* 201 Created
* 203 Non-Authoritative Information
* 204 No Content
* 205 Reset Content
* 206 Partial Content
* 304 Not Modified

=== Retry ===

These status codes indicate a temporary failure or misconfiguration on the server side, and therefore the client should retry until it gets something different. All the redirected/proxied messages carry the same message-id.

* 202 Accepted (potentially delaying longer than normal)
* 300 Multiple Choices (follow redirect)
* 302 Found (follow redirect)
* 305 Use Proxy (use proxy)
* 307 Temporary Redirect (follow redirect only if GET)
* 408 Request Timeout
* 413 Request Entity Too Large (if Retry-After header present)
* 502 Bad Gateway
* 503 Service Unavailable
* 504 Gateway Timeout

=== Fail ===

If your application logic screws up and picks an improper content-type or messes up the url, then the Certified HTTP subsystem shouldn't be burdened with retrying forever for a message that will never be delivered. If it receives these status codes, it will raise an exception to the caller and nuke the outgoing request.

* 400 Bad Request
* 401 Unauthorized
* 402 Payment Required
* 403 Forbidden
* 410 Gone
* 411 Length Required
* 413 Request Entity Too Large (if no Retry-After header present)
* 414 Request-URI Too Long
* 415 Unsupported Media Type
* 416 Requested Range Not Satisfiable
* 417 Expectation Failed
* 501 Not Implemented
* 505 HTTP Version Not Supported

=== Ambiguous ===

It's a little ambiguous what to do when the client gets one of these status codes, so we think that the application should decide. There are a few ways to do that:
# The client raises an exception with a retry() method that can be caught by the application, and retried if the application determines that the exception represented a temporary failure.
# The application passes a list to the Certified HTTP subsystem that sorts these status codes into 'retry' or 'fail'.
# The subsystem uses a heuristic such as retrying for a short period of time then converting to a Fail if still not successful.
Here's the list of status codes:

* 303 See Other (retry will use GET even if original used POST)
* 307 Temporary Redirect (only if POST)
* 404 Not Found
* 406 Not Acceptable
* 407 Proxy Authentication Required
* 409 Conflict
* 412 Precondition Failed
* 500 Internal Server Error

= Related Technologies =
I believe that all competitors to this fall into one of three categories, specialized message queues, reliable logic tunneled through HTTP, and delivery over HTTP with setup charges.

== traditional message queue technology ==
This includes products like [http://www-306.ibm.com/software/integration/wmq/ MQ], [http://www.microsoft.com/windowsserver2003/technologies/msmq/default.mspx MSMQ], and [http://activemq.apache.org/ ActiveMQ].

These technologies are useful, but provide a number of hurdles:
* No common standards.
* Integrates a new technology with unknown performance characteristics.
* Requires significant operational overhead.

Because of this, we have opted to use HTTP as a foundation of the technology.

== reliable application logic in body ==
This includes technologies like [http://www.ibm.com/developerworks/library/ws-httprspec/ httpr] and [http://www.ibm.com/developerworks/library/specification/ws-rm/ ws-reliable].

These tend to be thoroughly engineered protocol specifications which regrettably repeat the mistakes of the nearly defunct XMLRPC and the soon to join it SOAP -- namely, treating services as a function call. This is a reasonable approach, and is probably the most obvious to the engineers working on the problem. The most obvious path, which is followed in both of the examples, is to package a traditional message queue body into an HTTP body sent via POST. Treating web services as function calls severely limits the expressive nature of HTTP and should be avoided.

Consumers of web services prefer REST APIs rather than function calls over HTTP. I believe this is because REST is inherently more comprehensible to consumers since all of the data is data the consumer requested. In one telling data point, Amazon has both SOAP and REST interfaces to their web services, and 85% of their usage is of the REST interface[http://www.oreillynet.com/pub/wlg/3005]. I believe ceding power to the consumer is the only path to make wide adoption possible. In doing so, we must drop the entire concept of burying data the consumer wants inside application data.

== reliable delivery after setup ==
There appear to be a few proposals of this nature around the web and a shining example can be found in [http://www.dehora.net/doc/httplr/draft-httplr-01.html httplr].

These are http reliability mechanisms which require a round trip to begin the reliable transfer and then follow through with some permutation of acknowledging the transfer. This setup can be cheap since the setup does not have the same reliability constraints as long as all clients correctly handle 404. Also, some of this overhead can be optimized away by batching the setup requests.

However, a protocol which requires setup for all messaging will always be more expensive than other options.

Talk:Certified HTTP

2007-11-04T19:14:26Z

Phoenix Linden: /* Status Codes */

==X-Message-ID==

How about replacing the $random_uuid with an MD5 (or stronger) digest of the message body? That would eliminate the undefined result of sending a message with the same message id but a a different body. (Undefined results can be opportunities for exploits.) --[[User:Omei Turnbull|Omei Turnbull]] 20:21, 10 July 2007 (PDT)

:That wouldn't solve the problem, you would still be sending a message with the same message id if you sent two identical messages bodies. You would be guarantying a collision. It is really only an issue if two messages of the same ID are being processed at the same time. I think using $random_uuid is reasonable and in the event of a Message-ID collision or malformed Message-ID have the server return a [http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1 400]. -- [[User:Strife Onizuka|Strife Onizuka]] 00:01, 11 July 2007 (PDT)

:Heh, looks like Strife and I saw this at the same moment. :-) I guess if you digested the entire state of the message, including headers, receiving url, and sending url/host, then you're only ruling out the case where you do actually want to send two of the exact same message between the same two hosts at the exact same time and have both be processed as independent message. Thanks for the idea! [[User:Which Linden|Which Linden]] 00:06, 11 July 2007 (PDT)

== X-Message-URL ==

:"If the client performs a GET to the message url prior to DELETE, the server must return the same body as the original response, including the X-Message-URL."

I think this may be an attack point, since it would require the server to cache the response body. There should also be a short timeout on the caching. This requirement makes it look like this protocol isn't something you want use with unauthorized clients. -- [[User:Strife Onizuka|Strife Onizuka]] 00:18, 11 July 2007 (PDT)

::How does this differ from the explicit requirement that "the server must persist the response body or have a mechanism to idempotent generate the same response to the same request"? But yes, it seems like the need to persist un-acknowledged response bodies for 15 days creates a big opportunity for a DDOS-type attack if reliable messages from unauthenticated clients are allowed. - [[User:Omei_Turnbull|Omei Turnbull]]

::: That would be a problem if it only statically persisted a complete response. If it has a way to generate the idempotent response at any later time, there is no need to statically persist the complete response. [[User:Dzonatas Sol|Dzonatas Sol]] 10:22, 11 July 2007 (PDT)

:::: The entire response body has to be stored so that if the connection was terminated before the response was received it can be requested by sending a GET to X-Message-URL (instead of a DELETE). -- [[User:Strife Onizuka|Strife Onizuka]] 15:27, 11 July 2007 (PDT)

::::: That would be one way. There are other ways to generate a response that is idempotent. [[User:Dzonatas Sol|Dzonatas Sol]] 15:49, 11 July 2007 (PDT)

:::::: True, but it really depends on what is being requested and whether what is wanted is the old status or the current status. -- [[User:Strife Onizuka|Strife Onizuka]] 16:11, 11 July 2007 (PDT)

::::::: Indeed, it depends on the intervals of when data is aggregated or archived. The complexity begins there. [[User:Dzonatas Sol|Dzonatas Sol]] 16:15, 11 July 2007 (PDT)

::The issue I see (which I think is the same issue Strife was referring to) is that when the server gets a request, it has to check to see whether it is a duplicate of any outstanding request (i.e. a request for which the response hasn't been acknowledged) issued within the last 15 days, so that if it is, it will repeat its previous response. If these requests can come from untrusted clients, the server could purposely be subjected to requests that are not acknowledged, until the server is no longer able to respond to any requests in a timely manner.--[[User:Omei Turnbull|Omei Turnbull]] 12:59, 11 July 2007 (PDT)

:::Thats what I was thinking. -- [[User:Strife Onizuka|Strife Onizuka]] 15:27, 11 July 2007 (PDT)

:::: Though there are certain things you could do to stave off DoS attacks like refusing to serve more than N connections at a time and refusing to even open a tcp connection to any future ones, I agree that without further consideration it's probably not a good idea to do chttp between hosts that don't trust each other. [[User:Which Linden|Which Linden]] 21:12, 3 October 2007 (PDT)

::This could be mitigated by adding a header field in the client message saying whether this is an initial or a follow-up request. The server would not be required to check initial requests against its history of open requests. Follow-up requests, which would require a lookup against the open requests, could be done at reduced priority, so that they don't interfere with normal traffic.--[[User:Omei Turnbull|Omei Turnbull]] 16:43, 11 July 2007 (PDT)

::: Wow, how did I not see this earlier? I think that the problem with this idea is that the client doesn't, in general, know whether it's making an initial or a follow up request. If it hasn't received a response from the server, it doesn't know whether the server received the message and didn't respond, or if the message never made it to the server in the first place (or was incomplete, as would happen if the network died mid-send). [[User:Which Linden|Which Linden]] 21:12, 3 October 2007 (PDT)

== Thoughts ==
For a simple setup X-Message-URL could be the original request URL. The DELETE command should send the same X-Message-ID as the orig request to better facilitate this. This would have the added benefit that a client could possibly cancel a request by sending a DELETE before getting a response.
This doesn't have to be all that complicated to implement. Once a request comes in, check to see if there is a DB entry for it, if it does not exist in the DB, execute the command and write the body to file and return the body. If it does exist in the DB already, check the status of the request, if there is a body, return it and wait for the timeout or DELETE command before removing the DB entry. -- [[User:Strife Onizuka|Strife Onizuka]] 15:34, 11 July 2007 (PDT)

== Cleanup ==

Limiting the number of concurrent requests per client is one way of reducing DOS risk but if a client crashes and reconnects then it will need some way of finding out what requests need to be closed. There should probably be some interface the client can query the server to find out what requests it has open. The response to such a query would give URLs to close those requests but they should not be able to return those request's response bodies as that could be a security breach. Additionally those requests returned should be tagged with the session that created them and the status of that session (so multiple sessions can use the same authorization information concurrently). -- [[User:Strife Onizuka|Strife Onizuka]] 16:24, 11 July 2007 (PDT)

:This is a really interesting point. We've given very little thought to communication with untrusted and unreliable clients. Right now, we are assuming that the client is a reliable service itself -- chttp is essentially a peer protocol between durable hosts. In particular, we want to assume delivery, which means that all the application logic doesn't have to contain a lot of failure cases (always a bugbear to write and test). The application just assumes that the message will eventually make it, despite temporary failures on both sending and receiving hosts. With those assumptions, it's reasonable to say that the client doesn't need to query the server to find out what requests it has open. It's not clear if the semantics even mean anything if the client is untrusted or unreliable. [[User:Which Linden|Which Linden]] 22:01, 11 July 2007 (PDT)

::Perhaps there needs to be a way of identifing trusted hosts? Perhaps using HTTP authentication on servers that require identity? and if they can be identified, don't apply a limit to concurrent requests or at least increase the limit? Though this would surely make https as the perfered protocol in such a case, so authentication information is more secure. -- [[User:Nik Woodget|Nik Woodget]] 10:20, 19 September 2007

::: Could use client certificates, too. I think specifying an authentication method is outside the scope of certified http, though. [[User:Which Linden|Which Linden]] 21:59, 3 October 2007 (PDT)

::: As much as possible, things like authentication, should follow existing http style practice. I'd like to see it compose with the related specs. This seems like an overall good principle [[User: Zha Ewry|Zha Ewry]] 12:40 3 October 2007

== Status Codes ==

I suggest should adjust interpretation of a few of the status codes.
; 304 Not Modified : I believe we should add a requirement that no cHTTP enabled server will return 304 to any request which include x-message-id. In order to maintain idempotence, we should typically return 200, but at least we should return 200 <= status < 300.
; 203 Non-Authoritative Information : I think we should consider this a success because the use case where this makes sense is if the server has a secondary persistent store which it considers good enough for this particular transaction. It also makes me nervous to think of anything in 2xx other than 202 as a retry.
; 406 Not Acceptable : Since the persisted client request theoretically includes the Accept header, there is no way that further calls will ever return anything other than 406. So shouldn't we fail sooner?
; 411 Length Required : A cHTTP dialogue requires Content-Length for every non-zero length message so this sound like a permanent failure to me.

[[User:Phoenix Linden|Phoenix Linden]] 22:28, 1 November 2007 (PDT)

:Hah, we should have looked at [http://www.ilovejackdaniels.com/apache/http-status-codes-explained/ this page], since it already kinda does the work for us.
:; 304 : I don't think it really matters. If the client wants to add an If-Modified-Since header, why shouldn't the server accommodate it? I don't think there's a compelling reason to make chttp behave differently than standard http with regards to this status code.
:; 203 : Agreed.
:; 406 : The case where this might be usefully Ambiguous is when a server is temporarily incapacitated or misconfigured and throws 406s until it gets fixed. Not sure if that's plausible though.
:; 411 : Agreed.
:Thanks for looking these over! I'm gonna wait for Sardonyx to weigh in before moving stuff around though.
:[[User:Which Linden|Which Linden]] 23:21, 1 November 2007 (PDT)

::; 304: Agree.
::; 406: Maybe. Let's leave it ambiguous.
::[[User:Phoenix Linden|Phoenix Linden]] 11:14, 4 November 2007 (PST)

Talk:Certified HTTP

2007-11-02T05:28:23Z

Phoenix Linden: Status Codes

Compiling Issues with Vista/MSVS2008

2007-10-11T15:54:24Z

Phoenix Linden: Compiling Issues with Vista/MSVS2008 moved to Compiling Issues with Vista and MSVS2008

#REDIRECT [[Compiling Issues with Vista and MSVS2008]]

User:Stefano CiscoSystems/Compiling Issues with Vista and MSVS2008

2007-10-11T15:54:24Z

Phoenix Linden: Compiling Issues with Vista/MSVS2008 moved to Compiling Issues with Vista and MSVS2008

== could not deduce template argument from 'LLMessageThrottleEntry' in llmessagethrottle.cpp ==
* [VS9PATH]\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::deque<_Ty,_Alloc> &,const std::deque<_Ty,_Alloc> &)' : could not deduce template argument for 'const std::deque<_Ty,_Alloc> &' from 'LLMessageThrottleEntry'
* [VS9PATH]\vc\include\deque(1341) : see declaration of 'std::operator =='
* [VS9PATH]\vc\include\algorithm(435) : see reference to function template instantiation '_FwdIt1 std::_Search_n<_FwdIt1,_Diff2,_Ty,bool(__cdecl *)(LLMessageThrottleEntry,LLMessageThrottleEntry)>(_FwdIt1,_FwdIt1,_Diff2,const _Ty &,_Pr,std::random_access_iterator_tag)' being compiled

The first error is related to the search_n for the LLMessageThrottleEntry class on line 113 of \indra\llmessage\llmessagethrottle.cpp.

The error happens in [yourpath]\Visual Studio 9.0\vc\include\algorithm, on line 406 (excerpt follows)

template<class _FwdIt1,
class _Diff2,
class _Ty,
class _Pr> inline
_FwdIt1 _Search_n(_FwdIt1 _First1, _FwdIt1 _Last1,
_Diff2 _Count, const _Ty& _Val, _Pr _Pred, random_access_iterator_tag)
{ // find first _Count * _Val satisfying _Pred, random-access iterators
_DEBUG_RANGE(_First1, _Last1);
_DEBUG_POINTER(_Pred);

if (_Count <= 0)
return (_First1);

_FwdIt1 _Oldfirst1 = _First1;
for (; _Count <= _Last1 - _Oldfirst1; )
{ // enough room, look for a match
if (_Pred(*_First1, _Val))
{ // found part of possible match, check it out
_Diff2 _Count1 = _Count;
_FwdIt1 _Mid1 = _First1;

406: for (; _Oldfirst1 != _First1 && _First1[-1] == _Val; --_First1)
--_Count1; // back up over any skipped prefix

if (_Count1 <= _Last1 - _Mid1)
for (; ; ) // enough left, test suffix
if (--_Count1 == 0)
return (_First1); // found rest of match, report it
else if (!_Pred(*++_Mid1, _Val))
break; // short match not at end

_Oldfirst1 = ++_Mid1; // failed match, take small jump
_First1 = _Oldfirst1;
}
else
{ // no match, take big jump and back up as needed
_Oldfirst1 = _First1 + 1;
_First1 += _Count;
}
}
return (_Last1);
}

So the problem seems to be the operator == in the equality:
_First1[-1] == _Val;
coming from the search_n operation.

They both evaluate to a
const std::deque<_Ty,_Alloc> &
which types are ambiguous for the compiler.

Here is the exact copy of the full compilation error:

1>------ Build started: Project: llmessage, Configuration: Debug Win32 ------
1>Compiling...
1>llmessagethrottle.cpp
1>c:\sources\secondlife\lindenlabclient\indra\llmessage\llmessagethrottle.cpp(134) : warning C4189: 'message_list' : local variable is initialized but not referenced
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::deque<_Ty,_Alloc> &,const std::deque<_Ty,_Alloc> &)' : could not deduce template argument for 'const std::deque<_Ty,_Alloc> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\deque(1341) : see declaration of 'std::operator =='
1> c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(435) : see reference to function template instantiation '_FwdIt1 std::_Search_n<_FwdIt1,_Diff2,_Ty,bool(__cdecl *)(LLMessageThrottleEntry,LLMessageThrottleEntry)>(_FwdIt1,_FwdIt1,_Diff2,const _Ty &,_Pr,std::random_access_iterator_tag)' being compiled
1> with
1> [
1> _FwdIt1=LLMessageThrottle::message_list_iterator_t,
1> _Diff2=int,
1> _Ty=LLMessageThrottleEntry,
1> _Pr=bool (__cdecl *)(LLMessageThrottleEntry,LLMessageThrottleEntry)
1> ]
1> c:\sources\secondlife\lindenlabclient\indra\llmessage\llmessagethrottle.cpp(117) : see reference to function template instantiation '_FwdIt1 std::search_n<LLMessageThrottle::message_list_iterator_t,int,LLMessageThrottleEntry,bool(__cdecl *)(LLMessageThrottleEntry,LLMessageThrottleEntry)>(_FwdIt1,_FwdIt1,_Diff2,const _Ty &,_Pr)' being compiled
1> with
1> [
1> _FwdIt1=LLMessageThrottle::message_list_iterator_t,
1> _Diff2=int,
1> _Ty=LLMessageThrottleEntry,
1> _Pr=bool (__cdecl *)(LLMessageThrottleEntry,LLMessageThrottleEntry)
1> ]
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::list<_Ty,_Ax> &,const std::list<_Ty,_Ax> &)' : could not deduce template argument for 'const std::list<_Ty,_Ax> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\list(1299) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::_Tree<_Traits> &,const std::_Tree<_Traits> &)' : could not deduce template argument for 'const std::_Tree<_Traits> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\xtree(1459) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::basic_string<_Elem,_Traits,_Alloc> &,const _Elem *)' : could not deduce template argument for 'const std::basic_string<_Elem,_Traits,_Alloc> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\string(90) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const _Elem *,const std::basic_string<_Elem,_Traits,_Alloc> &)' : could not deduce template argument for 'const _Elem *' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\string(80) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::basic_string<_Elem,_Traits,_Alloc> &,const std::basic_string<_Elem,_Traits,_Alloc> &)' : could not deduce template argument for 'const std::basic_string<_Elem,_Traits,_Alloc> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\string(70) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::vector<_Ty,_Alloc> &,const std::vector<_Ty,_Alloc> &)' : could not deduce template argument for 'const std::vector<_Ty,_Alloc> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\vector(1309) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::istream_iterator<_Ty,_Elem,_Traits,_Diff> &,const std::istream_iterator<_Ty,_Elem,_Traits,_Diff> &)' : could not deduce template argument for 'const std::istream_iterator<_Ty,_Elem,_Traits,_Diff> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\iterator(266) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::istreambuf_iterator<_Elem,_Traits> &,const std::istreambuf_iterator<_Elem,_Traits> &)' : could not deduce template argument for 'const std::istreambuf_iterator<_Elem,_Traits> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\streambuf(548) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::allocator<_Ty> &,const std::allocator<_Other> &) throw()' : could not deduce template argument for 'const std::allocator<_Ty> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\xmemory(173) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::reverse_iterator<_RanIt> &,const std::reverse_iterator<_RanIt2> &)' : could not deduce template argument for 'const std::reverse_iterator<_RanIt> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\xutility(2193) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::_Revranit<_RanIt,_Base> &,const std::_Revranit<_RanIt2,_Base2> &)' : could not deduce template argument for 'const std::_Revranit<_RanIt,_Base> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\xutility(2007) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2784: 'bool std::operator ==(const std::pair<_Ty1,_Ty2> &,const std::pair<_Ty1,_Ty2> &)' : could not deduce template argument for 'const std::pair<_Ty1,_Ty2> &' from 'LLMessageThrottleEntry'
1> c:\program files\development\microsoft visual studio 9.0\vc\include\utility(68) : see declaration of 'std::operator =='
1>c:\program files\development\microsoft visual studio 9.0\vc\include\algorithm(406) : error C2676: binary '==' : 'LLMessageThrottleEntry' does not define this operator or a conversion to a type acceptable to the predefined operator
1>Build log was saved at "file://c:\Sources\SecondLife\LindenLabClient\indra\llmessage\Debug\BuildLog.htm"
1>llmessage - 14 error(s), 1 warning(s)
========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

And this is the content of the file llmessagethrottle.cpp that i am using:

/**
* @file llmessagethrottle.cpp
* @brief LLMessageThrottle class used for throttling messages.
*
* Copyright (c) 2004-2007, Linden Research, Inc.
*
* Second Life Viewer Source Code
* The source code in this file ("Source Code") is provided by Linden Lab
* to you under the terms of the GNU General Public License, version 2.0
* ("GPL"), unless you have obtained a separate licensing agreement
* ("Other License"), formally executed by you and Linden Lab. Terms of
* the GPL can be found in doc/GPL-license.txt in this distribution, or
* online at http://secondlife.com/developers/opensource/gplv2
*
* There are special exceptions to the terms and conditions of the GPL as
* it is applied to this Source Code. View the full text of the exception
* in the file doc/FLOSS-exception.txt in this software distribution, or
* online at http://secondlife.com/developers/opensource/flossexception
*
* By copying, modifying or distributing this software, you acknowledge
* that you have read and understood your obligations described above,
* and agree to abide by those obligations.
*
* ALL LINDEN LAB SOURCE CODE IS PROVIDED "AS IS." LINDEN LAB MAKES NO
* WARRANTIES, EXPRESS, IMPLIED OR OTHERWISE, REGARDING ITS ACCURACY,
* COMPLETENESS OR PERFORMANCE.
*/

#include "linden_common.h"
#include "llhash.h"

#include "llmessagethrottle.h"
#include "llframetimer.h"

// This is used for the stl search_n function.
bool eq_message_throttle_entry(LLMessageThrottleEntry a, LLMessageThrottleEntry b)
{ return a.getHash() == b.getHash(); }

const U64 SEC_TO_USEC = 1000000;

// How long (in microseconds) each type of message stays in its throttle list.
const U64 MAX_MESSAGE_AGE[MTC_EOF] =
{
10 * SEC_TO_USEC, // MTC_VIEWER_ALERT
10 * SEC_TO_USEC // MTC_AGENT_ALERT
};

LLMessageThrottle::LLMessageThrottle()
{
}

LLMessageThrottle::~LLMessageThrottle()
{
}

void LLMessageThrottle::pruneEntries()
{
// Go through each message category, and prune entries older than max age.
S32 cat;
for (cat = 0; cat < MTC_EOF; cat++)
{
message_list_t* message_list = &(mMessageList[cat]);

// Use a reverse iterator, since entries on the back will be the oldest.
message_list_reverse_iterator_t r_iterator = message_list->rbegin();
message_list_reverse_iterator_t r_last = message_list->rend();

// Look for the first entry younger than the maximum age.
F32 max_age = (F32)MAX_MESSAGE_AGE[cat];
BOOL found = FALSE;
while (r_iterator != r_last && !found)
{
if ( LLFrameTimer::getTotalTime() - (*r_iterator).getEntryTime() < max_age )
{
// We found a young enough entry.
found = TRUE;

// Did we find at least one entry to remove?
if (r_iterator != message_list->rbegin())
{
// Yes, remove it.
message_list->erase(r_iterator.base(), message_list->end());
}
}
else
{
r_iterator++;
}
}

// If we didn't find any entries young enough to keep, remove them all.
if (!found)
{
message_list->clear();
}
}
}

BOOL LLMessageThrottle::addViewerAlert(const LLUUID& to, const char* mesg)
{
message_list_t* message_list = &(mMessageList[MTC_VIEWER_ALERT]);

// Concatenate from,to,mesg into one string.
std::ostringstream full_mesg;
full_mesg << to << mesg;

// Create an entry for this message.
size_t hash = llhash<const char*> (full_mesg.str().c_str());
LLMessageThrottleEntry entry(hash, LLFrameTimer::getTotalTime());

// Check if this message is already in the list.
/*
* Stefano: i did try using this but did not help:
<message_list_iterator_t,int,LLMessageThrottleEntry,bool (__cdecl *)(LLMessageThrottleEntry,LLMessageThrottleEntry)>
*/
message_list_iterator_t found = std::search_n(message_list->begin(), message_list->end(), 1, entry, eq_message_throttle_entry);

if (found == message_list->end())
{
// This message was not found. Add it to the list.
message_list->push_front(entry);
return TRUE;
}
else
{
// This message was already in the list.
return FALSE;
}
}

BOOL LLMessageThrottle::addAgentAlert(const LLUUID& agent, const LLUUID& task, const char* mesg)
{
message_list_t* message_list = &(mMessageList[MTC_AGENT_ALERT]);

// Concatenate from,to,mesg into one string.
std::ostringstream full_mesg;
full_mesg << agent << task << mesg;

// Create an entry for this message.
size_t hash = llhash<const char*> (full_mesg.str().c_str());
LLMessageThrottleEntry entry(hash, LLFrameTimer::getTotalTime());

// Check if this message is already in the list.
/* stefano i commented the following so to get one only error while debugging */
/* message_list_iterator_t found = std::search_n(message_list->begin(), message_list->end(),
1, entry, eq_message_throttle_entry);

if (found == message_list->end())
{
// This message was not found. Add it to the list.
message_list->push_front(entry);
return TRUE;
}
else
{
// This message was already in the list.
return FALSE;
}
*/

}

Recursive URL Substitution Syntax

2007-08-03T18:24:56Z

Phoenix Linden: /* Strings */

Like any substitution syntax, using untrusted formatted strings or untrusted sources of data can lead to exploits. Be careful when designing the usage so that no tainted input winds up in the context.

= Syntax =
The syntax is based on placing curly braces inside an URL to indicate that the curly brace and everything inside should be replaced with a substitution. Each type of substitution will have it's own rules but every time you see { and } then all contents inside those braces are to be replaced.

== Strings ==
String substitution uses an open curly brace '{' followed by a dollar symbol '$' followed by the name of the substitution and a closing curly brace '}'. The name is used as a key into a map whose value will be replaced into the original format string. The key must only contain alphanumeric characters and '+', '-', '_', and spaces.

Values which appear in the map but not referenced in the format string are ignored.

{| border="1"
|+ String Substitution Examples
! Format !! Map Contents !! Result
|-
| {$bucket}.agent.lindenlab.com
| 'bucket':'a'
| a.agent.lindenlab.com
|-
| agent/{$agent-id}/inventory/item/{$item-id}
| 'agent-id':foo, 'item-id':bar
| agent/foo/inventory/item/bar
|}

Values which are lists/tuples will have their elements urlquoted and joined with '/'. I.e. they are assumed to be exploded paths. E.g.:

{| border="1"
! Format !! Map Contents !! Result
|-
| <code>foo/{$stuff}/baz</code>
| <code>'stuff':['one','two','three']</code>
| <code>foo/one/two/three/baz</code>
|}

== Query Strings ==
Query strings are a specialized url syntax for representing the contents of a map as an ampersand delimited url query string including the leading '?'. Query string use an open curly brace '{' followed by a percent symbol '%' followed by the name of a dictionary in the replacement context followed by a closing curly brace '}'.

Unlike string substitution, if the named value is not a key in the map contents, the russ directive will be stripped.

{| border="1"
|+ Query String Substitution Examples
! Format !! Map Contents !! Result
|-
| /sql/{$query}{%params}
| { 'query':'get-agent-name-by-id', 'params':{'agent_id':123}}
| /sql/get-agent-name-by-id?agent_id=123
|-
| /proc/{$proc}{%params}
| { 'proc':'messages/dir/DirFindPeople', 'params':{'estate':1, 'query':'designer clothing'}}
| /proc/messages/dir/DirFindPeople?estate=1&query=designer+clothing
|}

== Functions ==
Function substitution uses an open curly brace '{' followed by a bang symbol '!' followed by the name of the substitution function and a closing curly brace '}'. The name is a function that is available to the substitution engine, and may be implementation specific. The function is prototyped as accepting a map context and returning a string.

For example, <b>{!region-host-port}</b> could be a function which takes a map which is assumed to contain a key <code>'region-id'</code>. The function will perform a service lookup for region presence with the region-id in the service builder, and then parse the return document for the region host and port.

== REST Requests ==
For REST Request substitution, the embedded URL is fetched, parsed for a single [[LLSD]] document which is embedded inside the curly braces.

The simple syntax is an opening curly brace '{', followed by the URL, and terminated with a closing curly brace '}'. The document at the url is parsed and treated as a string. Containers, the undefined element, and non-parseable documents are considered errors.

For http request, no instructions to the protocol means to perform a normal GET.

{| border="1"
|+ Rest Request Substitution Examples
! Format !! Results
|-
| <nowiki>{http://gridtool.agni.lindenlab.com/agents/online-now}</nowiki>
| 58582
|-
| <nowiki>{http://blondie.lindenlab.com/lookup/agentname/phoenix/linden||agent-id}</nowiki>
| 3c115e51-04f4-523c-9fa6-98aff1034730
|}

Supported protocols: http, https

We should probably support file.

== Recursive Substitution ==
In theory, this grammar can be used recursively, though only python currently supports this feature.

{| border="1"
|+ Formating Examples
! Format
|-
| <nowiki>{http://sim1028.{$grid}.{$domain}/agent/{$agent-id}/location}</nowiki>
|-
| {{$node}{$domain}}
|}

= Syntax Specification =
The full syntax is an opening curly brace '{', followed by the URL, followed by a vline '|', followed by protocol specific instructions, followed by a 'vline', followed by a path to follow through the document to the element which will be treated as a string.
<pre>
russ-statement : open-russ substitution close-russ
open-russ: '{'
close-russ: '}'
substituion: string-substitution| query-string-substitution | url-substitution | function-substitution
string-substition: '$' llsd-key
query-string-substition: '%' llsd-key
function-substitution: '!' function-name
function-name: llsd-key
url-substitution: url [ vline [ url-parameters ] vline llsd-path]
url: protocol ':' (normal url authority & host & path & parameters & opaque parts)
protocol: 'http' | 'https'
vline: '|'
url-parameters: verb [ body ]
verb: 'GET' | 'PUT' | 'POST' | 'DELETE'
body: ???
llsd-path: segment * [ "/" segment ]
segment: llsd-key
</pre>

Please note that the following elements in the syntax rules are not well defined:
* llsd-key
* body
* function-name

= Implementations =
== python ==
Our indra python libs have a russ implementation in russ.py which supports:
* string substitution
* query string substitution
* url substitution
* recursive substitution

== c++ ==
In indra/llmessage libs has a russ implementation inside of the LLServiceBuilder class which supports:
* string substitution
* url substitution

== perl ==
In <code>Indra::WebServices</code>, you can call <code>buildService($service_name)</code> to make a client to that service. The current implementation supports:
* string substitution
* query string substitution
* recursive substitution

Recursive URL Substitution Syntax

2007-08-03T18:24:23Z

Phoenix Linden: /* c++ */

Like any substitution syntax, using untrusted formatted strings or untrusted sources of data can lead to exploits. Be careful when designing the usage so that no tainted input winds up in the context.

= Syntax =
The syntax is based on placing curly braces inside an URL to indicate that the curly brace and everything inside should be replaced with a substitution. Each type of substitution will have it's own rules but every time you see { and } then all contents inside those braces are to be replaced.

== Strings ==
String substitution uses an open curly brace '{' followed by a dollar symbol '$' followed by the name of the substitution and a closing curly brace '}'. The name is used as a key into a map whose value will be replaced into the original format string. The key must only contain alphanumeric characters and '+', '-', '_', and spaces.

Values which appear in the map but not referenced in the format string are ignored.

{| border="1"
|+ String Substitution Examples
! Format !! Map Contents !! Result
|-
| {$bucket}.agent.lindenlab.com
| 'bucket':'a'
| a.agent.lindenlab.com
|-
| agent/{$agent-id}/inventory/item/{$item-id}
| 'agent-id':foo, 'item-id':bar
| agent/foo/inventory/item/bar
|}

== Query Strings ==
Query strings are a specialized url syntax for representing the contents of a map as an ampersand delimited url query string including the leading '?'. Query string use an open curly brace '{' followed by a percent symbol '%' followed by the name of a dictionary in the replacement context followed by a closing curly brace '}'.

Unlike string substitution, if the named value is not a key in the map contents, the russ directive will be stripped.

{| border="1"
|+ Query String Substitution Examples
! Format !! Map Contents !! Result
|-
| /sql/{$query}{%params}
| { 'query':'get-agent-name-by-id', 'params':{'agent_id':123}}
| /sql/get-agent-name-by-id?agent_id=123
|-
| /proc/{$proc}{%params}
| { 'proc':'messages/dir/DirFindPeople', 'params':{'estate':1, 'query':'designer clothing'}}
| /proc/messages/dir/DirFindPeople?estate=1&query=designer+clothing
|}

== Functions ==
Function substitution uses an open curly brace '{' followed by a bang symbol '!' followed by the name of the substitution function and a closing curly brace '}'. The name is a function that is available to the substitution engine, and may be implementation specific. The function is prototyped as accepting a map context and returning a string.

For example, <b>{!region-host-port}</b> could be a function which takes a map which is assumed to contain a key <code>'region-id'</code>. The function will perform a service lookup for region presence with the region-id in the service builder, and then parse the return document for the region host and port.

== REST Requests ==
For REST Request substitution, the embedded URL is fetched, parsed for a single [[LLSD]] document which is embedded inside the curly braces.

The simple syntax is an opening curly brace '{', followed by the URL, and terminated with a closing curly brace '}'. The document at the url is parsed and treated as a string. Containers, the undefined element, and non-parseable documents are considered errors.

For http request, no instructions to the protocol means to perform a normal GET.

{| border="1"
|+ Rest Request Substitution Examples
! Format !! Results
|-
| <nowiki>{http://gridtool.agni.lindenlab.com/agents/online-now}</nowiki>
| 58582
|-
| <nowiki>{http://blondie.lindenlab.com/lookup/agentname/phoenix/linden||agent-id}</nowiki>
| 3c115e51-04f4-523c-9fa6-98aff1034730
|}

Supported protocols: http, https

We should probably support file.

== Recursive Substitution ==
In theory, this grammar can be used recursively, though only python currently supports this feature.

{| border="1"
|+ Formating Examples
! Format
|-
| <nowiki>{http://sim1028.{$grid}.{$domain}/agent/{$agent-id}/location}</nowiki>
|-
| {{$node}{$domain}}
|}

= Syntax Specification =
The full syntax is an opening curly brace '{', followed by the URL, followed by a vline '|', followed by protocol specific instructions, followed by a 'vline', followed by a path to follow through the document to the element which will be treated as a string.
<pre>
russ-statement : open-russ substitution close-russ
open-russ: '{'
close-russ: '}'
substituion: string-substitution| query-string-substitution | url-substitution | function-substitution
string-substition: '$' llsd-key
query-string-substition: '%' llsd-key
function-substitution: '!' function-name
function-name: llsd-key
url-substitution: url [ vline [ url-parameters ] vline llsd-path]
url: protocol ':' (normal url authority & host & path & parameters & opaque parts)
protocol: 'http' | 'https'
vline: '|'
url-parameters: verb [ body ]
verb: 'GET' | 'PUT' | 'POST' | 'DELETE'
body: ???
llsd-path: segment * [ "/" segment ]
segment: llsd-key
</pre>

Please note that the following elements in the syntax rules are not well defined:
* llsd-key
* body
* function-name

= Implementations =
== python ==
Our indra python libs have a russ implementation in russ.py which supports:
* string substitution
* query string substitution
* url substitution
* recursive substitution

== c++ ==
In indra/llmessage libs has a russ implementation inside of the LLServiceBuilder class which supports:
* string substitution
* url substitution

== perl ==
In <code>Indra::WebServices</code>, you can call <code>buildService($service_name)</code> to make a client to that service. The current implementation supports:
* string substitution
* query string substitution
* recursive substitution