llGiveAgentInventory

function

Function syntax

integer llGiveAgentInventory(

key agent,// UUID of the target agent in the same region.
string folder,// Name of the destination folder to be created
list items,// The names of the items in the prim's inventory to transfer.
list options// A list of options to configure the inventory transfer.

);

Returns: integer
Delay: 3 s
Energy: 10

Gives the specified inventory items to the agent as a new folder named folder, as permitted by the permissions system. Customizes the transfer using options.

Gives inventory items to agent, creating a new folder to put them in.

integer result = llGiveAgentInventory(NULL_KEY, "", [], []);

Specification

From the LSL definitions: GiveAgentInventoryParam (rule, then its arguments)

TRANSFER_DEST  // Inventory option specifying the destination root folder to transfer inventory into.TRANSFER_FLAGS  // Inventory parameter specifying flags to control the behavior of inventory transfers.

The target must be an avatar in the same region as the sending object, or must have recently been in the region.
Places the inventory items in a newly created folder in the avatar’s inventory (even if there is a folder by the same name, a new one is created).
If a path of root folders has been specified, the function will ensure that those folders exist but will not recreate them if they already exist.

Transfer Options

Flags		Parameters	Description
`TRANSFER_DEST`	0	`[ TRANSFER_DEST, string ]`	Sets a root path that will be used as the parent for folder. If the root path does not exist it will be created. If it already exists in the target inventory it will be reused. Path folders are separated by a ”\|” character. The path may have have up to 4 folders in it. Note that transfers to certain system folders (such as ‘Trash’) are disallowed. Examples: “Objects\|Vehicles\|My Motorcycle Company” “Clothing\|Shoes\|Breedables” “My Store\|Home & Garden\|“
`TRANSFER_FLAGS`	1	`[ TRANSFER_FLAGS, integer ]`	There are no flags defined at this time.

Transfer Errors

Constant		Description
`TRANSFER_OK`	0	No error detected, inventory transferred
`TRANSFER_BAD_OPTS`	-1	A bad option was passed in the options list.
`TRANSFER_NO_TARGET`	-2	Could not find the receiving agent in the current region.
`TRANSFER_THROTTLE`	-3	Transfer rate exceeded the inventory transfer throttle.
`TRANSFER_NO_ITEMS`	-4	The list of items was empty or contained only non-transferable items.
`TRANSFER_BAD_ROOT`	-5	The root path specified in `TRANSFER_DEST` contained an invalid directory or was reduced to nothing.
`TRANSFER_NO_PERMS`	-6	The object does not have transfer permissions.
`TRANSFER_NO_ATTACHMENT`	-7	Can not transfer ownership of an attached object.

Caveats

Any no-copy items in inventory will be excluded from transfer.
Any no-transfer items in inventory will be excluded from transfer if agent is not the script owner.

Examples

In this example, the object inventory needs to contain two objects named Item 1 and Item 2. The destination folder will be named Destination Folder and will be created under the main folder Objects, in the sub-folder Subfolder. If Subfolder does not exist, it will be created.

If the object gets touched for a second time, the sub-folder Subfolder will not be duplicated, however the destination folder Destination Folder will be duplicated.

If Item 1 and/or Item 2 do not exist, the transfer will silently fail partially or completely.

default
{
    touch_start(integer total_number)
    {
        llGiveAgentInventory(llDetectedKey(0), "Destination Folder", ["Item 1","Item 2"], [TRANSFER_DEST, "Objects|Subfolder"] );
    }
}