Aw query

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 2.1
SDKbuild 13


int aw_query (int x_sector, int z_sector, int sequence[3][3])

Description

Queries for property in a three by three sector area.

Callback

AW_CALLBACK_QUERY

Notes

For a complete description of how to use aw_query, see Property.

Sequence is a 3x3 array of sector sequence numbers. These sequence numbers come from previous calls to aw_query and indicate the last time your application queried property in this zone. A zero sequence number indicates that you have no previous property for that sector. To get a complete property update for the entire zone, set all nine sequence numbers to zero.

A single call to aw_query may not be sufficient to update the entire area. After the call completes (or within the context of the AW_CALLBACK_QUERY callback) the value of the boolean attribute AW_QUERY_COMPLETE indicates whether aw_query should be called again to get more property. It may be necessary to call aw_query many times in order to get the contents of the entire three by three sector area.

Once AW_QUERY_COMPLETE is 1 (true), live update mode is enabled. This means your application may start receiving AW_EVENT_OBJECT_ADD and AW_EVENT_OBJECT_DELETE events if the surrounding property is being modified by other users.

For version 3.2 or later: Consider using aw_query_5x5 to query larger areas of property.

Arguments

x_sector
z_sector
sequence

Argument attributes

None

Return values

RC_SUCCESS (1) (2)
RC_NOT_INITIALIZED (1)
RC_NO_INSTANCE (1)
RC_NO_CONNECTION (1)
The connection to the world is down.
RC_QUERY_IN_PROGRESS (1)
RC_TIMEOUT

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

(2) Returned by the world server.

Returned attributes

AW_QUERY_COMPLETE

Usage

Count the number of objects in the 3x3 sector area around 500N 500W.

int sequence[3][3]; /* sequence[z][x] */
int object_count;
int query_x;
int query_z;

void handle_cell_begin (void)
{
  int cell_x = aw_int (AW_CELL_X);
  int cell_z = aw_int (AW_CELL_Z);
  int sector_x = aw_sector_from_cell (cell_x) - query_x;
  int sector_z = aw_sector_from_cell (cell_z) - query_z;
  
  if (sector_x < -1 || sector_x > 1 || sector_z < -1 || sector_z > 1)
    return;
  
  sequence[sector_z + 1][sector_x + 1] = aw_int (AW_CELL_SEQUENCE);
}

void handle_cell_object (void)
{
  object_count += 1;
}

int main (int argc, char *argv[])
{
  int rc;
  
  /* ... */
  
  aw_event_set (AW_EVENT_CELL_BEGIN, handle_cell_begin);
  aw_event_set (AW_EVENT_CELL_OBJECT, handle_cell_object);
  
  memset (sequence, 0, sizeof (sequence));
  
  query_x = aw_sector_from_cell (500); /* 500W */
  query_z = aw_sector_from_cell (500); /* 500N */
  
  for (;;)
  {
    rc = aw_query (query_x, query_z, sequence);
    if (rc != RC_SUCCESS)
    {
      printf ("Query failed (reason %d)\n", rc);
      return 1;
    }
    if (aw_bool (AW_QUERY_COMPLETE))
      break;
  }
  
  printf ("%d objects at sector (%d, %d)\n", object_count, query_x, query_z);
  
  /* ... */
  
  return 0;
}

This trick allows an application to immediately receive AW_EVENT_OBJECT_ADD and AW_EVENT_OBJECT_DELETE events for an area.

 int sequence[3][3];
 
 memset (sequence, -1, sizeof (sequence));
 aw_query (query_x, query_z, sequence);

See also