LSL Wiki Mirror 10-5-2006: llGiveInventoryList

llGiveInventoryList(key destination, string category, list inventory)

Give the list of named inventory items to the keyed agent (anywhere in the world--see notes below) or object (in the same simulator as the giver) destination. If the recipient is an agent, the user follows the normal procedure of accepting or denying the offer. The offered inventory is then placed in a folder named category in the recipient's inventory. If the recipient is an object, the same permissions apply as if the user dragged inventory onto the object by hand, i.e., if llAllowInventoryDrop has been called with TRUE, any other object can pass items to its inventory. If the recipient is an object, the category parameter is ignored--an object cannot contain folders in its inventory.

Notes:

llGiveInventoryList can only give items which the object owner has copy permission on. To determine whether or not the object owner has permission to give the objects specified, use llGetInventoryPermMask.
llGiveInventoryList does not consistently deliver the objects to an agent in another sim. From test results, it appears it will deliver only if the agent is a child agent to the sim with the giver or if the agent has been recently in the sim that the giver is. Do not rely on this functionality!
Group owned (deeded) objects are not permitted to give inventory. The function sends an error message to the "Script Errors/Warning" dialog: "Group owned objects cannot give inventory.".
If inventory is empty, or if the object contains none of the items specified in inventory, or if the object owner does not have copy permission on any of the items specified in inventory, llGiveInventoryList will cause the object to say "Unable to give inventory list: No items passed filter".
If inventory contains even one item that exists in the object and is copyable, llGiveInventoryList will give it, in the specified folder, but will not return an error. The items that could not be transferred will be ignored.
llGiveInventoryList delays the script for 3 seconds.

Example:

default
{
    on_rez(integer nevermind)
    {
        llSetText("Touch me to unpack\nyour new "+llGetObjectName()+".",<1,1,1>,1.0);
    }
    touch_start(integer total_number)
    {
// give all items in a prim to the owner, as folder (with the name of the prim)
// Ezhar Fairlight <efairlight@gmail.com>

// user-friendly additions by Mechanique Thirty (egypt@urnash.com)
// Script adjusted to run faster by Strife Onizuka.

        list        inventory;
        string      name;
        integer     num = llGetInventoryNumber(INVENTORY_ALL);
        string      text = llGetObjectName() + " is unpacking...\n";
        integer     i;
        
        for (i = 0; i < num; ++i) {
            name = llGetInventoryName(INVENTORY_ALL, i);
            if(llGetInventoryPermMask(name, MASK_NEXT) & PERM_COPY)
                inventory += name;
            else
                llOwnerSay("Cannot give asset \""+name+"\", owner lacks copy permission");
            llSetText(text + (string)((integer)(((i + 1.0) / num) * 100))+ "%", <1, 1, 1>, 1.0);
        }
        
        //chew off the end off the text message.
        text = llGetObjectName();
        
        //we don't want to give them this script
        i = llListFindList(inventory, [llGetScriptName()]);
        inventory = llDeleteSubList(inventory, i, i);
        
        if (llGetListLength(inventory) < 1) llSay(0, "No items to offer."); else
        {
            llGiveInventoryList(llGetOwner(), text, inventory);
            llSetText("All done!\nYou can delete this now!",<1,1,1>,1);
            llOwnerSay("Your new "+ text +" can be found in your inventory, in a folder called '"+ text +"'. Drag it onto your avatar to wear it!");
        }
    }
}

Q: Is there a way to give items into an existing folder or subfolder in a user's inventory?
A: No. The recipient will recieve the items in a new folder with the name specified in category within their inventory's root. There's no way to create a folder within their 'Clothing' folder, for example.

Q: So can I use llGiveInventoryList to give items that I can copy, but that have been set to prohibit other users from copying?
A: Yes. llGiveInventoryList will only prevent a script from giving an items if its owner does not have permissions copy permission. See llGetInventoryPermMask for more details on the difference between a "no-copy" item the creator can copy, and a no-copy item after it's been transferred to another user.

Q: What if the user I'm trying to give the objects to is offline?
A: If their offline buffer isn't full, and they don't have the object giving the items muted, they will be able to accept the transfer when they log on.

I seriously doubt if this is true. It gives me a "Cannot find destination" error -- FuRaz

Functions | Inventory