XPersistentLocalStorageGetPath

[アーティクル]
05/09/2023

デバイス上の永続的なローカルストレージ (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、PC デバイスでは HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) に設定されます。

解説

注意

この関数は、時間依存のスレッドで呼び出すのに安全ではありません。詳細については、「時間依存のスレッド」を参照してください。

ゲームでは、ステージング領域、ゲーム内 DLC、コンテンツのオンデマンド生成などのタスクに PLS が必要になる場合があります。この領域はゲームの複数のアクティブ化にわたって保持されますが、ユーザーが削除することもできます。 PLS の詳細については、「ローカルストレージ」を参照してください。

PLS は、デバイスのファミリーに従ってアクセスおよび管理されます。 Xbox デバイスでは、ドライブのルートにマウントされたフォルダーへのアクセスを提供します。そのフォルダーにプロビジョニングされたストレージ領域の容量は、ゲームの MicrosoftGame.config ファイルで指定されます。プロビジョニングされた領域は利用可能で、ゲームの起動中に常に存在します。空き領域を増やすには、ゲームを実行していないときに、ユーザーはゲームをアンインストールせずに、プロビジョニングされた領域を削除することができます。ただし、ゲームの実行中は、ストレージの可用性が保証されます。この領域を Xbox デバイス用にプロビジョニングするには、MicrosoftGame.config ファイルに対応するエントリが必要です。

PC デバイスでは、PC 上のローカルストレージフォルダーの場所へのアクセスを提供しますが、ゲームのための領域は特にプロビジョニングされていません。ユーザーは、ゲームの実行中でもその領域を削除できます。ストレージの可用性は保証されていません。ストレージ領域を要求するために、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 本体

次の方法で共有

XPersistentLocalStorageGetPath

構文

パラメーター

戻り値

解説

要件

関連項目

その他のリソース