Aw cell next

From ActiveWiki
Jump to: navigation, search

Minimum requirements
Added in version 3.1
SDKbuild 18
Worldbuild 28

int aw_cell_next (void)


Returns the contents of the next cell in an enumeration sequence.




This method provides a simple mechanism for enumerating all of the objects in a world. Applications wishing to query all objects in a world should set AW_CELL_ITERATOR to 0 and then call aw_cell_next repeatedly until it fails.

Each call to aw_cell_next returns the contents of one cell. The individual objects are returned via the AW_EVENT_CELL_OBJECT event.

For SDK build 21 and later, and world server build 32 and later: This method supports a boolean attribute AW_CELL_COMBINE. Setting this attribute to 1 (true) will cause multiple cells to be sent back in response to a single call to aw_cell_next (the event AW_EVENT_CELL_OBJECT will be triggered once for each cell sent back.) For applications that wish to enumerate all cells in a world, setting AW_CELL_COMBINE to true can significantly increase the performance of this operation. The actual number of cells sent back per call depends on the amount of data in each cell.

For a complete description of cells and property in Active Worlds, see Property.



Argument attributes


Return values

RC_SUCCESS (1) (2)
No more cells left to enumerate.

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

(2) Returned by the world server.

Returned attributes



void handle_cell_object (void)
  printf ("%s\n", aw_string (AW_OBJECT_MODEL));

void list_objects (void)
  /* list all objects in the world */
  aw_callback_set (AW_CALLBACK_CELL_RESULT, NULL);
  aw_event_set (AW_EVENT_CELL_OBJECT, handle_cell_object);
  aw_int_set (AW_CELL_ITERATOR, 0);
  aw_bool_set (AW_CELL_COMBINE, 1);
  while (!aw_cell_next ()
    && aw_int (AW_CELL_ITERATOR) != -1);

It is also possible to specify the exact cell to query using aw_cell_next using a simple C++ union:

union cell_iterator
    int iterator;
        short z;
        short x;
    } cell;

Then doing as such:

cell_iterator it;

void query_cell (short cell_x, short cell_z)
    it.cell.x = cell_x;
    it.cell.z = cell_z;
    aw_int_set (AW_CELL_ITERATOR, it.iterator);
    aw_cell_next ();

If the cell is empty then objects in the next populated cell would be returned:

void list_objects (void)
  /* make sure the object is in the queried cell */
  if (aw_int (AW_OBJECT_X) / 1000 != it.cell.x)
  if (aw_int (AW_OBJECT_Z) / 1000 != it.cell.z)
  printf ("%s\n", aw_string (AW_OBJECT_MODEL));

See also