Aw world list

Minimum requirements
Added in version 2.1
SDK	build 13

int aw_world_list (void)

Description

Requests a list of all worlds currently running in the universe.

Callback

AW_CALLBACK_WORLD_LIST

Notes

Applications can use this method to query the universe server for a list of all worlds running in the universe. It may require more than one call to get the complete list of worlds. Furthermore, subsequent calls will only return the changes since the previous call; the entire list is only returned once per login session, on the first call or series of calls. Meaning that applications are required to maintain their own copy of the world list, and to update it in response to any changes that are returned.

World list updates are sent back to the application via AW_EVENT_WORLD_INFO events.

The world list in the universe server has at most one entry per each started world and any number of entries for stopped worlds (i.e. aw_int (AW_WORLDLIST_STATUS) == AW_WORLDSTATUS_STOPPED). It is sorted by when the state of each world changed. Worlds that have not changed their state for a long time will appear at the start of the list.

A call to aw_world_list must be repeated within an interval of less than 24 hours, or otherwise stopped worlds would not have been recognized by the bot, because the universe database does not keep the information about stopped worlds longer than twenty-four hours. The very first call to aw_world_list will not return updates for stopped worlds.

There is no recommended interval between calls to aw_world_list, but browsers call it every 30 seconds.

For SDK build 20 and later: The behavior of aw_world_list has changed beginning with build 20 of the SDK. Old applications that use this method will need to be modified to take this new behavior into account. Previously, the entire list would be returned in response to a single call. However, that mechanism could not handle a list of more than 750 worlds. This mechanism was changed since the number of worlds in the main AW universe exceeded 750. It now may require more than one call to get the complete list of worlds.

Arguments

None

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 universe is down.

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

(2) Returned by the universe server.

Returned attributes

AW_WORLDLIST_MORE

If this attribute is 1 (true) then the entire world list has not been updated yet so aw_world_list should be called again. If this attribute is 0 (false) then the application is now up to date and no further calls are necessary.

Usage

Print a list of all worlds currently running in the universe.

/* Note that this mechansim will only work once per login session.
   Subsequent calls to aw_world_list() will only return the changes
   since the previous call. A proper implementation requires the
   application to maintain its own copy of the world list, and to
   update its list in response to the changes returned. */

void handle_world_info (void)
{
  printf ("%s\t %d\t ", aw_string (AW_WORLDLIST_NAME), aw_int (AW_WORLDLIST_USERS));
  
  switch (aw_int (AW_WORLDLIST_STATUS))
  {
    case AW_WORLDSTATUS_PUBLIC:
      printf ("Public\n");
      break;
    case AW_WORLDSTATUS_PRIVATE:
      printf ("Private\n");
      break;
    case AW_WORLDSTATUS_STOPPED:
      /* do nothing */
      break;
    default:
      printf ("Unknown\n");
      break;
  }
}

int main (int argc, char *argv[])
{ 
  /* ... */
  
  aw_event_set (AW_EVENT_WORLD_INFO, handle_world_info);
  
  printf ("World\t Users\t Status\n\n");
  do
  {
    int rc;
    
    rc = aw_world_list ();
    if (rc != RC_SUCCESS)
    {
      printf ("Unable to query world list (reason %d)\n", rc);
      break;
    }
  }
  while (aw_bool (AW_WORLDLIST_MORE));
  
  /* ... */
}

See also

• AW_EVENT_WORLD_INFO