Aw create
| Minimum requirements | ||
|---|---|---|
| Added in version 2.1 | ||
| SDK | build 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
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); }