UDN
Search public documentation:

CloudDocumentStorageKR
English Translation
中国翻译

Interested in the Unreal Engine?
Visit the Unreal Technology site.

Looking for jobs and company info?
Check out the Epic games site.

Questions about support via UDN?
Contact the UDN Staff

UE3 홈 > 플랫폼 인터페이스 프레임워크 > 클라우드 도큐멘트 스토리지

클라우드 도큐멘트 스토리지


문서 변경내역: Jeff Wilson 작성. 홍성진 번역.

개요


클라우드 도큐멘트 스토리지(Cloud Document Storage)는 일반적으로 게임 데이터를 저장하기 위해 "클라우드"에 보관되는 도큐멘트에(서) 데이터를 보관하(거나 읽어오)는 것을 말합니다.

주: 클라우드 도큐멘트 스토리지 함수성은, PC 에서 도큐멘트를 로컬에 저장하여 시뮬레이션되기는 해도, 현재 iOS 플랫폼에서 실행되는 게임에 제한되어 있습니다.

CloudStorageBase


CloudStorageBase 클래스는 클라우드 도큐멘트를 로드하고 저장하는 함수성이 담겨있는 베이스 클래스입니다. PlatformInterfaceBase 를 상속하여 그 클래스에 들어있는 델리게이트 시스템을 활용합니다. (PC, iOS 등) 각 플랫폼은 CloudStorageBase 에서 확장되는 자체 서브클래스가 있어, 해당 플랫폼 전용 구현을 제공합니다.

