타이틀 스토리지 인터페이스

클라우드의 모든 플레이어가 공유하는 암호화된 데이터를 다운로드하는 인터페이스

10 분 소요

타이틀 스토리지 인터페이스(Title Storage Interface) 는 개발자가 에픽 온라인 서비스(EOS) 를 사용하여 클라우드 서버에서 암호화된 데이터를 얻을 수 있게 합니다. 이 인터페이스를 통해 데이터를 저장하면 모든 디바이스에서 누구나 로그인하여 데이터에 액세스할 수 있습니다. 이 인터페이스는 플레이어 데이터 스토리지 인터페이스(Player Data Storage Interface)와 비슷하지만, 사용자별 데이터보다는 게임별 데이터를 처리하는 데 특화된 인터페이스이며,사용자의 플랫폼, 지역 같은 조건에 따라 다른 파일 버전을 제공할 수 있습니다. 타이틀 스토리지 인터페이스와 플레이어 데이터 스토리지 인터페이스의 차이에 대한 자세한 정보는 이 문서 끝에 있는 플레이어 데이터 스토리지와의 차이 섹션을 참고하세요.

타이틀 스토리지 인터페이스에 액세스하려면 플랫폼 인터페이스 함수인 EOS_Platform_GetTitleStorageInterface 를 통해 EOS_HTitleStorage 핸들을 얻어야 합니다. 모든 타이틀 스토리지 인터페이스 함수는 첫 번째 파라미터로 이 핸들이 필요합니다. 요청이 완료되었을 때 적절한 콜백을 트리거하려면 EOS_HPlatform 핸들의 틱이 실행 중인지 확인해야 합니다.

이 인터페이스를 사용하려면 다음 추가 파라미터로 EOS 플랫폼을 초기화해야 합니다.

  • const char* EncryptionKey : 이 64자 16진법 스트링은 EOS가 사용자 데이터를 암호화하기 위해 사용하는 256비트 키를 빌드합니다. 에픽의 백엔드 서버는 이 키를 저장하지 않습니다. 키가 없으면 타이틀 스토리지 인터페이스의 파일 관리 함수 호출이 실패하고 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 해시 등 하나 이상의 파일에 대한 메타데이터를 반환합니다. 그러면 사용자는 자신만의 메타데이터 사본을 요청하고 관리할 수 있으며, 이 사본으로 파일에 액세스하거나 수정할 수 있습니다. 파일은 백엔드에 암호화된 형식으로 저장되므로, 파일 크기나 MD5 해시 같은 메타데이터는 개발자 포털을 통해 업로드한 원본 파일보다는 암호화된 파일을 반영합니다.

쿼리의 콜백 함수 처리 기간 동안 캐시에서 필요할 수 있는 정보를 복사해야 합니다. 이 데이터의 수명은 콜백 함수 기간보다 더 오래 지속될 것이라고 보장되지 않습니다. 이는 여러 개의 쿼리를 실행할 때 특히 중요합니다. 각 쿼리가 성공할 때마다 캐시의 콘텐츠가 변경될 수 있기 때문입니다.

대부분의 함수에는 트래킹이 더 용이하도록 제품 사용자 ID 파라미터 옵션이 포함되어 있습니다. 제품 사용자 ID 없이 nullptr을 전달하는 방법으로 데이터를 쿼리할 수 있지만, 개발자 포털에서 설정한 사용자 ID 오버라이드를 사용할 수 없게 됩니다. 콜백에는 전달한 동일 사용자 제품 ID 값이 포함됩니다.

단일 파일 쿼리

하나의 파일에 대한 정보만 필요하고 그 파일명을 안다면, 다음과 같이 초기화된 EOS_TitleStorage_QueryFileOptions 구조를 전달하여 EOS_TitleStorage_QueryFile 함수를 호출할 수 있습니다.

프로퍼티
ApiVersionEOS_TITLESTORAGE_QUERYFILEOPTIONS_API_LATEST
LocalUserId(옵션) 파일 데이터를 요청하는 로컬 사용자의 EOS_ProductUserId
Filename쿼리하는 파일의 이름

