Presence インターフェース

ユーザーが自分の現在の活動をフレンドに知らせることができるインターフェースです。

Presence インターフェース を使用すると、アプリケーションで、プレゼンスと呼ばれるローカル プレーヤーのステータスをアドバタイズしたり、他のプレイヤーのオンラインでのプレゼンス (存在) をクエリしたりできます。また、アプリケーションでは、ローカル プレイヤーの状態に関する詳細情報を共有するために、一時的なデータを他のユーザーにアドバタイズすることもできます。フレンド である他のユーザーに関するプレゼンス情報のみを受信できます。

Presence インターフェースを使用するには、Epic Account Services (EAS) をアクティブにし、ユーザー同意 を取得して Online Presence データにアクセスする必要があります。EAS は Developer Portal 上で有効にすることができます。詳細は「Epic のドキュメント」を参照してください。EAS およびユーザー同意がなくても、EOS SDK および Presence インターフェースの初期化を行うことができますが、バックエンド サービスへのすべての Presence インターフェース機能呼び出しは失敗します。

プレゼンス情報を管理する

Presence インターフェース を使用するには、Platform インターフェース 関数 EOS_Platform_GetPresenceInterfaceEOS_HPresence 型のハンドルを取得する必要があります。このハンドルを使用すると、フレンド リストの他のユーザーに関するプレゼンス情報をダウンロードしてキャッシュしたり、自分のプレゼンスを更新したりできます。

プレゼンス情報を取得してキャッシュする

ユーザーに関するプレゼンス情報を取得するには、EOS_Presence_QueryPresenceOptions 構造体、オプションの ClientData パラメータ、およびコールバック関数を使用して EOS_Presence_QueryPresence を呼び出します。次のフィールド値を使用して、EOS_Presence_QueryPresenceOptions を初期化します。

プロパティ

ApiVersion

EOS_FRIENDS_QUERYPRESENCE_API_LATEST

LocalUserId

リクエストをしているログイン ユーザーの EOS_EpicAccountId

TargetUserId

プレゼンス データを取得する対象のユーザーの EOS_EpicAccountId

この値は、LocalUserId に一致するか、そのユーザーのフレンドである必要があります。

コールバック関数は、ここでユーザーが指定する The callback function will receive the ClientData パラメータを受け取り、成功または失敗にかかわらず、操作の完了後に実行されます。唯一の例外は、EOS_Presence_QueryPresenceOptions 構造体に必要な情報が不足していることにより、この呼び出しがローカルで失敗した場合です。ターゲット ユーザーのプレゼンスを表示する権限がないために失敗した場合、コールバック関数の ResultCode フィールドは EOS_NotFound になります。EOS_Success を除き、その他すべての値は、パラメータが無効であるか、LocalUserId がローカルのログイン ユーザーに一致しないか、またはローカル ユーザーがオフラインであるなど、入力または状態の失敗を示します。

プレゼンス情報を更新する

ローカル キャッシュのプレゼンス情報を更新するには 2 つの方法があります。1 つ目は、EOS_Presence_QueryPresence を定期的にまたはキャッシュにアクセスする直前に呼び出す方法です。2 つ目は、変更発生時に Presence インターフェースから通知を受け取る方法です。この機能を有効にするには、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 が返されます。

この機能を無効にするには、EOS_Presence_RemoveNotifyOnPresenceChanged を呼び出して、プレゼンス ハンドルと通知 ID をパラメータとして渡します。この関数では、以前 EOS_Presence_AddNotifyOnPresenceChanged を使用して登録されたハンドルへの通知を停止します。

1 度に複数のコールバックを登録することができます。このケースでは、イベントが発生するとすべてのコールバックを呼び出すことができます。

プレゼンス情報を調査する

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 では、キャッシュのプレゼンス情報のコピーを提供します。Presence インターフェースでは、データを新しい EOS_Presence_Info オブジェクトとして返します。この関数では、新しい EOS_Presence_Info オブジェクトを保持するために、Presence インターフェースのハンドル、EOS_Presence_CopyPresenceOptions 構造体、および出力パラメータが必要です。EOS_Presence_CopyPresenceOptions 構造体を次のように初期化します。

プロパティ

ApiVersion

EOS_FRIENDS_COPYPRESENCE_API_LATEST