Functions 함수

  • Init - 엔진이 클라우드 스토리지 시스템을 initialize 하기 위해 호출하는 이벤트입니다.
  • ReadKeyValue [KeyName] [Type] [SerializedObj] - 클라우드 스토리지에서 키/값 쌍 읽기를 시작시키고, 성공하면 참을 반환합니다.
    • KeyName - 읽을 이름 (string) 입니다.
    • Type - 읽을 값의 EPlatformInterfaceDataType 종류입니다.
    • SerializedObj - 오브젝트를 읽는 경우, 바이너리 덩어리를 이 오브젝트로 de-serialize 합니다.
  • WriteKeyValue [KeyName] [Value] - 클라우드에 키/값 쌍을 쓰고, 성공하면 참을 반환합니다.
    • KeyName - 쓸 키의 이름 (string) 입니다.
    • Value - 지정된 키에 쓸 PlatformInterfaceData 값입니다.
  • QueryForCloudDocuments - 클라우드에 존재하는 도큐멘트 비동기 퀴리를 시작하고, 성공하면 참을 반환합니다. 이미 받아둔 도큐멘트가 있으면, 그 도큐멘트를 비우고 세트를 새로 고칩니다. 완료되면 GetNumCloudDocuments()GetCloudDocumentName() 를 사용하여 기존 도큐멘트에 대한 정보를 구합니다.
  • GetNumCloudDocuments [bIsForConflict] - QueryForCloudDocuments() 로의 콜 이후 클라우드에 존재하는 것으로 알려진 도큐멘트 수를 반환합니다.
    • bIsForConflict - 옵션. 참이면 도큐멘트 총 갯수 대신 충돌이 있는 도큐멘트 수가 반환됩니다.
  • GetCloudDocumentName [Index] - 주어진 인덱스에 상응하는 도큐멘트 이름을 반환합니다.
    • Index - 이름을 구할 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • CreateCloudDocument [Filename] - 클라우드에 새 도큐멘트를 만듭니다. (initialize 도 안되어있고 저장도 안되어있으니 Write/Save 함수를 사용하세요.)
    • Filename - 새로 만든 도큐멘트에 줄 이름 (string) 입니다.
  • ReadCloudDocument [Index] [bIsForconflict] - 도큐멘트를 메모리로 읽어옵니다. (또는 게임 지체 없이 ParseDocumentAs* 함수가 동기적으로 작동되게 하기 위해 필요한 작업을 해 줍니다.)
    • Index - 읽을 도큐멘트의 인덱스를 나타내는 Int 입니다.
    • bIsForConflict - 참이면 Index 는 모든 도큐멘트 배열이 아닌 충돌이 있는 도큐멘트 배열에 대한 인덱스가 됩니다.
  • ParseDocumentAsString [Index] [bIsForConflict] - 전체 도큐멘트를 나타내는 문자열을 반환합니다. 도큐멘트를 읽을 때는 먼저 ReadCloudDocument() 를 사용해야 합니다. 이 함수는 SaveDocumentWithString() 를 사용하여 도큐멘트를 생성했을 때만 사용해야 합니다.
    • Index - 파싱할 도큐멘트의 인덱스를 나타내는 Int 입니다.
    • bIsForConflict - 참이면 Index 는 모든 도큐멘트 배열이 아닌 충돌이 있는 도큐멘트 배열에 대한 인덱스가 됩니다.
  • ParseDocumentAsBytes [Index] [ByteData] [bIsForConflict] - 전체 도큐멘트를 나타내는 바이트 배열을 출력합니다. 도큐멘트를 읽을 때는 먼저 ReadCloudDocument() 를 사용해야 합니다. 이 함수는 SaveDocumentWithBytes() 를 사용하여 도큐멘트를 생성했을 때만 사용해야 합니다.
    • Index - 파싱할 도큐멘트의 인덱스를 나타내는 Int 입니다.
    • ByteData - 도큐멘트의 데이터로 채워진 바이트 배열입니다. 파싱이 실패하면 비어 있습니다.
    • bIsForConflict - 참이면 Index 는 모든 도큐멘트 배열이 아닌 충돌이 있는 도큐멘트 배열에 대한 인덱스가 됩니다.
  • ParseDocumentAsObject [Index] [ObjectClass] [ExpectedVersion] [bIsForConflict] - 전체 도큐멘트를 나타내는 오브젝트를 반환합니다. 도큐멘트를 읽을 때는 먼저 ReadCloudDocument() 를 사용해야 합니다. 이 함수는 SaveDocumentWithObject() 를 사용하여 도큐멘트를 생성했을 때만 사용해야 합니다.
    • Index - 파싱할 도큐멘트의 인덱스를 나타내는 Int 입니다.
    • ObjectClass - 도큐멘트의 데이터를 사용하여 만들 오브젝트 Class 입니다.
    • ExpectedVersion - 데이터의 (SaveDocumentWithObject 를 통해 설정된) 예상 버전 번호를 나타내는 Int 입니다. 데이터 버전이 여기에 일치하지 않는다면 함수는 none 을 반환합니다.
    • bIsForConflict - 참이면 Index 는 모든 도큐멘트 배열이 아닌 충돌이 있는 도큐멘트 배열에 대한 인덱스가 됩니다.
  • WriteCloudDocument [Index] - SaveDocumentWith* 함수를 사용하여 이미 "저장된" 도큐멘트를 씁니다.
    • Index - 쓸 도큐멘트의 인덱스를 나타내는 Int 입니다.
  • SaveDocumentWithString [Index] [StringData] - 문자열을 입력 데이터로 하여 클라우드에 쓸 도큐멘트를 준비합니다. 동기성(synchronous)입니다.
    • Index - 저장할 도큐멘트의 인덱스를 나타내는 Int 입니다.
    • StringData - 파일에 저장할 String 데이터입니다.
  • SaveDocumentWithBytes [Index] [ByteData] - 바이트 배열을 입력 데이터로 하여 클라우드에 쓸 도큐멘트를 준비합니다. 동기성(synchronous)입니다.
    • Index - 저장할 도큐멘트의 인덱스를 나타내는 Int 입니다.
    • ByteData - 파일에 저장할 바이트 배열입니다.
  • SaveDocumentWithObject [Index] [ObjectData] [SaveVersion] - 오브젝트를 입력 데이터로 하여 클라우드에 쓸 도큐멘트를 준비합니다. 동기성(synchronous)입니다.
    • Index - 저장할 도큐멘트의 인덱스를 나타내는 Int 입니다.
    • ObjectData - 바이트로 serialize 하고 파일에 저장할 Object 데이터입니다.
    • SaveVersion - 저장할 오브젝트의 버전 번호를 나타내는 Int 입니다. 이 오브젝트를 로드할 때, 이 버전에 일치하지 않는 오브젝트는 로드하지 않습니다.
  • ResolveConflictWithNewestDocument - 충돌 통지가 생기면, 클라우드 인터페이스더러 가장 최근에 수정된 버전을 선택하고, 다른 것은 던져 버리라고 이릅니다.
  • ResolveConflictWithNewestVersionIndex [Index] - 충돌 통지가 생기면, 클라우드 인터페이스더러 주어진 인덱스 버전을 마스터 버전으로 선택하고, 다른 것은 던져 버리라고 이릅니다.
    • Index - 마스터 버전으로 유지할 도큐멘트 인덱스를 나타내는 Int 입니다.

