XPersistentLocalStorageGetPathSize

Article
06/22/2023

Returns the length, in characters, of the path to the persistent local storage (PLS).

Syntax

HRESULT XPersistentLocalStorageGetPathSize(  
         size_t* pathSize  
)

Parameters

pathSize _Out_
Type: size_t*

The length, in characters, of the PLS path.

Return value

Type: HRESULT

Returns S_OK if successful; otherwise, returns an error code. For a list of error codes, see Error Codes.

Remarks

Note

This function isn't safe to call on a time-sensitive thread. For more information, see Time-sensitive threads.

The return value of this function is used for the pathSize parameter of the XPersistentLocalStorageGetPath function to return the game-specific PLS path on the device. For more information about PLS, see Local Storage.

When calling the XPersistentLocalStorageGetPath function, allocate at least as many characters for the path parameter of XPersistentLocalStorageGetPath as the number specified in the value returned in the pathSize parameter of this function; failure to do so will cause an error.

The following example illustrates how to use the XPersistentLocalStorageGetPathSize and XPersistentLocalStorageGetPath functions to get the PLS path for your game.

// Confirm that all of the features needed to run asynchronous tasks on 
// task queues are available.
LPCSTR Game::CheckPLSPath()
{
    // Confirm the length of the path to the local storage folder.
    LPCSTR returnPath = "";
    size_t pathSize;
    if (SUCCEEDED(XPersistentLocalStorageGetPathSize(&pathSize)))
    {
        char * path = new char[pathSize];
        size_t * pathUsed = new size_t;
        if (path != nullptr)
        {
            // Get the path to the local storage folder.
            if (SUCCEEDED(XPersistentLocalStorageGetPath(pathSize, path, pathUsed))) 
            {
                // Just to be safe, copy the bytes used in the buffer 
                // to a separate string.
                char * actualPath = new char[*pathUsed];
                strncpy(actualPath, path, *pathUsed);
                returnPath = actualPath;
            }
        }
    };

    return returnPath;
}

Requirements

Header: XPersistentLocalStorage.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles