Base Module

Back To Top

Base Module

The Base Module in the GDK Extension provides a set of functions to handle the user/account selection for the player.

Base Functions

The following functions are given for working with user accounts:

• xboxone_show_account_picker
• xboxone_get_token_and_signature
• xboxone_get_activating_user
• xboxone_get_user_count
• xboxone_get_user

---

Back To Top

xboxone_get_activating_user

With this function you can retrieve the user ID pointer for the user that launched the game.

ℹ️ NOTE

The returned user ID may not always be accurate as the active account can be changed at any time and this value will always return the user account that was active when the game launched.

Syntax:

xboxone_get_activating_user();

Returns:

Pointer (The user ID pointer)

Example:

global.main_user = xboxone_get_activating_user();

In the code above we get the ID of the user responsible for launching the game and store it inside a global variable (global.main_user).

---

Back To Top

xboxone_get_token_and_signature

This function retrieves xtokens and signatures for web requests. This function returns -1 if it fails and 0 if succeeds to request the token/signature. This is an asynchronous function that will trigger the System Async Event when the task is finished.

Syntax:

xboxone_get_token_and_signature(user, url, method, json_headers, body, force_refresh);

Argument	Type	Description
index	int64	The user's unique identifier
url	string	The URL for the web request
method	string	The method type for the web request (http method)
json_headers	string	Headers for the web request (json formated string)
body	string/buffer ID	A buffer that contains the body of the web request (also accepts strings)
force_refresh	bool	Whether a refresh should be forced or not

Returns:

real

Triggers:

Asynchronous System Event

Key	Type	Description
event_type	string	The string "tokenandsignature_result"
status	real	Returns -1 if request failed, 0 if succeeded
token	string	The token for the provided user
signature	string	The signature of the http request

Example:

var headers = ds_map_create();
headers[?"this"] = "that";
headers[?"woot"] = "this";

var body = buffer_create(1, buffer_grow, 1);
buffer_write(body, buffer_string, "hello");

var url = "https://profile.xboxlive.com/users/me/profile/settings?settings=GameDisplayName";
var request_method = "GET";

if (xboxone_get_token_and_signature(xboxone_get_activating_user(), url, request_method, json_encode(headers), body, true) < 0) {
    show_message("Token query failed");
}
else {
    show_debug_message("Requested token.");
}

buffer_delete(body);
ds_map_destroy(headers);    

In the code above we get perform a token request for the activating used (xboxone_get_activating_user), this function behaves similarly to to a simple http_request in the way you are required to provide a URL, http method (GET, POST, ...), the headers to be used in the request and the body that can be either in buffer or string format. We can catch the function callback inside the System Async Event, following the code below.

// Early exit if event type doesn't match
if (async_load[?"event_type"] != "tokenandsignature_result") exit

// Validate status
var status = async_load[?"status"];
if (status == 0) {

    // Success
    show_message("Token query succeeded. See output.");
    show_debug_message("The token of the user that opened the app: " + async_load[?"token"]);
    if (ds_map_exists(async_load, "signature")) {
        show_debug_message("The signature of the http request: " + async_load[?"signature"]);
    }
}
else {
    // Failure
    show_message("Token query failed");
}

---

Back To Top

xboxone_get_user

With this function you can retrieve the user ID pointer for the indexed user. If the user does not exist, the function will return the constant pointer_null instead. You can find the number of users currently logged in with the function xboxone_get_user_count.

Syntax:

xboxone_get_user(index);

Argument	Type	Description
index	integer	The index to get the user ID from.

Returns:

Pointer (The user ID pointer)

Example:

for (var i = 0; i < xboxone_get_user_count(); i++)
  {
      user_id[i] = xboxone_get_user(i);
    }

In the code above we loop through all the users currently singed in (using the [xboxone_get_user_count](#xboxone_get_user_count) function) and store their user IDs into an array (user_id).

---

Back To Top

xboxone_get_user_count

With this function you can find the total number of users currently signed in to the system. The returned value will be an integer.

Syntax:

xboxone_get_user_count();

Returns:

Real (The total number of users currently signed in to the system)

Example:

for (var i = 0; i < xboxone_get_user_count(); i++)
  {
      user_id[i] = xboxone_get_user(i);
    }

In the code above we loop through all the users currently singed in to the system and store their user IDs into an array (using the xboxone_get_user function).

---

Back To Top

xboxone_show_account_picker

This function launches the system's account picker for the specified pad ID, where selecting an account will associate it with the specified pad. The guests argument is either true or false – if false is specified no guest accounts can be selected, while true allows guest accounts.

⚠️ IMPORTANT

The argument pad_id is ignored by the GDK Extension and is only used when the function is called on console.

This is an asynchronous function that will trigger the Async Dialog event when the task is finished.

Syntax:

xboxone_show_account_picker(pad_id, guests);

Argument	Type	Description
pad_id	real	⚠️ UNUSED Pad ID of the user to select the account for
guests	boolean	Whether we should allow guest accounts

Returns:

N/A

Triggers:

Asynchronous Dialog Event

Key	Type	Description
type	string	The string "xboxone_accountpicker"
succeeded	boolean	Returns true if an account was select, false if cancelled
user	pointer	The store ID used when acquiring the license.

Example:

xboxone_show_account_picker(0, false);

In the code above we first request for an account selection dialog that allows no guest accounts. The function callback can be caught inside an Async Dialog event, following the code below.

if (async_load[? "type"] == "xboxone_accountpicker")
{
    if (async_load[? "succeeded"] == false)
    {
        show_debug_message("User cancelled account selection!");
    }
}

The code above matches the response against the correct event id , providing a failure message if "succeeded" is false.

---