> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XPersistentLocalStorageGetPath

> XPersistentLocalStorageGetPath

# XPersistentLocalStorageGetPath

返回设备上永久本地存储 (PLS) 的游戏专用路径。

## 语法

```cpp theme={null}
HRESULT XPersistentLocalStorageGetPath(  
         size_t pathSize,  
         char* path,  
         size_t* pathUsed  
)  
```

### 参数

*pathSize*   \_In\_\
类型：size\_t

为 PLS 路径提供的缓冲区中的字符数。要获取此值，请调用 [XPersistentLocalStorageGetPathSize](/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize)。

*path*   \_Out\_writes\_to\_(pathSize,*pathUsed)\
类型：char*

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

*pathUsed*   \_Out\_opt\_\
类型：size\_t\*

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

### 返回值

类型：[HRESULT](https://learn.microsoft.com/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a)

如果成功，则返回 **S\_OK**；否则返回错误代码。有关错误代码列表，请参阅[错误代码](/reference/errorcodes)。如果因为 *pathSize* 小于 PLS 路径长度而函数失败，则返回值在 XBOX 设备上设为 **E\_FAIL**，在 PC 设备上设为 **HRESULT\_FROM\_WIN32(ERROR\_INSUFFICIENT\_BUFFER)**。

## 备注

<Note>此函数在时间敏感型线程上调用不安全。有关详细信息，请参阅[时间敏感型线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

游戏可能需要 PLS 来执行诸如暂存空间、游戏内 DLC 以及按需生成内容之类的任务。虽然该空间在游戏的多次激活之间保留，但用户也可以将其删除。有关 PLS 的详细信息，请参阅[本地存储](/build/console-features/storage/local-storage)。

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

对于 PC 设备，我们提供对 PC 上本地存储文件夹位置的访问，但不会专门为你的游戏预配空间。用户可以随时删除该空间，即使游戏正在运行。存储的可用性不能保证，也不需要在 MicrosoftGame.config 文件中添加条目即可占用存储空间。你必须首先确认本地存储文件夹中可用的空间足以满足游戏的用途。

在调用此函数以检索 PLS 路径之前，请先调用 [XPersistentLocalStorageGetPathSize](/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize) 函数来获取 PLS 路径中的字符数，然后在 *pathSize* 参数中提供该值，并为 *path* 参数分配至少同等数量的字符。如果 *pathSize* 中指定的字符数少于 PLS 路径中包含的字符数，则会发生错误。

以下示例演示如何使用 **XPersistentLocalStorageGetPathSize** 和 **XPersistentLocalStorageGetPath** 函数来获取游戏的 PLS 路径。

```cpp theme={null}
// 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 主机

## 概念文档

* [XBOX 主机上的本地存储](/build/console-features/storage/local-storage)
* [时间敏感型线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另请参阅

[XPersistentLocalStorageGetPathSize](/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize)\
[XPersistentLocalStorage](/reference/system/xpersistentlocalstorage/xpersistentlocalstorage_members)\
[如何使用新的 MicrosoftGame.config 文件](/build/core-features/common/game-config/MicrosoftGameConfig-toc)


## Related topics

- [XPersistentLocalStorageGetPathSize](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize.md)
- [XPersistentLocalStorage](/zh-CN/reference/system/xpersistentlocalstorage/xpersistentlocalstorage_members.md)
- [面向 GDK 的 Unity C# API 包装器](/zh-CN/build/gdk-and-engines/unity/unity-api-wrappers.md)
- [XPersistentLocalStorageGetSpaceInfo](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetspaceinfo.md)
- [XPersistentLocalStorageMountForPackage](/zh-CN/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragemountforpackage.md)