LlReturnObjectsByID

Wiki description

If the script is owned by an agent, PERMISSION_RETURN_OBJECTS may be granted by the owner. If the script is owned by a group, this permission may be granted by an agent belonging to the group's "Owners" role.

Function notes

If the return value is negative, it represents an error flag.

Return value notes

Returns an integer that is the number of objects successfully returned to their owners or an ERR_* flag.

Specification

Script Owner and Scope

If the script is owned by an estate owner or manager, this function works for objects located on any parcel in the region. Otherwise, the script can return objects located over land owned by the owner of the script.

As a security measure, parcel owner, estate owner, and estate managers can not have their objects returned by this method, except when the object returns itself.

Throttle

Throttled at max parcel land impact capacity region-wide per hour.

ERR_GENERIC integer -1 m=3 c=A nebulous and inexplicable error, nothing is known about it.

ERR_PARCEL_PERMISSIONS integer -2 m=3 c=Permission lacked to perform task on specified parcel.

ERR_MALFORMED_PARAMS integer -3 m=3 c=Parameters are malformed.

ERR_RUNTIME_PERMISSIONS integer -4 m=3 c=Script lacks the runtime permission to perform the requested task.

ERR_THROTTLED integer -5 m=3 c=Task has been throttled. Try again later.

Error Flags		Description

Caveats

Objects owned by other groups will be returned to their previous owner if the object is transferable, deleted otherwise.

Examples

key owner;

// list of objects to return
list objects_to_return = [
    "929f26d8-b225-5f6a-a26a-eeda27c31416",
    "f0abe779-1989-6be4-d73c-dcb48b4313cf",
    "bad9903-139f-2217-81f3-e61884540df6"
];

default
{
    state_entry()
    {
        llRequestPermissions(llGetOwner(),PERMISSION_RETURN_OBJECTS);
    }
    
    run_time_permissions(integer p)
    {
        if (p & PERMISSION_RETURN_OBJECTS)
        {
            llSetText("Touch me to return the list of objects defined in this script",<1,1,0>,1);
        }
    }

    touch_start(integer total_number)
    {
        if ((llGetPermissions() & PERMISSION_RETURN_OBJECTS) == 0)
        {
            llOwnerSay("Requesting permission to return objects.");
            llRequestPermissions(llGetOwner(),PERMISSION_RETURN_OBJECTS);
        }
        else
        {
            list found_objects = [];
            integer n = llGetListLength(objects_to_return);
            while(--n >= 0)
            {
                key object = llList2Key(objects_to_return, n);
                string pos = llList2String(llGetObjectDetails(object, [OBJECT_POS]), 0);
                if(pos == "" )
                {
                    llOwnerSay( "Object in return list " + (string)object + " not found - skipping.");
                }
                else
                {
                    llOwnerSay("Adding object " + (string)object + " at " + (string)pos + " to return list.");
                    found_objects += [object];
                }
            }
            llOwnerSay("Found " + (string)llGetListLength(found_objects) + " objects to return.");
            integer result = llReturnObjectsByID(found_objects);
            if(result >= 0)
            {
                llOwnerSay("Returned " + (string)result + " objects.");
            }
            else
            {
                llOwnerSay("llReturnObjectsByID returned error code " + (string)result
                    + " - see https://wiki.secondlife.com/wiki/LlReturnObjectsByID for meaning");
            }
        }
    }
}

History

Date of Release 18/06/2013

Shared wiki helpers

The original page also injects shared parameter notes, caveats or issue information through these helpers. Their conditional MediaWiki logic is not reproduced here; inspect the preserved helper source for additional material.

Template:Issues/SVC-6281

Original shared helper source (conditional wiki logic is not evaluated)

{{Issues|SVC-6281|Shared group inventory|type=fs|fc=1}}

Template:LSL Function/permission