int aw_user_list (void)

DESCRIPTION

Requests a list of all users currently connected to the universe.

CALLBACK

AW_CALLBACK_USER_LIST

NOTES

This method is only accessible if the user list is enabled. Check AW_USERLIST_ENABLED to determine if the user list is enabled. For universe caretaker bots this method is always available and AW_EVENT_USER_INFO will also includes bots.

The user info is sent back to the application via the AW_EVENT_USER_INFO event.   Within the context of the AW_EVENT_USER_INFO handler, the following attributes will contain information about each user:

AW_USERLIST_NAME name of the user
AW_USERLIST_EMAIL* email address (tourists)
AW_USERLIST_WORLD current world
AW_USERLIST_CITIZEN citizen number
AW_USERLIST_PRIVILEGE* privilege number
AW_USERLIST_STATE online (1) / offline (0)
AW_USERLIST_ADDRESS* IP address
AW_USERLIST_ID unique number for updates
* Accessible to universe caretakers only.

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

A call to aw_user_list() must be repeated within an interval of less than 30 minutes, or otherwise logged off users would not have been recognized by the bot, because the universe database does not keep the information about logged off users longer than half an hour.

EXAMPLE

/* Print a list of all users currently connected to the universe. */
/* Note that this mechansim will only work once per login session.
   Subsequent calls to aw_user_list() will only return the changes
   since the previous call.  A proper implementation requires the
   application to maintain its own copy of the user list, and to
   update its list in response to the changes returned.
   AW_USERLIST_ID should be checked to update the correct user as
   multiple bots may be connected using the same name */
void handle_user_info (void)
{
  printf ("%s: %s\n", aw_string (AW_USERLIST_NAME),
    aw_int (AW_USERLIST_STATE) ? "Online" : "Offline");
}

aw_event_set (AW_EVENT_USER_INFO, handle_user_info);
do {
  int rc;
  if (rc = aw_user_list ()) {
    printf ("Unable to query user list (reason %d)\n", rc);
    break;
  }
} while (aw_bool (AW_USERLIST_MORE));

SEE ALSO

AW_EVENT_USER_INFO