작업이 완료되면 EOS는 EOS_TitleStorage_QueryFileCallbackInfo 구조로 콜백(EOS_TitleStorage_OnQueryFileCompleteCallback 타입)을 실행합니다. 호출에 성공하면 EOS는 파일에 대한 데이터를 캐시로 가져옵니다.

태그로 여러 파일 쿼리하기

한 번에 여러 파일을 쿼리하거나 정확한 파일명을 모르는 상태로 파일을 쿼리하려면, 먼저 개발자 포털을 통해 파일에 태그부터 적용해야 합니다. 그러면 EOS SDK에서 그 태그를 기반으로 쿼리할 수 있습니다. 파일 태그는 EOS 파일명과 같은 형식 규칙을 사용하는 스트링입니다. 이 방식으로 파일을 쿼리할 때는 하나 이상의 태그를 제공해야 합니다. 그러면 EOS SDK에서 해당 태그를 하나 이상 포함하는 모든 파일 목록을 얻게 됩니다. 이렇게 하려면 다음과 같이 초기화된 EOS_TitleStorage_QueryFileListOptions 데이터 구조로 EOS_TitleStorage_QueryFileList 를 호출합니다.

프로퍼티
ApiVersionEOS_TITLESTORAGE_QUERYFILELISTOPTIONS_API_LATEST
LocalUserId(옵션) 파일 데이터를 요청하는 로컬 사용자의 EOS_ProductUserId
NumTags태그 목록의 태그 수(양수여야 함)
ListOfTags파일 쿼리에 사용하는 태그의 배열(ASCII 스트링)

완료되면 EOS는 EOS_TitleStorage_QueryFileListCallbackInfo 데이터 구조로 콜백 함수(EOS_TitleStorage_OnQueryFileListCompleteCallback 타입)를 실행합니다. 호출이 성공하면 발견된 파일 수가 데이터 구조체에 포함되며 해당 파일에 대한 정보를 EOS 캐시에서 사용할 수 있습니다.

모든 파일 쿼리

타이틀 스토리지 인터페이스에서 모든 파일을 쿼리하는 특정 API 호출은 제공하지 않습니다. 하지만 업로드하는 파일 전부에 특정 태그를 적용하는 방법이 있습니다. 해당 태그와 함께 EOS_TitleStorage_QueryFileListOptions 를 사용하면 모든 파일의 데이터를 얻을 수 있습니다.

