Aw query
| Minimum requirements | ||
|---|---|---|
| Added in version 2.1 | ||
| SDK | build 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
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
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);