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

Callback

AW_CALLBACK_CELL_RESULT

Notes

This method is new in Active Worlds 3.1 and requires at least SDK build 18 and world server build 28. 

aw_cell_next provide 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.

Beginning with Active Worlds 3.2 (SDK build 21 and world server build 33), this method supports a new boolean attribute AW_CELL_COMBINE. Setting this attribute to 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.

Example

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, TRUE);
  while (!aw_cell_next ())
    ;

}

See Also

aw_object_add
aw_object_change
aw_object_delete
aw_object_load
aw_query