Title Storage インターフェース

すべてのプレイヤーに共有される暗号化されたデータをクラウドからダウンロードするためのインターフェースです。

10 分で読めます

Title Storage インターフェース を使用することで、デベロッパーは Epic Online Services (EOS) をクラウド サーバーから暗号化したデータを取得することができます。このインターフェースで格納したデータは、ログイン可能なデバイス上のすべてのユーザーがアクセスできます。Player Data Storage インターフェイス と同様に、このインターフェイスは、ユーザー固有ではなくゲーム固有のデータの処理に特化しており、ユーザーのプラットフォーム、地域、またはその他の条件に応じてファイルをさまざまな形式で提供することができます。Title Storage インターフェースと Player Data Storage インターフェースの詳しい違いについては、このドキュメントの後半の「Player Data Storage との違い」セクションを参照してください。

Title Storage インターフェースを利用するには、Platform インターフェース 関数 EOS_Platform_GetTitleStorageInterfaceEOS_HTitleStorage ハンドルを取得します。Title Storage インターフェースの関数はすべて、最初のパラメータとしてこのハンドルを必要とします。リクエストが完了したときにコールバックがトリガーされるようにするには、EOS_HPlatform ハンドルがティックしていることを確認する必要があります。

このインターフェースを使用するには、次の追加パラメーターを使用して EOS プラットフォームを初期化する必要があります。

  • const char* EncryptionKey:この 64 文字の 16 進数文字列は 256 ビットのキーを構成し、EOS がこれをユーザー データの暗号化に使用します。Epic のバックエンド サーバーはこのキーを格納しません。キーを指定せずに Title Storage インターフェースからファイル管理関数を呼び出すと、失敗して EOS_TitleStorage_EncryptionKeyNotSet エラー コードを返します。

  • const char* CacheDirectory:これはローカル ディレクトリへのフルパスで、インターフェースがデータ ファイルを転送する際に一時的なストレージとして使用します。これは任意の場所を指定できます。通常は、システムの一時ディレクトリやゲームのデータ ディレクトリを選択します。指定したディレクトリが存在しない場合、EOS は作成を試みます。そして、EOS はディレクトリの競合をしないようにするので、複数のユーザーや製品に対して同じディレクトリを使用できます。このディレクトリに問題がある状態でファイル管理関数を呼び出すと、失敗して EOS_CacheDirectoryMissing または EOS_CacheDirectoryInvalid のエラーコードを返します。使用可能なフォルダに関するプラットフォーム別の制限については「EOS プラットフォーム ドキュメント」を参照してください。

ファイルを管理する

ファイル名の形式

EOS のファイル名は以下の形式です。Directory0/Directory1/DirectoryN/Filename.Extension

「Directory」と「Extension」の部分はオプションです。「/」文字を各ディレクトリ名の後ろに追加する必要がありますが、これは最初や最後の文字を含め他の場所には使用できません。ファイル名に以下の文字を使用できます。

  • すべての ASCII 英数字
  • !
  • -
  • _
  • +
  • .
  • '
  • (
  • )

ファイル名は EOS_TITLESTORAGE_FILENAME_MAX_LENGTH_BYTES (64) 文字を超えてはいけません。

ファイルのクエリ

EOS SDK では、いくつかのクエリ API を呼び出すことで、クラウドに保存されているファイルに関する情報を取得できます。クエリは、各ファイルの名前、サイズ (バイト単位)、MD5 ハッシュなど、1 つ以上のファイルに関するメタデータを返します。次に、このメタデータの独自のコピーを要求および管理し、それを使用してファイルにアクセスまたは変更することができます。ファイルはバックエンドに暗号化された形式で保存されるため、ファイルサイズや MD5 ハッシュなどのメタデータは、Dev Portal を通じてアップロードした元のファイルではなく、暗号化されたファイルを反映します。

クエリのコールバック関数の実行中に必ず、必要な情報をキャッシュからコピーする ようにしてください。このデータのライフタイムは、コールバック関数の期間を超えて持続することが保証されていません。複数のクエリを実行する場合、クエリが成功するたびにキャッシュの内容が変更される可能性があるため、これは特に重要です。

ほとんどの関数は、トラックを向上させるための Product User ID パラメータ (省略可能) を含みます。Product User ID を使わずに (nullptr を渡すことによって) データをクエリすることが可能ですが、Dev Portal で設定した User ID のオーバーライドは使用できません。Callbacks は渡された同じ User Product ID 値を含みます。

単一のファイルをクエリする

単一のファイルに関する情報のみが必要で、そのファイルの名前がわかっている場合は、EOS_TitleStorage_QueryFile 関数を呼び出して、次のように初期化された EOS_TitleStorage_QueryFileOptions 構造体を渡します。

プロパティ
ApiVersionEOS_TITLESTORAGE_QUERYFILEOPTIONS_API_LATEST
LocalUserIdファイル データを陸枝うとするローカル ユーザーの EOS_ProductUserId (省略可能)
Filenameクエリするファイルの名前

操作が完了すると、EOS は (EOS_TitleStorage_OnQueryFileCompleteCallback タイプの) コールバックを EOS_TitleStorage_QueryFileCallbackInfo 構造で実行します。呼び出しが成功すると、EOS はファイルに関するデータをキャッシュに保持します。

タグを使って複数のファイルをクエリする