Delegates 델리게이트

ECloudStorageDelegate enum 은 콜백을 받을 수 있는 델리게이트 종류에 대한 ID 를 정의합니다. 플랫폼 인터페이스 델리게이트 시스템을 사용하여 이들 각각에 델리게이트를 할당할 수 있습니다.

  • CSD_KeyValueReadComplete - 이 ID 에 할당된 델리게이트는, ReadKeyValue() 를 통해 클라우드 키/값을 읽으려는 시도가 끝났을 때 실행됩니다.
    • bSuccessful - 값을 읽는 데 성공했으면 참입니다.
    • Data - 읽은 값입니다.
  • CSD_KeyValueWriteComplete - 이 ID 에 할당된 델리게이트는, WriteKeyValue() 를 통해 클라우드 키/값을 쓰려는 시도가 끝났을 때 실행됩니다.
    • bSuccessful - 값을 쓰는 데 성공했으면 참입니다.
    • Data - 쓴 값입니다.
  • CSD_ValueChanged - 이 ID 에 할당된 델리게이트는, 클라우드 키/값이 바뀔 때 실행됩니다.
    • bSuccessful - 성공하면 참입니다.
    • Data - 값이 변한 키 이름입니다.
  • CSD_DocumentQueryComplete - 이 ID 에 할당된 델리게이트는, QueryCloudDocuments() 를 통해 클라우드 도큐멘트에 대한 퀴리가 끝났을 때 실행됩니다.
    • bSuccessful - 읽는 데 성공했으면 참입니다.
    • Data - 읽은 도큐멘트의 인덱스입니다.
  • CSD_DocumentReadComplete - 이 ID 에 할당된 델리게이트는, ReadCloudDocument() 를 통해 읽을 도큐멘트를 열려는 시도가 끝났을 때 실행됩니다.
    • bSuccessful - 여는 데 성공했으면 참입니다.
    • Data - 연 도큐멘트의 인덱스입니다.
  • CSD_DocumentWriteComplete - 이 ID 에 할당된 델리게이트는, WriteCloudDocument() 를 통해 도큐멘트를 쓰려는 시도가 끝났을 때 실행됩니다.
    • bSuccessful - 도큐멘트를 쓰는 데 성공했으면 참입니다.
    • Data - 쓴 도큐멘트의 인덱스입니다.
  • CSD_DocumentConflictDetected - 이 ID 에 할당된 델리게이트는, 여러 기계에서 도큐멘트를 업데이트하여 충돌이 일어났을 때 실행됩니다. ResolveConflictWithNewest* 함수를 통해 스크립트가 사용할 버전을 결정하도록 하는 데 사용됩니다.
    • bSuccessful - 성공하면 참입니다.
    • Data - 충돌이 발생한 도큐멘트의 인덱스 입니다.

데이터로서의 Object


