int aw_world_list (void)

DESCRIPTION

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

CALLBACK

AW_CALLBACK_WORLD_LIST

NOTES

Important: The behavior of aw_world_list has changed beginning with Build 20 of the SDK.  Applications running in the main AW universe that use this method will need to be modified to take this new behavior into account.

Applications can use aw_world_list to query the universe server for a list of all worlds running in the universe.  Previously (before build 20), the entire list would be returned in response to a single call to aw_world_list.   However, that mechanism could not handle a list of more than 750 worlds.   Since the number of worlds in the main AW universe is now well over 750, this mechanism has been changed beginning in build 20.  It now may require more than one call to aw_world_list in order to get the complete list of worlds.  Furthermore, subsequent calls to aw_world_list 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.

The world list is sent back to the application via the AW_EVENT_WORLD_INFO event.   Within the context of the AW_EVENT_WORLD_INFO handler, the following attributes will contain information about each world:

AW_WORLDLIST_NAME name of the world
AW_WORLDLIST_USERS number of users in the world
AW_WORLDLIST_STATUS current state of the world
AW_WORLDLIST_RATING rating of the world

The AW_WORLDLIST_STATUS attribute can have one of four values:

AW_WORLDSTATUS_PUBLIC world is open to the public
AW_WORLDSTATUS_PRIVATE world is closed to the public
AW_WORLDSTATUS_UNKNOWN world status is not yet known
AW_WORLDSTATUS_STOPPED world which was previously running is now stopped

When a call to aw_world_list completes (or within the AW_CALLBACK_WORLD_LIST callback for asynchronous mode) applications should now check the attribute AW_WORLDLIST_MORE. If this attribute is true, the entire world list has not been updated yet so aw_world_list should be called again.  if this attribute is false, the application is now up to date and no further calls are necessary.

EXAMPLE

/* 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;
  }
}

aw_event_set (AW_EVENT_WORLD_INFO, handle_world_info);
printf ("World\t Users\t Status\n\n");
do {
  int rc;
  if (rc = aw_world_list ()) {
    printf ("Unable to query world list (reason %d)\n", rc);
    break;
  }
} while (aw_bool (AW_WORLDLIST_MORE));

SEE ALSO

AW_EVENT_WORLD_INFO