현재상태 인터페이스(Presence Interface) 는 온라인에서 로컬 플레이어의 상태를 알려주고 다른 플레이어의 상태를 쿼리하는 애플리케이션입니다. 이 상태를 현재상태라고 합니다. 애플리케이션은 로컬 플레이어의 상태를 더 자세히 공유하기 위해 다른 사람에게 임시 데이터를 알려줄 수도 있습니다. 사용자는 친구 관계인 사람의 현재상태 정보만 받을 수 있습니다.
현재상태 인터페이스를 사용하려면 제품에서 에픽 계정 서비스(Epic Account Services, EAS) 가 활성 상태여야 하며, 온라인 현재상태 데이터에 액세스하려면 사용자 동의가 필요합니다. 개발자 포털에서 EAS를 활성화하거나 에픽 문서에서 자세한 내용을 확인할 수 있습니다. EAS와 사용자 동의 없이도 EOS SDK와 현재상태 인터페이스를 초기화할 수 있지만, 그 경우 백엔드 서비스에 보내는 모든 현재상태 인터페이스 함수 호출이 실패합니다.
현재상태 정보 관리하기
현재상태 인터페이스(Presence Interface) 를 사용하려면 반드시 플랫폼 인터페이스 함수인 EOS_Platform_GetPresenceInterface 에서 EOS_HPresence 타입의 핸들을 획득해야 합니다. 이 핸들을 사용하여 친구 목록에 있는 다른 사용자의 현재상태 정보를 다운로드하거나 자신의 현재상태를 업데이트할 수 있습니다.
현재상태 정보 받기 및 캐시하기
사용자의 현재상태 정보를 가져오려면 EOS_Presence_QueryPresenceOptions 구조, ClientData 파라미터 옵션, 콜백 함수를 사용하여 EOS_Presence_QueryPresence 를 호출합니다. EOS_Presence_QueryPresenceOptions 를 다음과 같은 필드 값으로 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_FRIENDS_QUERYPRESENCE_API_LATEST |
LocalUserId | 로그인한 상태로 요청을 보낸 사용자의 EOS_EpicAccountId 입니다. |
TargetUserId | 현재상태 정보를 가져올 사용자의 EOS_EpicAccountId 입니다. 반드시 이 값이 LocalUserId 와 일치하거나 해당 사용자와 친구여야 합니다. |
콜백 함수는 여기에 제공한 ClientData 파라미터를 받고, 작업이 완료되면 성공 여부와 상관없이 실행됩니다. 유일한 예외는 EOS_Presence_QueryPresenceOptions 구조에 필수 정보가 하나라도 부족해서 로컬에서 호출이 실패하는 경우입니다. 권한 부족으로 타깃 사용자의 현재상태를 볼 수 없는 경우 콜백 함수의 ResultCode 필드는 EOS_NotFound 가 됩니다. EOS_Success 를 제외한 다른 모든 값은 입력 실패 또는 상태 실패를 나타냅니다(유효하지 않은 파라미터, LocalUserId 와 로컬 로그인 사용자의 불일치, 오프라인 상태인 로컬 사용자 등).
현재상태 정보 업데이트하기
로컬 캐시에 현재상태 정보를 업데이트하는 방법은 두 가지입니다. 첫째는 EOS_Presence_QueryPresence 를 주기적으로 호출하거나 캐시에 액세스하기 직전에 호출하는 것입니다. 둘째는 변경 사항이 있을 때 현재상태 인터페이스에서 알림을 받는 것입니다. 이 기능을 활성화하려면 EOS_Presence_AddNotifyOnPresenceChanged 를 호출합니다. 이 함수에는 EOS_Presence_AddNotifyOnPresenceChangedOptions 구조, 사용자 정의 ClientData 파라미터, EOS_Presence_OnPresenceChangedCallback 타입의 콜백 함수가 필요합니다. 이 콜백 함수는 ClientData 파라미터와 현재상태가 변경된 사용자의 EOS_EpicAccountId 를 받습니다. EOS_Presence_OnPresenceChangedCallback 구조를 다음과 같이 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_FRIENDS_ADDNOTIFYONPRESENCECHANGED_API_LATEST |
성공하면 EOS_Presence_AddNotifyOnPresenceChanged 가 유효한 EOS_NotifcationId 를 반환합니다. 오류가 발생하면 EOS_INVALID_NOTIFICATIONID 를 반환합니다.
이 기능을 비활성화하려면 현재상태 핸들과 알림 ID를 파라미터로 전달하는 EOS_Presence_RemoveNotifyOnPresenceChanged 를 호출합니다. 이 함수는 앞서 EOS_Presence_AddNotifyOnPresenceChanged 에 등록된 핸들에 보내는 알림을 중단합니다.
한 번에 여러 개의 콜백이 등록될 수 있습니다. 이 경우 이벤트가 발생하면 모든 콜백이 호출됩니다.
현재상태 정보 조사하기
EOS_Presence_QueryPresence 가 캐시를 사용자의 현재상태 정보로 채우고 나면 조사하기 시작할 수 있습니다. 캐시가 지정된 사용자의 현재상태 정보를 포함하는지 확인하려면 EOS_HPresence handle 그리고 다음과 같이 초기화된 EOS_Presence_HasPresenceOptions 구조를 사용하여 EOS_Presence_HasPresence 를 호출합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_FRIENDS_HASPRESENCE_API_LATEST |
LocalUserId | 로그인한 상태로 요청을 보낸 사용자의 EOS_EpicAccountId 입니다. |
TargetUserId | 우리가 캐시된 현재상태 데이터를 찾을 사용자의 EOS_EpicAccountId 입니다. |
EOS_Presence_HasPresence 는 데이터를 찾는 데 성공하면 EOS_TRUE 를 반환하고, 잘못된 입력을 받거나 타깃 사용자의 데이터가 캐시에 없으면 EOS_FALSE 를 반환합니다.
EOS_Presence_CopyPresence 는 캐시로부터 현재상태 정보의 사본을 제공합니다. 현재상태 인터페이스는 데이터를 새로운 EOS_Presence_Info 오브젝트로 반환합니다. 이 함수에는 현재상태 인터페이스 핸들, EOS_Presence_CopyPresenceOptions 구조, 새로운 EOS_Presence_Info 오브젝트를 담을 출력 파라미터가 필요합니다. EOS_Presence_CopyPresenceOptions 구조를 다음과 같이 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_FRIENDS_COPYPRESENCE_API_LATEST |
LocalUserId | 로그인한 상태로 요청을 보낸 사용자의 EOS_EpicAccountId 입니다. |
TargetUserId | 캐시된 현재상태 데이터를 복사할 사용자의 EOS_EpicAccountId 입니다. |
현재상태 인터페이스가 캐시에서 해당 정보 사본을 가져오는 데 성공하면 EOS_Presence_CopyPresence 는 EOS_Success 를 반환하고, 타깃 사용자의 데이터 사본과 함께 제공한 EOS_Presence_Info 포인터를 채웁니다. 이 포인터는 호출자의 소유이므로 EOS SDK는 결코 포인터 내용을 수정하거나 관련 메모리를 해제하지 않습니다. 더 이상 이 데이터가 필요 없으면 EOS_Presence_Info_Release 를 포인터로 호출하여 해제합니다. 그렇지 않으면 메모리 누수가 발생합니다.
EOS_Presence_GetJoinInfo 를 사용하면 원격 사용자의 현재상태 데이터에서 전에 설정한 참여 정보(Join Info) 문자열을 쉽게 얻을 수 있습니다. 이 함수가 성공하려면 사용자의 현재상태 데이터가 현재상태 캐시에 있어야 합니다. 이 기능은 현재상태 인터페이스 핸들과 EOS_Presence_GetJoinInfoOptions 구조, char 버퍼에 대한 포인터로 설정된 OutBuffer, char 버퍼의 최대 길이로 설정된 InOutBufferLength 가 필요합니다. EOS_Presence_GetJoinInfoOptions 구조를 다음과 같이 초기화합니다.
| 파라미터 | 설명 |
|---|---|
ApiVersion | 이 파라미터를 EOS_PRESENCE_GETJOININFO_API_LATEST로 설정합니다. |
LocalUserId | 로그인한 상태로 요청을 보낸 사용자의 EOS_EpicAccountId입니다. |
TargetUserId | 참여 정보를 가져올 사용자의 EOS_EpicAccountId 입니다. 이 값은 로그인한 로컬 사용자(Local User) 또는 LocalUserId의 친구(Friend)여야 합니다. |
OutBuffer char 버퍼의 길이는 EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH 가 권장되며, 그렇지 않으면 일부 값을 저장하기에 길이가 너무 짧아 요청이 실패할 수 있습니다.
참고: 현재상태 정보 업데이트는 EOS_Presence_AddNotifyOnPresenceChanged 를 사용하더라도 기존 EOS_Presence_Info 오브젝트에 반영되지 않습니다. 이러한 오브젝트는 캐시 데이터의 사본이지 캐시에 대한 포인터가 아니며, 현재상태 인터페이스는 이 오브젝트를 소유하지 않고 초기 사본 이후로는 수정하지 않기 때문입니다.
로컬 현재상태 수정하기
로컬 사용자의 현재상태를 수정하려면 EOS_HPresenceModification 핸들을 생성하고 다음 함수 중 하나 이상을 호출하여 변경 사항을 설정해야 합니다.
EOS_PresenceModification_SetStatusEOS_PresenceModification_SetRawRichTextEOS_PresenceModification_SetDataEOS_PresenceModification_DeleteDataEOS_PresenceModification_SetJoinInfo
참고: 변경 사항은 EOS_Presence_SetPresence 호출이 성공한 후부터 반영됩니다.
PresenceModification 핸들 생성하기
로컬 사용자의 현재상태를 수정하려면 우선 유효한 EOS_HPresence 핸들로 호출한 EOS_Presence_CreatePresenceModification, 초기화된 EOS_Presence_CreatePresenceModificationOptions 구조, 유효하지 않은 EOS_HPresenceModification 핸들에 대한 포인터를 사용하여 PresenceModification 핸들을 생성합니다. EOS_Presence_CreatePresenceModificationOptions 구조를 다음과 같이 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PRESENCE_CREATEPRESENCEMODIFICATION_API_LATEST |
LocalUserId | 로그인한 상태의 유효한 로컬 사용자입니다. |
성공하면 EOS_Presence_CreatePresenceModification 함수는 EOS_EResult::EOS_Success 를 반환하며, OutPresenceModificationHandle 이 EOS_PresenceModification 네임스페이스 내의 함수와 함께 사용할 수 있도록 초기화됩니다. 결과적인 핸들이 더 이상 필요 없으면 EOS_PresenceModification_Release 메서드를 호출하여 릴리즈해야 합니다.
PresenceModification 변경하기
유효한 EOS_HPresenceModification을 사용하면 EOS_PresenceModification 함수 네임스페이스 내의 함수를 호출하여 사용자의 현재상태에 대한 업데이트를 빌드할 수 있습니다.
현재상태 정보 수정하기
새 상태를 설정하려면 유효한 EOS_HPresenceModification 핸들로 EOS_PresenceModification_SetStatus 를 호출하고 EOS_PresenceModification_SetStatusOptions 구조를 다음과 같이 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PRESENCE_SETSTATUS_API_LATEST |
Status | 유효한 EOS_Presence_EStatus 값입니다. |
성공하면 EOS_PresenceModification_SetStatus 는 EOS_EResult::EOS_Success 를 반환합니다. 그렇지 않은 경우 요청에서 발생한 문제를 설명하는 오류 코드를 반환합니다. EOS_Presence_SetPresence 호출이 EOS_EResult::EOS_Success 로 완료될 때까지 변경 사항은 사용자의 현재상태에 반영되지 않습니다.
서식 있는 텍스트 문자열 수정하기
서식 있는 텍스트 문자열을 새로 설정하려면 유효한 EOS_HPresenceModification 핸들로 EOS_PresenceModification_SetRawRichText 를 호출하고 다음과 같이EOS_PresenceModification_SetRawRichText 구조를 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PRESENCE_SETRAWRICHTEXT_API_LATEST |
RichText | EOS_PRESENCE_RICH_TEXT_MAX_VALUE_LENGTH 의 바이트 크기보다 작으면서 null이 아닌 문자열입니다. |
성공하면 EOS_PresenceModification_SetRawRichText 는 EOS_EResult::EOS_Success 를 반환합니다. 그렇지 않으면 요청에서 발생한 문제를 설명하는 오류 코드를 반환합니다. EOS_Presence_SetPresence 호출이 EOS_EResult::EOS_Success 로 완료될 때까지 변경 사항은 사용자의 현재상태에 반영되지 않습니다.
현재상태 데이터 추가 또는 교체하기
사용자의 현재상태에 기존 현재상태 데이터를 추가하거나 교체하려면 유효한 EOS_HPresenceModification 핸들로 EOS_PresenceModification_SetData 를 호출하고 다음과 같이 EOS_PresenceModification_SetDataOptions 구조를 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PRESENCE_SETDATA_API_LATEST |
RecordsCount | Records 에 EOS_Presence_DataRecord 가 얼마나 많이 있는지를 나타냅니다. Records 는 최소 RecordsCount 길이인 EOS_Presence_DataRecord 의 배열에 대한 포인터여야 합니다. |
EOS_Presence_DataRecord 를 다음과 같이 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PRESENCE_DATARECORD_API_LATEST |
Key | EOS_PRESENCE_DATA_MAX_KEY_LENGTH 의 바이트 크기보다 작으면서 null이 아닌 문자열입니다. |
Value | EOS_PRESENCE_DATA_MAX_VALUE_LENGTH 의 바이트 크기보다 작으면서 null이 아닌 문자열입니다. |
참고: 동일한 키를 가진 DataRecords 가 여러 개 있는 상황처럼 값이 충돌하는 경우 Records 배열의 최종 충돌 값이 사용됩니다.
성공하면 EOS_PresenceModification_SetData 는 EOS_EResult::EOS_Success 를 반환합니다. 그렇지 않은 경우 요청에서 발생한 문제를 설명하는 오류 코드를 반환합니다. EOS_Presence_SetPresence 호출이 EOS_EResult::EOS_Success 로 완료될 때까지 변경 사항은 사용자의 현재상태에 반영되지 않습니다.
현재상태 데이터 삭제하기
EOS_PresenceModification_SetData 와 유사하게 EOS_PresenceModification_DeleteData 는 이전에 설정한 데이터 키와 일치하는 현재상태 데이터를 제거합니다. 현재상태 데이터를 제거하려면 유효한 EOS_HPresenceModification 핸들로 EOS_PresenceModification_DeleteData 를 호출하고 다음과 같이 EOS_PresenceModification_DeleteDataOptions 구조를 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PRESENCE_DELETEDATA_API_LATEST |
RecordsCount | Records 에 EOS_PresenceModification_DataRecordId 가 얼마나 많이 있는지를 나타냅니다. Records 는 EOS_PresenceModification_DataRecordId 배열에 대한 포인터여야 합니다. |
EOS_PresenceModification_DataRecordId 를 다음과 같이 초기화합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PRESENCE_DELETEDATA_API_LATEST |
Key | EOS_PRESENCE_DATA_MAX_KEY_LENGTH 의 바이트 크기보다 작으면서 null이 아닌 문자열입니다. |
키에 삭제 표시를 했지만 키가 존재하지 않는 경우, 보류 중인 현재상태를 수정하는 이 프로세스 부분은 조용히 무시됩니다. 또한, 여러 개의 키가 동일한 키를 삭제하도록 설정된 경우 여분의 키는 조용히 무시됩니다.
성공하면 EOS_PresenceModification_DeleteData 는 EOS_EResult::EOS_Success 를 반환합니다. 그렇지 않으면 요청에서 발생한 문제를 설명하는 오류 코드를 반환합니다. EOS_Presence_SetPresence 호출이 EOS_EResult::EOS_Success 로 완료될 때까지 변경 사항은 사용자의 현재상태에 반영되지 않습니다.
현재상태 JoinInfo 데이터 설정하기
EOS_PresenceModification_SetJoinInfo 헬퍼 함수는 지정된 참여 정보(Join Info) 스트링을 사용하여 EOS_JoinInfo 현재상태 데이터 키를 설정합니다. 이 데이터는 EOS_Presence_GetJoinInfo 함수를 사용하여 가져올 수도 있습니다. 이 데이터는 EOS 소셜 오버레이(EOS Social Overlay)의 게임 참여(Join Game) 기능을 호출할 때 게임에 전송되며, 타이틀에 적절한 사항에 따라 사용자의 경기나 파티를 찾고 참여하기 위해 게임에 필요한 정보가 포함되어야 합니다.
EOS_PresenceModification_SetJoinInfo 함수를 성공적으로 호출하려면 유효한 EOS_HPresenceModification 핸들로 호출되어야 하며 유효한 EOS_PresenceModifcation_SetJoinInfoOptions 구조를 다음과 같이 초기화해야 합니다.
| 파라미터 | 설명 |
|---|---|
ApiVersion | EOS_PRESENCEMODIFICATION_SETJOININFO_API_LATEST 로 설정합니다. |
JoinInfo | 최대 EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH 바이트 길이의 null 종료 문자열로, null 종료 문자는 포함하지 않습니다. |
PresenceModification 변경 사항 적용하기
EOS_HPresenceHandle 에 모든 변경 사항이 적용되면 이러한 변경 사항은 유효한 EOS_HPresence 핸들, ClientData 필드 옵션, EOS_Presence_SetPresenceCompleteCallback 콜백 함수로 EOS_Presence_SetPresence 를 호출하여 사용자에게 적용되어야 합니다. 콜백 함수에는 ClientData 파라미터의 값이 포함됩니다. 또한, EOS_Presence_SetPresenceOptions 구조를 제공하고 다음과 같이 초기화해야 합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PRESENCE_SETPRESENCE_API_LATEST |
LocalUserId | 현재상태를 수정한 로컬 사용자입니다. |
PresenceModificationHandle | 보류 중인 변경 사항이 있는 EOS_HPresenceModification 핸들입니다. |
EOS_Presence_SetPresence 호출 직후에 EOS_HPresenceModification 핸들을 릴리즈해도 안전하지만 오류가 생기면 변경 사항이 손실될 수 있습니다. 콜백 함수가 결과 코드를 반환하는 데 성공하거나 변경 사항을 취소하고 싶을 때까지 이 핸들을 유지하는 것을 권장합니다. 또한 단일 사용자가 고유 현재상태 데이터의 EOS_PRESENCE_DATA_MAX_KEYS 를 초과 보유하는 것은 유효하지 않으며, 이 고유한 현재상태 데이터보다 더 많이 설정하려는 시도는 실패하게 됩니다.
완료되면 콜백 함수는 다음을 포함하는 EOS_Presence_SetPresenceCompleteInfo 구조로 호출됩니다.
| 프로퍼티 | 설명 |
|---|---|
ResultCode | 호출의 결과 코드입니다. |
ClientData | ClientData 파라미터의 클라이언트 데이터입니다. |
AccountId | 호출을 발생시킨 로컬 사용자의 계정 ID 값입니다. |
한 프레임에서 여러 개의 EOS_Presence_SetPresence 호출이 발생하면 호출들이 자동으로 결합될 수 있습니다. 모든 호출에 대한 콜백 함수는 여전히 개별적으로 호출되지만 ResultCode 를 공유할 수 있습니다. 하나 또는 복수의 수정 사항에서 상태가 두 번 설정되는 등 수정 내용이 충돌하는 경우 마지막으로 설정된 필드가 이전 변경 사항을 덮어씁니다.
소셜 오버레이 알림 구독하기
EOS_Presence_AddNotifyJoinGameAccepted / EOS_Presence_RemoveNotifyJoinGameAccepted 쌍을 통해 JoinGameAccepted 이벤트 등의 소셜 오버레이(Social Overlay) 관련 알림을 구독할 수도 있습니다. 자세한 내용은 소셜 오버레이 페이지를 참고하세요.