LocalUserId

リクエストをしているログイン ユーザーの EOS_EpicAccountId

TargetUserId

コピーする対象のユーザーのキャッシュされたプレゼンス データの EOS_EpicAccountId

Presence インターフェースがキャッシュから情報のコピーを正常に取得した場合、EOS_Presence_CopyPresenceEOS_Success を返し、ユーザーが指定した EOS_Presence_Info ポインタにターゲット ユーザーのデータのコピーを入力します。呼び出し元がこのポインタを所有しているため、EOS SDK により、このポインタの内容が変更されたり、関連付けられているメモリが解放されたりすることはありません。このデータを解放する必要がなくなったら、ポインタを使用して、EOS_Presence_Info_Release を呼び出します。これを実行しないと、メモリ リークが発生します。

EOS_Presence_GetJoinInfo によって、リモート ユーザーのプレゼンス データから以前に設定した Join Info 文字列を簡単に取得することができます。この関数を成功させるには、ユーザーのプレゼンス データはすでにプレゼンス キャッシュになければなりません。この関数は Presence インターフェース EOS_Presence_GetJoinInfoOptions 構造体、OutBuffer を Char バッファへのポインタに、そして InOutBufferLength を Char バッファを最長に設定することを求めます。EOS_Presence_GetJoinInfoOptions 構造体を以下のように初期化します。

パラメータ

説明

ApiVersion

Set this to EOS_PRESENCE_GETJOININFO_API_LATEST

LocalUserId

リクエストをしているログイン ユーザーの EOS_EpicAccountId。

TargetUserId

Join Info を取得する対象のユーザーの EOS_EpicAccountId。

この値はログインしているローカル ユーザー、または LocalUserId のフレンドである必要があります。

OutBuffer Char バッファの長さは EOS_PRESENCEMODIFICATION_JOININFO_MAX_LENGTH を推奨します。中には短すぎて格納できない値もあるので、リクエストが失敗します。

注記: プレゼンス情報の更新は、EOS_Presence_AddNotifyOnPresenceChanged を使用する場合でさえ、既存の EOS_Presence_Info オブジェクトに反映されません。これらのオブジェクトはキャッシュのポインタではなくてキャッシュ データにコピーされ、Presence インターフェースはそれらを所有せず初期コピー後にそれらを変更しないためです。

ローカル プレゼンスを変更する

ローカル ユーザーのプレゼンスを変更するには、EOS_HPresenceModification ハンドルを作成し、次の関数を 1 つ以上呼び出して変更を設定する必要があります。

  • EOS_PresenceModification_SetStatus

  • EOS_PresenceModification_SetRawRichText

  • EOS_PresenceModification_SetData

  • EOS_PresenceModification_DeleteData

  • EOS_PresenceModification_SetJoinInfo

注意: 注:変更は EOS_Presence_SetPresence への呼び出しの成功後に反映されます。

PresenceModification ハンドルを作成する

ローカル ユーザーのプレゼンスを変更するには、まず、有効な EOS_HPresence ハンドル、初期化された EOS_Presence_CreatePresenceModificationOptions 構造体、および無効な EOS_HPresenceModification ハンドルへのポインタを使用して、EOS_Presence_CreatePresenceModification を呼び出すことで、PresenceModification ハンドルを作成します。EOS_Presence_CreatePresenceModificationOptions 構造体を次のように初期化します。

プロパティ

ApiVersion

EOS_PRESENCE_CREATEPRESENCEMODIFICATION_API_LATEST

LocalUserId

ログイン状態の有効なローカル ユーザー。

成功した場合、EOS_Presence_CreatePresenceModification 関数は、EOS_EResult::EOS_Success を返し、EOS_PresenceModification 名前空間で関数と併用するために OutPresenceModificationHandle が初期化されます。また、結果のハンドルが不要になった場合は、そのハンドルを 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_SetStatusEOS_EResult::EOS_Success を返します。その他の場合は、リクエストに関する問題を説明するエラー コードを返します。EOS_EResult::EOS_Success を使って EOS_Presence_SetPresence への呼び出しが完了するまで変更はユーザーのプレゼンスに反映されません。

リッチ テキスト文字列を変更する

