XPersistentLocalStorageGetPath

返回指向设备上永久性本地存储 (PLS) 的特定于游戏的路径。

语法

HRESULT XPersistentLocalStorageGetPath(  
         size_t pathSize,  
         char* path,  
         size_t* pathUsed  
)  

参数

pathSize _In_
类型：size_t

缓冲区中为 PLS 路径提供的字符数。 要获取该值，请调用 XPersistentLocalStorageGetPathSize。

path _Out_writes_to_(pathSize,pathUsed)
类型：char

游戏可将数据写入到的 PLS 路径。

pathUsed _Out_opt_
类型：size_t*

写入所提供的缓冲区的字符数。

返回值

类型：HRESULT

如果成功，则返回 S_OK；否则返回错误代码。 有关错误代码的列表，请参阅错误代码。 如果该函数由于 pathSize 小于 PLS 路径的长度而失败，则对于 Xbox 设备，返回值设置为 E_FAIL；对于电脑设备，返回值设置为 HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER)。

备注

注意

在时间敏感线程上调用此函数是不安全的。 有关详细信息，请参阅时间敏感线程。

游戏可能需要 PLS 以执行诸如暂存空间、游戏内 DLC 和按需生成内容等任务。 尽管跨游戏的激活保留了空间，但用户也可以将其删除。 有关 PLS 的详细信息，请参阅本地存储

根据设备的系列访问和管理 PLS。 对于 Xbox 设备，我们提供对装载到驱动器根的文件夹的访问权限。 为该文件夹预配的存储空间量是在游戏的 MicrosoftGame.config 文件中指定的。 预配的空间可用，并且始终在游戏启动过程中出现。 要释放空间，用户可以在游戏未运行时删除预配的空间而不卸载游戏；但是，当游戏运行时，应保证存储的可用性。 要为 Xbox 设备预配此空间，在 MicrosoftGame.config 文件中必须具有相应的条目。

对于电脑设备，我们提供对电脑上本地存储文件夹的位置的访问权限，但不会为您的游戏专门预配空间。 即使在游戏运行时，用户也可以删除该空间。 无法保证存储的可用性，并且 MicrosoftGame.config 文件中不需要条目来声明存储空间。 您必须首先确认本地存储文件夹中的可用空间足以满足您游戏的目的。

在调用此函数以检索 PLS 路径之前，请先调用 XPersistentLocalStorageGetPathSize 函数以获取 PLS 路径中的字符数，然后在 pathSize 参数中提供该值，并分配与 path 参数至少相同数量的字符。 如果在 pathSize 中指定的字符数少于 PLS 路径中包含的字符数，将会发生错误。

下面的示例说明如何使用 XPersistentLocalStorageGetPathSize 和 XPersistentLocalStorageGetPath 函数获取游戏的 PLS 路径。

// 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;
}

要求

头文件：XPersistentLocalStorage.h

库：xgameruntime.lib

支持平台：Windows、Xbox One 系列主机和 Xbox Series 主机

另请参阅

XPersistentLocalStorageGetPathSize
XPersistentLocalStorage
如何使用新的 MicrosoftGame.config 文件