一度に複数のファイルをクエリしたり、正確なファイル名を知らないファイルをクエリするには、まず Dev Portal からファイルにタグを適用する必要があります。EOS SDK は、これらのタグに基づいてファイルをクエリすることができます。ファイル タグは、EOS ファイル名と同じフォーマット規則を使用する文字列です。この方法でファイルをクエリする場合、1 つ以上のタグを指定する必要があります。EOS SDK は、少なくともタグの 1 つを含むすべてのファイルのリストを取得します。これを行うには、EOS_TitleStorage_QueryFileListOptions を指定して EOS_TitleStorage_QueryFileList を呼び出します。

プロパティ
ApiVersionEOS_TITLESTORAGE_QUERYFILELISTOPTIONS_API_LATEST
LocalUserIdファイル データを陸枝うとするローカル ユーザーの EOS_ProductUserId (省略可能)
NumTagsタグのリスト内のタグの数 (正である必要があります)
ListOfTagsファイルをクエリするタグ (ASCII 文字列) の配列

完了すると、EOS は (EOS_TitleStorage_OnQueryFileListCompleteCallback タイプ) )コールバック関数を EOS_TitleStorage_QueryFileListCallbackInfo データ構造で実行します。呼び出しが成功すると、データ構造には検出されたファイルの数が含まれ、それらのファイルに関する情報は EOS キャッシュで利用できます。

すべてのファイルをクエリする

Title Storage インターフェースは、すべてのファイルをクエリするための特定の API コールは提供しません。ただし、アップロードするすべてのファイルに特定のタグを適用する場合、そのタグで EOS_TitleStorage_QueryFileListOptions を使用して、すべてのファイルに関するデータを取得できます。

(#キャッシュしたファイル情報を確認する)

キャッシュしたファイル情報を確認する

EOS 1 つ以上のファイルに関する情報を取得してキャッシュすると、ファイル名で EOS_TitleStorage_CopyFileMetadataByFilename を呼び出すか、キャッシュにあるファイルのゼロベースのインデックスで EOS_TitleStorage_CopyFileMetadataAtIndex を呼び出すことで、特定のファイルの情報を取得できます。キャッシュにあるファイルの数を知る必要がある場合は、 EOS_TitleStorage_GetFileMetadataCount を呼び出すことができます。この情報のコピーが不要になったら EOS_PlayerDataStorage_FileMetadata_Release を呼び出して使用していたメモリを解放します。

単一のファイルに関する情報を EOS にクエリした結果、EOS_PlayerDataStorage_GetFileMetadataCount により複数のファイルがキャッシュに存在することが判明する場合があります。これは、以前クエリした結果がキャッシュに残っている場合に発生することがあります。このような場合のベスト プラクティスは、EOS_TitleStorage_QueryFileCallbackInfo にある ResultCodeEOS_Success であることを確認してから、EOS_TitleStorage_CopyFileMetadataByFilename を呼び出して情報にアクセスすることです。以前にキャッシュされたメタデータは、複数ファイルのクエリが成功すると削除されます。

ファイルへアクセスする

Title Storage インターフェースは、クラウドからのファイルの非同期読み取りをサポートしています。読み込みはストリーミング操作です。EOS では、ストリームの進行状況を確認したり、ストリームを調整または中断するために使用できるハンドルを提供します。

ファイルの読み取り

名前がわかっているファイルをクラウド (またはローカル キャッシュ) から読み取るには、EOS_TitleStorage_ReadFile を呼び出します。以下のように初期化した EOS_TitleStorage_ReadFileOptions を渡す必要があります。

プロパティ
ApiVersionEOS_TITLESTORAGE_READFILEOPTIONS_API_LATEST
LocalUserIdリクエストしたファイルを読み取るローカル ユーザーのアカウント ID (省略可能)
Filename読み取るファイルの名前
ReadChunkLengthBytes1 回の EOS_TitleStorage_OnReadFileDataCallback 呼び出しで読み取るデータの最大量
ReadFileDataCallback入ってくるデータを処理し、転送を早期に停止できるコールバック関数
FileTransferProgressCallback転送状況を通知するオプションのコールバック関数で、設定すると少なくとも 1 回呼び出されます

この関数は、転送の進行状況の確認、ファイル名の取得、または転送のキャンセルに使用できる EOS_HTitleStorageFileTransferRequest ハンドルを返します。転送中のいつでも、 EOS_TitleStorageFileTransferRequest_GetFileRequestState を呼び出して現在の状態をポーリングし、EOS_TitleStorageFileTransferRequest_GetFilename を呼び出して転送中のファイルの名前を確認するか、または EOS_TitleStorageFileTransferRequest_CancelRequest を呼び出して (エラーを生成せずに) 取り消します。転送を直接ポーリングするのではなく、EOS から更新を受信する場合は、転送を開始するときに有効な EOS_TitleStorage_OnFileTransferProgressCallback 関数を ( FileTransferProgressCallbackパラメーターとして) 提供し、EOS がそれを (EOS_TitleStorage_FileTransferProgressCallbackInfo パラメーターで) 呼び出して、ファイルの転送状況を定期的に通知します。このルートを選択すると、コールバック関数への呼び出しを少なくとも 1 つ以上受け取ることが保証されます。コールバック関数を使用した場合もハンドルを使用でき