Aw create

From ActiveWiki
Jump to: navigation, search


Minimum requirements
Added in version 2.1
SDKbuild 13


int aw_create (char *domain, int port, void **instance)

Description

Creates a bot instance associated with the specified universe server. If you desire to create several bots, call this multiple times, once for each instance of the bot.

Callback

AW_CALLBACK_CREATE

Notes

If the call is successful then the created instance will be selected as current. That is, aw_instance returns the same pointer as would be passed through the instance pointer.

The universe server must be running version 2.1 or later to accept connections from SDK applications.

Asychronous operation

It will time out after 60 seconds of waiting for the connection to be established and the handshake to succeed. There will not be any automatic reconnection attempt. The bot needs to call this method again.

Keep in mind that the domain name resolution will block even though it is an asychronous call. That is, unless domain was an IP address in dotted quad form.

Blocking operation

The connection attempt will time out after 18 seconds of waiting. If the connection is successfully established then it will wait an additional 18 seconds for the handshake to succeed. Worst case is that it will block for a total of 36 seconds. Plus an additional 20 seconds (so it does not "hammer" the server) before a reconnection is attempted.

Arguments

domain
May be specified as NULL to take the default of "auth.activeworlds.com". It can also be set to IP addresses in dotted quad form like "192.168.0.1".
port
May be specified as 0 to take the default port. The default is port 6670 for v4.1 or newer, and port 5670 for v3.6 or older.
instance
Pointer to where an instance pointer is returned. May be specified as NULL if it is not desired.

Argument attributes

None

Return values

RC_SUCCESS (1)
RC_NOT_INITIALIZED (1)
RC_CANT_RESOLVE_UNIVERSE_HOST (1)
WSAECONNRESET (1) (2)
Connection was reset by universe.
RC_TIMEOUT (2)
Connection attempt timed out, connection was reset by universe, or handshake timed out.
RC_NO_CONNECTION (2)
Connection was reset by universe while waiting for handshake to succeed.

(1) Possible return values when a callback is installed.

(2) Automatic reconnection attempt in 20 seconds. Provided that aw_wait is called.

Returned attributes

None

Usage

int rc;

rc = aw_create ("", 0, NULL); 
if (rc != RC_SUCCESS)
{
  printf ("Unable to create instance (reason %d)\n", rc);
  exit (1);
}

See also