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)

Description

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

Callback

AW_CALLBACK_CELL_RESULT

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

AW_CELL_COMBINE
AW_CELL_ITERATOR

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

AW_CELL_ITERATOR

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));
}

See also