Presence インターフェース

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

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

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

コールバック関数は、ここでユーザーが指定する 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 構造体を次のように初期化します。

成功した場合、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 を呼び出します。

成功してデータが見つかった場合は、EOS_Presence_HasPresence により EOS_TRUE が返されます。あるいは、不正な入力を受け取り、キャッシュにターゲット ユーザーのデータが含まれていない場合は、EOS_FALSE が返されます。

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

Presence インターフェースがキャッシュから情報のコピーを正常に取得した場合、EOS_Presence_CopyPresence は EOS_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 構造体を以下のように初期化します。

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_HPresence ハンドル、初期化された EOS_Presence_CreatePresenceModificationOptions 構造体、および無効な EOS_HPresenceModification ハンドルへのポインタを使用して、EOS_Presence_CreatePresenceModification を呼び出すことで、PresenceModification ハンドルを作成します。EOS_Presence_CreatePresenceModificationOptions 構造体を次のように初期化します。

成功した場合、EOS_Presence_CreatePresenceModification 関数は、EOS_EResult::EOS_Success を返し、EOS_PresenceModification サンドボックスで関数と併用するために OutPresenceModificationHandle が初期化されます。また、結果のハンドルが不要になった場合は、そのハンドルを EOS_PresenceModification_Release メソッドを呼び出して解放する必要があります。

有効な EOS_HPresenceModification を使用すると、EOS_PresenceModification 関数のサンドボックス内で関数を呼び出すことによって、ユーザーのプレゼンスの更新を作成できます。

新しいステータスを設定するには、有効な EOS_HPresenceModification ハンドルを使用して、EOS_PresenceModification_SetStatus を呼び出し、次のように EOS_PresenceModification_SetStatusOptions 構造体を初期化します。

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

新しいリッチ テキスト文字列を設定するには、有効な EOS_HPresenceModification ハンドルを使用して EOS_PresenceModification_SetRawRichText を呼び出し、次のように EOS_PresenceModification_SetRawRichText 構造体を初期化します。

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

既存のプレゼンス データをユーザーのプレゼンスに追加または置き換えるには、有効な EOS_HPresenceModification ハンドルを使用して EOS_PresenceModification_SetData を呼び出し、次のように EOS_PresenceModification_SetDataOptions 構造体を初期化します。

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

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

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

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

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

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

ヘルパ関数 EOS_PresenceModification_SetJoinInfo は指定された Join Info 文字列を使って EOS_JoinInfo プレゼンス データを設定します。データは EOS_Presence_GetJoinInfo 関数を使っても取得することができます。EOS Social Overlay の Join Game 機能を呼び出すとデータはゲームへ送信され、タイトルに合わせて、ユーザーのマッチまたはパーティを探してジョインさせるためにゲームが必要とする情報を含みます。

EOS_PresenceModification_SetJoinInfo 関数を正常に呼び出すには、有効な EOS_HPresenceModification ハンドルと、以下のように初期化された有効な EOS_PresenceModifcation_SetJoinInfoOptions 構造体で呼び出される必要があります。

EOS_HPresenceHandle に対するすべての変更が行われたら、有効な EOS_HPresence ハンドル、オプションの ClientData フィールド、EOS_Presence_SetPresenceCompleteCallback コールバック関数を使用して EOS_Presence_SetPresence を呼び出すことによってユーザーに変更を適用する必要があります。コールバック関数では、ClientData パラメータの値を含みます。以下のように初期化した EOS_Presence_SetPresenceOptions 構造体も提供する必要があります。

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

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

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

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