(#ExaminingCachedFileInformation)

캐시된 파일 정보 조사하기

EOS가 하나 이상의 파일에 대한 정보를 얻고 캐시하고 나면, 특정 파일의 정보를 얻기 위해 그 파일명으로 EOS_TitleStorage_CopyFileMetadataByFilename 을 호출하거나, 캐시 내에서 파일의 0부터 시작하는 인덱스로 EOS_TitleStorage_CopyFileMetadataAtIndex 를 호출하면 됩니다. 캐시에 있는 파일 수를 알아야 하는 경우, EOS_TitleStorage_GetFileMetadataCount 를 호출합니다. 이 정보의 사본이 더는 필요 없다면, EOS_TitleStorage_FileMetadata_Release 를 호출하여 사용하던 메모리를 해제합니다.

EOS에 단일 파일에 대한 정보를 쿼리한 후에, EOS_TitleStorage_GetFileMetadataCount 가 캐시에 여러 개의 파일이 있다고 알릴 수도 있습니다. 이러한 상황은 이전 쿼리의 결과가 캐시에 남아 있는 경우에 발생합니다. 이 경우에 가장 좋은 방법은 EOS_TitleStorage_QueryFileCallbackInfo 내의 ResultCodeEOS_Success인지 확인하고 EOS_TitleStorage_CopyFileMetadataByFilename 을 호출하여 그 정보에 액세스하는 것입니다. 여러 파일 쿼리에 성공하면 전에 캐시된 메타데이터가 제거됩니다.

파일에 액세스하기

타이틀 스토리지 인터페이스는 클라우드에서 비동기식으로 파일을 읽는 기능을 지원합니다. 읽기는 스트리밍 작업이며, EOS는 스트리밍 진행 상황을 확인하거나 제한하거나 중단하는 데 사용할 수 있는 핸들을 제공합니다.

파일 읽기

클라우드(또는 로컬 캐시)에서 알려진 이름의 파일을 읽으려면 EOS_TitleStorage_ReadFile 을 호출합니다. 다음과 같이 초기화된 EOS_TitleStorage_ReadFileOptions 를 전달해야 합니다.

프로퍼티
ApiVersionEOS_TITLESTORAGE_READFILEOPTIONS_API_LATEST
LocalUserId(옵션) 요청된 파일을 읽을 로컬 사용자의 계정 ID
Filename읽을 파일명
ReadChunkLengthBytes하나의 EOS_TitleStorage_OnReadFileDataCallback 호출에서 읽을 최대 데이터 양
ReadFileDataCallback데이터가 들어오는 대로 처리하고 전송을 조기에 중단할 수 있는 콜백 함수
FileTransferProgressCallback전송 진행 상황을 알려줄 선택적 콜백 함수(설정하면 최소 1회 호출됨)

이 함수는 전송 진행 상황을 확인하거나 파일명을 얻거나 전송을 취소하는 데 사용할 수 있는 EOS_HTitleStorageFileTransferRequest 핸들을 반환합니다. 전송 중에 언제든지 EOS_TitleStorageFileTransferRequest_GetFileRequestState 를 호출하여 현재 상태를 폴링하거나, EOS_TitleStorageFileTransferRequest_GetFilename 을 호출하여 전송 중인 파일명을 확인하거나, EOS_TitleStorageFileTransferRequest_CancelRequest 를 호출하여 (오류 생성 없이) 전송을 취소할 수 있습니다. 직접 전송을 폴링하는 것보다 EOS에서 업데이트를 받는 것을 선호하는 경우, (FileTransferProgressCallback 파라미터로) 전송 시작 시 유효한 EOS_TitleStorage_OnFileTransferProgressCallback 함수를 제공하면 EOS에서 주기적으로 이 함수를 호출(EOS_TitleStorage_FileTransferProgressCallbackInfo 파라미터 사용)하여 파일 전송 진행 상황을 알려줍니다. 이 방법을 선택하면 콜백 함수에 대해 최소 한 번의 호출을 받을 수 있습니다. 콜백 함수를 사용해도 핸들 사용에는 아무런 지장이 없지만 이 둘은 매우 비슷한 목적을 수행하므로 대부분의 사용 사례에서는 함께 사용할 필요가 없습니다.

파일 청크가 들어오면, ReadFileDataCallback(EOS_TitleStorage_OnReadFileDataCallback 타입)이 EOS_TitleStorage_ReadFileDataCallbackInfo 타입의 파라미터로 실행됩니다. 이 구조체는 파일의 실제 데이터 청크와 해당 청크가 최종인지 아닌지를 나타내는 변수를 포함합니다. 또한, 열거형 반환 타입인 EOS_TitleStorage_EReadResult 도 포함되는데, 이를 사용하여 EOS에 전송을 계속 진행하거나 오류 때문에 종료하거나 오류 보고 없이 취소하도록 지시할 수 있습니다.

파일 전송이 완료되면, EOS에서 EOS_TitleStorage_ReadFileCallbackInfo 파라미터로 EOS_TitleStorage_OnReadFileCompleteCallback 콜백 함수를 실행합니다. 이 파라미터는 성공 또는 실패를 표시하며 파일 이름을 포함합니다.

EOS는 이후 읽기 작업의 속도를 높이기 위해 파일을 로컬로 캐시할 수 있습니다. 이러한 파일은 EOS 플랫폼 초기화 때 제공한 키로 암호화됩니다. ReadFileDataCallback 함수로 전송된 데이터 청크는 암호화되지 않습니다.

다음 타임라인 다이어그램은 작동 중인 읽기 작업의 예시입니다.