> ## 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](/zh-TW/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**；否則傳回錯誤碼。如需錯誤碼的清單，請參閱[錯誤碼](/zh-TW/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 的詳細資訊，請參閱[本機儲存體](/zh-TW/build/console-features/storage/local-storage)

PLS 會根據裝置的系列進行存取和管理。對於 XBOX 裝置，我們會提供對掛接至磁碟機根目錄之資料夾的存取權。為該資料夾佈建的儲存空間量是在遊戲的 MicrosoftGame.config 檔案中指定。佈建的空間在遊戲啟動期間可供使用且一律存在。為了釋放空間，使用者可以在遊戲未執行時刪除佈建的空間，而不需解除安裝遊戲；不過，在遊戲執行時，儲存體的可用性是有保證的。若要為 XBOX 裝置佈建此空間，您的 MicrosoftGame.config 檔案中必須有對應的項目。

對於 PC 裝置，我們會提供對 PC 上本機儲存體資料夾位置的存取權，但不會特別為您的遊戲佈建空間。即使遊戲正在執行，使用者也可以刪除該空間。儲存體的可用性沒有保證，而且不需要在 MicrosoftGame.config 檔案中有項目即可取得儲存空間。您必須先確認本機儲存體資料夾中的可用空間足以符合遊戲的用途。

在呼叫此函式擷取 PLS 路徑之前，請先呼叫 [XPersistentLocalStorageGetPathSize](/zh-TW/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 主機上的本機儲存體](/zh-TW/build/console-features/storage/local-storage)
* [時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

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


## Related topics

- [XPersistentLocalStorageGetPath](/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpath.md)
- [XPersistentLocalStorageGetPathSize](/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetpathsize.md)
- [Local storage](/build/console-features/storage/local-storage.md)
- [XPersistentLocalStorage](/reference/system/xpersistentlocalstorage/xpersistentlocalstorage_members.md)
- [XPersistentLocalStorageGetSpaceInfo](/reference/system/xpersistentlocalstorage/functions/xpersistentlocalstoragegetspaceinfo.md)