Aw cell next
| Minimum requirements | ||
|---|---|---|
| Added in version 3.1 | ||
| SDK | build 18 | |
| World | build 28 | |
int aw_cell_next (void)
Description
Returns the contents of the next cell in an enumeration sequence.
Callback
Notes
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.
Arguments
None
Argument attributes
Return values
- RC_SUCCESS (1) (2)
- RC_NOT_INITIALIZED (1)
- RC_NO_INSTANCE (1)
- RC_NO_CONNECTION (1)
- RC_NO_SUCH_CELL (2)
- No more cells left to enumerate.
(1) Possible return values when a callback is installed.
(2) Returned by the world server.
Returned attributes
Usage
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;
struct
{
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)
return;
if (aw_int (AW_OBJECT_Z) / 1000 != it.cell.z)
return;
printf ("%s\n", aw_string (AW_OBJECT_MODEL));
}