Aw user list
| Minimum requirements | ||
|---|---|---|
| Added in version 3.5 | ||
| SDK | build 37 | |
| Browser | build 502 | |
int aw_user_list (void)
Description
Requests a list of all users currently connected to the universe.
Callback
Notes
Applications can use this method to query the universe server for a list of all users logged into the universe. It may require more than one call to get the complete list of users. 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 user list, and to update it in response to any changes that are returned.
User list updates are sent back to the application via AW_EVENT_USER_INFO events.
This method is only accessible if the user list is enabled (i.e. userlist=1 in the [misc] section of universe.ini). Applications should check AW_UNIVERSE_USER_LIST_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 be received for bots.
The user list in the universe server has at most one entry per each logged in user and any number of entries for logged off users (i.e. aw_int (AW_USERLIST_STATE) == 0). It is sorted by when the state of each user changed. Users that have not changed their state for a long time will appear at the start of the list.
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. The very first call to aw_user_list will not return updates for any logged off users.
There is no recommended interval between calls to aw_user_list, but browsers call it every 5 seconds.
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_USERLIST_MORE
- If this attribute is 1 (true) then the entire user list has not been updated yet so aw_user_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 users currently connected to the universe.
Note that this example 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");
}
int main (int argc, char *argv[])
{
/* ... */
aw_event_set (AW_EVENT_USER_INFO, handle_user_info);
do
{
int rc;
rc = aw_user_list ();
if (rc != RC_SUCCESS)
{
printf ("Unable to query user list (reason %d)\n", rc);
break;
}
}
while (aw_bool (AW_USERLIST_MORE));
/* ... */
}