User:Jacek Antonelli/Plugin System/Accessing Properties

About Properties
Each entity type (avatar, texture, prim, etc.) has properties, values that can be accessed by name. For example, a prim has a position, scale, rotation, shape, face textures, and other properties.

Since all entity types have properties, a single shared set of three requests are used for manipulating those properties for any entity type:


 * ListProps: Retrieve a list of what properties an entity type has.
 * GetProps: Retrieve the values of one or more properties of an entity.
 * SetProps: Change the values of one or more properties of an entity.

ListProps
["$request_id", "ListProps", "$entity_type", [ "$prop1", "$prop2", ... ] ]

is the name of the entity type to query, as specified in the PVPI.

The final element is an optional array of property names to check. If this is omitted, the full catalogue of all properties is retrieved. If provided, only properties which are both in the array and supported by the entity type are returned. (This is to allow plugins to check whether the implementation supports certain optional or extra properties.)

If the given entity type does not exist, the viewer responds with an error indicating such.

Otherwise, if all goes well, the viewer responds with:

["$request_id", "ListProps.Response", "$entity_type", [ "$prop1", "$prop2", ... ] ]

GetProps
["$request_id", "GetProps", "$entity_id", [ "$prop1", "$prop2", ... ] ]

is a string identifying the specific entity in question, as described in the section.

The final element is an optional array of property names to retrieve the values of. If this is omitted, the values of all properties of the entity are retrieved. If provided, only the values of those given properties are retrieved. The order that properties are given in the array does not have any effect on the result.

If the requested entity did not exist, the viewer responds with an error indicating such.

If any of the properties could not be read (e.g. the user does not have permission, or in case of server failure), the viewer does not return any values, but instead responds with an error indicating which properties could not be read, and why.

Otherwise, if all goes well, the viewer responds with the following:

["$request_id", "GetProps.Response", "$entity_id", { "$prop1" : $value1, "$prop2" : $value2, ... } ]

is the same as in the request.

and  are the names and corresponding values of the requested properties. The order of name:value pairs does not matter, and does not need to match the order of properites in the request.

If any of the requested properties were not supported by the entity, the value in the response is.

SetProps
["$request_id", "SetProps", "$entity_id", { "$prop1" : $value1, "$prop2" : $value2, ... } ]

has the same meaning as in GetProps.

The final element is a struct of names and new values of properties that should be changed.

Properties which are not included in the struct will not be modified by this request.

If any of the given properties is not supported by the entity, that name:value pair is entirely ignored.

If any property is supported by the entity, but the given value is invalid (e.g. wrong type, out of bounds, contradicts related properties), no changes are made to the object, and the viewer responds with an error indicating which properties were invalid, and why.

If any property cannot be modified for some reason (e.g. for objects not owned by the user, no-mod inventory items, or in case of server failure), no changes are made to the object, and the viewer responds with an error indicating which properties couldn't be modified, and why.

Otherwise, if all goes well, the viewer responds with the following, to let the plugin know that the request was received and succeeded:

["$request_id" "SetProps.Response", "$entity_id" ]