Object 와 그 프로퍼티를 serialize 시켜 클라우드 도큐멘트에 저장하면 클라우드 스토리지를 게임 데이터 저장용으로 활용할 수 있게 됩니다. 여기서 일반적인 개념은, 모든 데이터가 저장될 변수가 담긴, Object 에서 확장된 클래스가 생성된다는 것입니다. 이 게임 데이터 오브젝트의 인스턴스가 만들어지고 그 변수는 게임 도중 업데이트됩니다. 게임 저장 준비가 되면 이 오브젝트의 인스턴스가 SaveDocumentWithObject() 에 전달되고, 그 다음 도큐멘트가 WriteCloudDocument() 로 작성됩니다. 그리고서 게임 시작시 ReadCloudDocument()ParseDocumentAsObject() 를 사용하여 데이터를 읽어들일 수 있는 것입니다.

구현 세부사항


언리얼 엔진 3 에서 클라우드 도큐멘트 스토리지를 셋업하여 사용하는 법에 대한 일반적인 작업방식은 개략적으로 아래와 같습니다:

  1. 게임이 iOS 앱인 경우, iOS Provisioning Portal 에서 iCloud 서비스를 사용하도록 셋업되었는지 확인합니다. 자세한 정보는 Apple Developer Site 를 확인하시기 바랍니다.
  2. PlatformInterfaceBase 클래스의 static GetCloudStorageInterface() 를 호출하여 CloudStorageBase 오브젝트로의 리퍼런스를 구한 다음 처리하려는 (도큐멘트 퀴리, 값 변경/읽기/쓰기, 도큐멘트 읽기/쓰기, 충돌 감지 등의) 델리게이트를 셋업해 줍니다. 이들은 보통 PostBeginPlay() 에 있거나, 클라우드 도큐멘트 함수성을 놓은 곳에 따라 다른 초기화(initialization) 함수에 있을 수도 있습니다.
     var CloudStorageBase Cloud;
  
     ...
  
     Cloud = class'PlatformInterfaceBase'.static.GetCloudStorageInterface();
     Cloud.AddDelegate(CSD_ValueChanged, CloudValueChanged);
     Cloud.AddDelegate(CSD_DocumentReadComplete, CloudReadDocument);
     Cloud.AddDelegate(CSD_DocumentConflictDetected, CloudConflictDetected);
  
CloudValueChanged, CloudReadDocument, CloudConflictDetected 는 예제일 뿐입니다. PlatformInterfaceDelegate 델리게이트의 시그너처에 일치하는 함수 이름이면 무엇이든 될 수 있습니다.
     delegate PlatformInterfaceDelegate(const out PlatformInterfaceDelegateResult Result);
  
  1. 게임에서 쓸 도큐먼트 목록을 구하려면, CloudStorageBase 오브젝트에서 QueryForCloudDocuments() 를 호출하고, 원하는(, 보통 메뉴같은) 방식으로 사용자에게 도큐멘트 목록을 표시하는 작업을 처리하는 곳인 CSD_DocumentQueryComplete 콜백을 기다립니다.
     Cloud.QueryForCloudDocuments();
  
  1. 도큐멘트를 읽으려면 ReadCloudDocument() 를 호출한 다음 예상되는 데이터 형태에 따라 ParseDocumentAs*() 함수 중 하나를 사용합니다.
     Cloud.ReadCloudDocument(0);
     StringData = Cloud.ParseDocumentAsString(0);
  
  1. 도큐멘트를 저장하려면, SaveDocumentAs*() 함수 중 하나에 적절한 데이터를 전달해서 호출하고, WriteCloudDocument() 를 호출하여 도큐멘트를 저장합니다.
     Cloud.SaveDocumentAsString(0, StringData);
     Cloud.WriteCloudDocument(0);
  
기본 구현은 UDKBase\Classes\CloudPC.uc 에서 찾을 수 있으며, 게임타입 CloudGame 을 사용해서 테스트할 수 있습니다.