Aw object load

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 2.2
SDKbuild 14
Worldbuild 21


int aw_object_load (void)

Description

Adds an object to the world, overriding default owner and timestamp attributes.

Callback

AW_CALLBACK_OBJECT_RESULT

Notes

This method is similar to aw_object_add except that the additional attributes AW_OBJECT_OWNER and AW_OBJECT_BUILD_TIMESTAMP are also set. Since this allows the creation of an object that appears to have been built at any time by any user, use of aw_object_load is restricted to instances with the eminent domain right. All other attributes work the same as with aw_object_add.

If this method completes successfully then AW_OBJECT_NUMBER will contain an object number that was assigned automatically by the SDK.

If AW_CALLBACK_OBJECT_RESULT is installed then AW_OBJECT_NUMBER will be set during the callback to indicate which object the result is for. This can be useful in applications that issue multiple asynchronous building requests.

An object identifier AW_OBJECT_ID is received by the SDK when the object has been successfully added. It can be particularly useful when refering to already existing objects (see aw_object_change, aw_object_delete) and provides a somewhat faster access for the world server to it's database. It is a primary key of the world's cell database and so it does not change during update/change operations.

It is possible to tell which operation on the object a callback is for. This is done by setting AW_OBJECT_CALLBACK_REFERENCE before calling a method. The attribute will be set to the specified value when the call completes.

Arguments

None

Argument attributes

AW_OBJECT_OWNER
AW_OBJECT_BUILD_TIMESTAMP
If set to 0 (zero) then the world will use its current local time.
AW_OBJECT_TYPE
AW_OBJECT_X
AW_OBJECT_Y
AW_OBJECT_Z
AW_OBJECT_YAW
AW_OBJECT_TILT
AW_OBJECT_ROLL
AW_OBJECT_DESCRIPTION
AW_OBJECT_ACTION
AW_OBJECT_MODEL
AW_OBJECT_DATA
AW_OBJECT_CALLBACK_REFERENCE

Return values

RC_SUCCESS (1) (2)
If the object was built, or out of bounds.
RC_NOT_INITIALIZED (1)
RC_NO_INSTANCE (1)
RC_NO_CONNECTION (1)
The connection to the world is down.
RC_OBJECT_TYPE_INVALID (1)
RC_UNAUTHORIZED (2)
Only world server administration instances or those that have build capability (i.e. aw_bool (AW_WORLD_BUILD_CAPABILITY) returns 1) and eminent domain capability (i.e. aw_bool (AW_WORLD_EMINENT_DOMAIN_CAPABILITY) returns 1) may use this method.
RC_ELEMENT_ALREADY_EXISTS (2)
RC_TOO_MANY_BYTES (2)
It would exceed the cell limit (see AW_WORLD_CELL_LIMIT).
RC_DATABASE_ERROR (2)
RC_UNABLE_TO_SET_SEQUENCE (2)
Unable to increment sequence number of the sector.

(1) Possible return values when a callback is installed.

(2) Returned by the world server.

Returned attributes

AW_OBJECT_NUMBER
AW_OBJECT_ID
AW_OBJECT_CALLBACK_REFERENCE (1)
AW_CELL_X (1)
AW_CELL_Z (1)

(1) Added in SDK build 70.

Usage

int rc;

aw_int_set (AW_OBJECT_TYPE, AW_OBJECT_TYPE_V3); 
aw_int_set (AW_OBJECT_X, 0);
aw_int_set (AW_OBJECT_Y, 0);
aw_int_set (AW_OBJECT_Z, 0);
aw_int_set (AW_OBJECT_YAW, 0);
aw_int_set (AW_OBJECT_TILT, 0);
aw_int_set (AW_OBJECT_ROLL, 0);
aw_string_set (AW_OBJECT_MODEL, "street1.rwx");
aw_string_set (AW_OBJECT_DESCRIPTION, "Cornerstone");
aw_string_set (AW_OBJECT_ACTION, "create sound xyz.mid");
/* object to be owned by citizen #1 */
aw_int_set (AW_OBJECT_OWNER, 1); 
/* object to appear to have been built one week ago */
aw_int_set (AW_OBJECT_BUILD_TIMESTAMP, time (NULL) - (7 * 24 * 60 * 60)); 

rc = aw_object_load ();
if (rc != RC_SUCCESS)
   printf ("Unable to load object (reason %d)\n", rc);
else
   puts ("Object loaded");

See also