LlGiveAgentInventory

Wiki description

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

Specification

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"] );
    }
}