新しいリッチ テキスト文字列を設定するには、有効な 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_SetRawRichTextEOS_EResult::EOS_Success を返します。その他の場合は、リクエストに関する問題を説明するエラー コードを返します。EOS_EResult::EOS_Success を使って EOS_Presence_SetPresence への呼び出しが完了するまで変更はユーザーのプレゼンスに反映されません。

プレゼンス データを追加または置き換える

既存のプレゼンス データをユーザーのプレゼンスに追加または置き換えるには、有効な 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_SetDataEOS_EResult::EOS_Success を返します。その他の場合は、リクエストに関する問題を説明するエラー コードを返します。EOS_EResult::EOS_Success を使って EOS_Presence_SetPresence への呼び出しが完了するまで変更はユーザーのプレゼンスに反映されません。

プレゼンス データを削除する

EOS_PresenceModification_SetData と同様に、EOS_PresenceModification_DeleteData では、以前に設定したデータのキーと一致するプレゼンス データを削除します。プレゼンス データを削除するには、有効な EOS_HPresenceModification ハンドルを使用して EOS_PresenceModification_DeleteData を呼び出し、次のように 構造体を初期化します。

プロパティ

ApiVersion

EOS_PRESENCE_DELETEDATA_API_LATEST

RecordsCount

Records に存在する EOS_PresenceModification_DataRecordId の数です。Records は最低でも RecordsCount の長さのある EOS_PresenceModification_DataRecordId の配列へのポインタでなければなりません。

以下を使用して EOS_PresenceModification_DataRecordId を初期化します。

プロパティ

ApiVersion

EOS_PRESENCE_DELETEDATA_API_LATEST

Key

EOS_PRESENCE_DATA_MAX_KEY_LENGTH のバイト サイズより小さい null 以外の文字列。

キーが削除対象としてマークされているものの、存在しない場合、保留中のプレゼンス変更プロセスのこの部分はメッセージを表示することなく無視されます。また、複数のキーが同じキーを削除するように設定されている場合、余分なキーはメッセージを表示することなく無視されます。

成功すると、EOS_PresenceModification_DeleteDataEOS_EResult::EOS_Success を返します。その他の場合は、リクエストに関する問題を説明するエラー コードを返します。EOS_EResult::EOS_Success を使って EOS_Presence_SetPresence への呼び出しが完了するまで変更はユーザーのプレゼンスに反映されません。

Presence JoinInfo Data を設定する

ヘルパ関数 EOS_PresenceModification_SetJoinInfo は指定された Join Info 文字列を使って EOS_JoinInfo プレゼンス データを設定します。データは EOS_Presence_GetJoinInfo 関数を使っても取得することができます。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 バイトの ヌル終焉文字列 (ヌル ターミネータは含みません)。

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 ハンドルを解放すると安全です。ただし、エラーがある場合、変更が失われる可能性があります。コールバック関数により成功の結果コードが返されるまで、または変更を放棄したい場合は、このハンドルを維持することをお勧めします。また、1 人のユーザーが、一意のプレゼンス データの複数の EOS_PRESENCE_DATA_MAX_KEYS を持つことは無効であり、さらに一意のプレゼンス データ キーを設定しようとしても失敗します。

完了すると、コールバック関数が以下を含む EOS_Presence_SetPresenceCompleteInfo 構造体を使用して呼び出されます。

プロパティ

説明

ResultCode

呼び出しの結果コードです。

ClientData

ClientData パラメータのクライアント データです。

AccountId

呼び出しを起動したローカル ユーザーのアカウント ID の値です。

単一のフレームの間に EOS_Presence_SetPresence への呼び出しが複数発生した場合は、それらの呼び出しは自動的に結合されます。すべての呼び出しのためのコールバック関数は、引き続き個別に呼び出されるものの、それらのコールバック関数では`ResultCode` を共有します。1 つ (または複数) の変更にわたってステータスが 2 回設定されるなど、競合する変更がある場合、last-set フィールドにより前の変更が上書きされます。

Social Overlay 通知へサブスクライブする

EOS_Presence_AddNotifyJoinGameAccepted/EOS_Presence_RemoveNotifyJoinGameAccepted ペアを使って、JoinGameAccepted イベントなど Social Overlay に関係する通知へサブスクライブすることも可能です。詳細については「Social Overlay」ページを参照してください。