Vp login: Difference between revisions
Jump to navigation
Jump to search
m Clean up, UTF-8 info |
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 | {{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 callvp_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);