Aw destroy

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 2.1
SDKbuild 13


int aw_destroy (void)

Description

Destroys the current bot instance.

Callback

None (returns immediately)

Notes

This method destroys the current bot instance (i.e. the one returned by aw_instance). In a multi-instance application, call aw_instance_set first to set the instance to be destroyed.

A destroyed instance is only flagged as having been destroyed. The SDK will stop processing events, callbacks and method calls for it. Any resources allocated to it will be deallocated in aw_wait. Which means it is safe to call aw_destroy from within the context of an event handler or callback.

The most recently created instance will be set as the new current instance. If the destroyed instance is the most recently created then it will set the second most recent. If none exists then it will be set to NULL. It does not care if the new current instance has previously been destroyed.

Note that this method will immediately close any connection to a world/universe server. Nonblocking method calls placed shortly before calling it are not guaranteed to affect the server (e.g. aw_say ("I'm going!")). Such methods that lack a callback have no way of knowing when they have affected the server (within the heartbeat timeout).

For version 3.6 and earlier: This method will immediately deallocate all data structures related to the current instance. For this reason, it must only be called from the main event loop of an application. Do not call aw_destroy within the context of any event handler or callback.

Arguments

None

Argument attributes

None

Return values

RC_SUCCESS
RC_NO_INSTANCE

Returned attributes

None

Usage

void handle_chat (void)
{
  /* destroy the bot instance when someone tells it to quit */
  if (strcmp (aw_string (AW_CHAT_MESSAGE), "quit") == 0)
  {
    /* immediately stop processing events and callbacks for the instance */
    aw_destroy ();
    /* ... */
  }
}

See also