AW EVENT WORLD DISCONNECT
| Minimum requirements | ||
|---|---|---|
| Added in version 2.1 | ||
| SDK | build 13 | |
AW_EVENT_WORLD_DISCONNECT
Description
Connection to a world has been severed.
Notes
This event signals that the connection to the world server has been severed. Which means that no methods that act on a world will work until the connection has been reestablished. The attribute AW_DISCONNECT_REASON contains a reason code indicating the reason for the disconnection.
Possible values for AW_DISCONNECT_REASON in the context of this event include:
Note that subscribing to this event does not alter the behaviour of the SDK in any way.
Automatic reconnection
If the reason code is not RC_EJECTED or RC_NOT_WELCOME then the SDK will automatically reconnect to the world after 30 seconds. The reconnection attempt could in turn fail and trigger this event again. There could be yet another reconnection attempt, and so forth.
For the reason codes RC_EJECTED and RC_NOT_WELCOME it will be up to the bot to decide if it should reconnect using aw_enter. f
Repercussions for avatar events
If the bot is tracking a session table using the AW_EVENT_AVATAR_ADD, AW_EVENT_AVATAR_CHANGE, and AW_EVENT_AVATAR_DELETE events, the table must be cleared upon a world disconnect, because no AW_EVENT_AVATAR_DELETE events are triggered upon a world disconnect. When the bot automatically reconnects to the world, it may receive AW_EVENT_AVATAR_ADD events for the same avatars it was previously tracking, if they still exist. If AW_AVATAR_SESSION is used as the key to a session-tracking hashtable, a duplicate key exception will occur.
Repercussions for object events
The bot's knowledge of property is affected by world disconnects as well. If the bot was in live update or global mode with the AW_EVENT_OBJECT_ADD and AW_EVENT_OBJECT_DELETE events handled, then the bot will have "missed" objects that were added, deleted, or changed during the time while the bot was disconnected. Unfortunately, the only reliable solution to keep the cache current is to clear it after a disconnect. Since the consequences of requerying the entire world when in global mode can be severe, world disconnects need to be avoided at all costs. One should also note that, after a world disconnect, aw_query must be re-called to re-initiate live update mode.
- Special note for one-zone object tracking: The bot can determine which objects were added or changed by re-calling aw_query for the zone with the sequence array leftover from the initial query. This method conserves bandwidth because only the objects added or modified since the last query will be returned. However, this "cheap" method will not issue any events for objects that were deleted in the interval, and thus the cache will likely retain stale objects that no longer exist.
Attributes
Usage
void handle_world_disconnect (void)
{
int rc;
rc = aw_int (AW_DISCONNECT_REASON);
switch (rc)
{
case RC_CONNECTION_LOST:
printf ("I've lost my connection to the world.\n");
break;
case RC_EJECTED:
printf ("I've been ejected!\n");
break;
case RC_NOT_WELCOME:
printf ("I'm not allowed in this world.\n");
break;
default:
printf ("Connection to world lost (reason %d)\n", rc);
break;
}
}
aw_event_set (AW_EVENT_WORLD_DISCONNECT, handle_world_disconnect);