Vp login: Difference between revisions

From Virtual Paradise Wiki
Jump to navigation Jump to search
Sleepy E (talk | contribs)
m Clean up, UTF-8 info
Sleepy E (talk | contribs)
m Characters => Bytes (since UTF-8 characters can take up multiple bytes), usage example
Line 6: Line 6:
   {{sdk parameter row|string|botname |Desired name for the bot to use}}
   {{sdk parameter row|string|botname |Desired name for the bot to use}}
|returncodes=
|returncodes=
   {{sdk return code row|string_too_long |If any of the given string parameters exceed 255 characters in length}}
   {{sdk return code row|string_too_long |If any of the given string parameters exceed 255 bytes in length (when using UTF-8 encoded characters they can each be multiple bytes long)}}
   {{sdk return code row|invalid_login  |The login credentials are incorrect}}
   {{sdk return code row|invalid_login  |The login credentials are incorrect}}
   {{sdk return code row|timeout        |Timeout}}
   {{sdk return code row|timeout        |Timeout}}
Line 18: Line 18:
* Strings may contain [https://wikipedia.org/wiki/UTF-8 UTF-8] encoded characters (e.g. "\xE2\x98\xAF" is the "Yin and Yang" symbol ☯).  
* Strings may contain [https://wikipedia.org/wiki/UTF-8 UTF-8] encoded characters (e.g. "\xE2\x98\xAF" is the "Yin and Yang" symbol ☯).  
|caveats=To log out from a universe, {{sdk method|destroy}} must be called which will also disconnect the bot from the world.
|caveats=To log out from a universe, {{sdk method|destroy}} must be called which will also disconnect the bot from the world.
|examples=
<syntaxhighlight lang="c">
int rc;
rc = vp_login(sdk, "myname", "mypassword", "botname");
if (rc)
  printf("Couldn't login (reason %d)\n", rc);
</syntaxhighlight>
|seealso=
|seealso=
* {{sdk callback|login}}
* {{sdk callback|login}}

Revision as of 20:04, 16 December 2016

Method call snippet vp_login(instance, username, password, botname);

Logs in a bot to the universe server, using the credentials of an existing account.

Parameters

These are the parameters that this method requires:

Parameter Usage
VPInstance
instance
Pointer to the instance this method call is intended for
string
username
Username of the account to log into
string
password
Password of the account to log into
string
botname
Desired name for the bot to use

Returns

This method returns a return code integer, which indicates whether the call was successful or errored for any reason:

Return code Cause
VP_RC_SUCCESS Successful call (for methods that have a registered callback, it only means the request has been sent)
VP_RC_STRING_TOO_LONG If any of the given string parameters exceed 255 bytes in length (when using UTF-8 encoded characters they can each be multiple bytes long)
VP_RC_INVALID_LOGIN The login credentials are incorrect
VP_RC_TIMEOUT Timeout
VP_RC_NOT_IN_UNIVERSE Bot is not currently connected to universe

The following attributes will be returned in VP_CALLBACK_LOGIN if the operation was successful:

Attribute Usage Also returned for
VP_MY_USER_ID User id of account used to log in

Behavior

  • If a VP_CALLBACK_LOGIN callback is set this function will return immediately and return the result using the callback, otherwise it will call vp_wait() in a loop until done.
  • When successfully logged in, bots will have square brackets around their name. For example, providing "Samantha" as the botname parameter will identify the bot as "[Samantha]".
  • The user ID of the account used to log in will be exposed to other users.
  • Strings may contain UTF-8 encoded characters (e.g. "\xE2\x98\xAF" is the "Yin and Yang" symbol ☯).

Caveats

To log out from a universe, vp_destroy() must be called which will also disconnect the bot from the world.

Examples

int rc;

rc = vp_login(sdk, "myname", "mypassword", "botname");
if (rc)
  printf("Couldn't login (reason %d)\n", rc);

See also