データセッション

LINE Planetは、アプリケーションがデータをやり取りするためのデータセッションを提供します。グループ通話（カンファレンス）中にテキストメッセージを送ったり、受信したりするのがその例です。

このとき、データ通信プロトコルはアプリケーション側で定義する必要があることにご注意ください。LINE Planetが提供するデータセッションは、アプリケーションが定義したデータ通信プロトコルのための通信チャネルとしてのみ機能します。

対応する通話タイプ	SDKの最低バージョン
1対1通話、グループ通話	PlanetKit 3.3

Note

• LINE Planetは、リアルタイム通信プラットフォームです。インターネットでは、ネットワークの状態によってパケットが失われたり、遅延したりすることがあり、リアルタイム通信を保証しません。ネットワークの障害は、リアルタイム通信の品質に影響を与え、深刻な場合通話が中断されることもあります。また、トラフィックが多い場合、各種ネットワーク障害が発生する可能性もあります。アプリケーションがデータセッションを使用する場合、データ通信が音声通話またはビデオ通話の品質を低下させる可能性があることにご注意ください。
• データセッションは、コールセットアップ（call setup）が完了した後、またはグループ通話に参加した後のみ使用できます。

データセッションの仕様

データセッションAPIには送信側と受信側があります。両者のアプリケーションは、事前に定義した ストリームIDでデータセッションをリクエストする必要があります。「事前に定義した」とは、実装段階に入る前に両者がストリームIDの値について協議していることを意味します。

ストリームID

ストリームIDは、各アプリケーションが設計段階で定義したデータ通信識別子です。ストリームIDの特長は次のとおりです。

• ストリームIDは動的に生成されません。ストリームIDは、アプリケーションの設計段階で割り当てられ、サービス運営全般に渡って一定に維持されます。これは、受信者が特定のストリームIDを処理できない場合に、アプリケーションがそのストリームIDの使用を中止しなければならないことを意味します。
• ストリームIDは100から999までの整数から選択する必要があります。
• 1つのストリームIDを送信側と受信側で使用できます。これは、双方向通信で同じ識別子を使用して双方向にデータが流れることを意味します。

サブグループのサポート

サブグループに属するデータセッションは、サブグループメンバー間でデータをやり取りするのに使用できます。同じストリームIDを使用しても、サブグループが異なれば、別のデータセッションを定義して使用することになります。

サブグループは、サブグループ名で区別します。サブグループ名がNullOptionalの場合、メインルーム（main room）という意味です。

Note

• アプリケーションでサブグループ内のデータセッションを使用するには、サブグループのプロパティ「dataSession」の値を必ずtrueに設定する必要があります。
• サブグループ内のデータセッションの使用は、PlanetKit 4.1以上のバージョンからサポートします。

サブグループについて詳しくは、サブグループカテゴリーのドキュメントを参照してください。

データセッションのライフタイム

通話タイプによるデータセッションのライフタイムは次のとおりです。

• 1対1通話
  • データセッションを作成すると、通話が終了するまで有効な状態を維持します。
• グループ通話 - メインルームのデータセッション
  • データセッションを作成すると、グループ通話が終了するまで有効な状態を維持します。
• グループ通話 - サブグループのデータセッション
  • 特定のサブグループ用のデータセッションを作成すると、データセッションを作成した参加者がサブグループに加入している間は有効な状態を維持します。その参加者がサブグループから退会すると、そのデータセッションは無効になります。

データセッションのタイプ

データセッションのタイプは以下のとおりです。アプリケーションは、データの特性によって使用するタイプを決定する必要があります。

データセッションのタイプ	説明
Reliable message	損失されたパケットを再送します。 各メッセージがの再組み立て時に、OnReceive コールバックが呼び出されるため、このコールバックはSend()が呼び出された回数分だけ呼び出されます。
Unreliable message	損失されたパケットを再送しません。 各メッセージの再組み立て時に、OnReceiveコールバックが呼び出されます。パケット損失がなければ、このコールバックがSend()と同じ回数で呼び出されますが、パケット損失が発生した場合はコールバックの呼び出し回数はSend()の呼び出し回数よりも少なくなる可能性があります。
Reliable bytes	損失されたパケットを再送します。 PlanetKitは、アプリケーションデータが大きい場合、それを分解します。ただし、受信側ではパケットの再組み立てをしないため、アプリケーションが分解されたパケットを組み立て直す必要があります。
Unreliable bytes	損失されたパケットを再送しません。 PlanetKitは、アプリケーションデータが大きい場合、それを分解します。ただし、受信側ではパケットの再組み立てをしないため、アプリケーションが分解されたパケットを組み立て直す必要があります。

データセッションの最大転送帯域幅

データセッションは、2Mbps以上のデータを送信できません。データセッションの帯域幅がオーディオまたはビデオの品質を低下させる可能性があるためです。そのため、PlanetKitはデータ送信速度（data rate）を制御します。アプリケーションが過剰なトラフィックを送る場合、PlanetKitはアプリケーションに対してデータの転送を遅らせることを知らせるために例外（exception）イベントを生成します。

送信側

送信側のAPIと操作について説明します。

送信側API

送信側では以下のAPIを使用します。

API	説明
MakeOutboundDataSession()	ストリームIDを使用してアウトバウンドデータセッションを作成する
GetOutboundDataSession()	以前作成されたアウトバウンドデータセッションをインポートする
Send()	アウトバウンドデータセッションを使用してデータを送信する
ChangeDestination()	データの送信先を変更する

アウトバウンドデータセッションの作成

アウトバウンドデータセッションを作成するには、MakeOutboundDataSession()を使用します。

virtual bool MakeOutboundDataSession(
    int nStreamId,
    EDataSessionType eType,
    NULLABLE void* pResultUserData,
    IOutboundDataSessionHandler* pDataSessionHandler
) = 0;

パラメーター	説明
nStreamId	アプリケーションで定義したストリーム識別子。詳しくは、ストリームIDを参照してください。
eType	データセッションタイプ。詳しくは、データセッションタイプを参照してください。
pResultUserData	pDataSessionHandlerが呼び出されたときに伝えられるユーザーデータ
pDataSessionHandler	データセッションに対するコールバックハンドラー

アウトバウンドデータセッションの作成結果はpDataSessionHandlerのコールバックで確認できます。

• アウトバウンドデータセッションの作成に成功すると、OnSuccessが呼び出されます。
• アウトバウンドデータセッションを作成できなかった場合は、失敗の理由と共にOnErrorが呼び出されます。詳しくは、データセッションの失敗理由を参照してください。

アウトバウンドセッションが作成された後、OnTooLongQueuedDataは、データトラフィックの状態を知らせます。下表の内容を参考に、アプリケーションで必要な処理を行ってください。

イベント	説明	アプリケーションに必要な処理
OnTooLongQueuedData (bEnabled =true)	データ使用量が多すぎます。	データ送信を中断するか、ビットレートを下げて送信してください。
OnTooLongQueuedData (bEnabled =false)	ネットワーク状態が改善されました。	もっと多くのデータを送信してください。

Note

OnTooLongQueuedDataイベントが継続的に発生すると、音声および映像の通信品質に悪影響を及ぼす可能性があります。これを緩和するには、データ送信ビットレートを下げる必要があります。

アウトバウンドデータセッションのインポート

既存のアウトバウンドデータセッションをインポートするには、GetOutboundDataSession()を使用します。

virtual bool GetOutboundDataSession(int nStreamId, OutboundDataSessionPtr* pResult) = 0;

パラメーター	説明
nStreamId	ストリームID。詳しくは、ストリームIDを参照してください。
pResult	インポートしたアウトバウンドデータセッション

データを送信する

アウトバウンドデータセッションを使用してデータを送信するには、OutboundDataSession::Send()を使用します。

 virtual bool Send(const void* pData, unsigned int nDataSize, unsigned long long llTimestamp) = 0;

パラメーター	説明
pData	送信するデータ。「Message」タイプの最大サイズは128KB、その他のタイプの最大サイズは、4MBです。
nDataSize	データのサイズ
llTimestamp	データを識別するためのユーザー定義のタイムスタンプ

データの送信先の変更

データの送信先を変更するには OutboundDataSession::ChangeDestination()を使用します。

Note

このメソッドは、グループ通話でのみ有効です。

virtual bool ChangeDestination(UserIdPtr pPeerId, void* pUserData = nullptr, ResultCallback pCallback = nullptr) = 0;

パラメーター	説明
pPeerId	データを受信するピア。nullptrに設定すると、次のような効果があります。 - メインルームのデータセッションの場合、ルームのすべてのピアにデータを送信します。 - サブグループデータセッションの場合、すべてのサブグループメンバーにデータを送信します。
pUserData	pResultHandlerのためのユーザーデータ
pCallback	結果コールバック関数

受信側

このセクションでは、受信側のAPIと操作について説明します。

受信側 API

受信側では以下のAPIを使用します。

API	説明
OnDataSessionIncoming	送信側で新たにアウトバウンドデータセッションを作成したときに呼び出される
MakeInboundDataSession()	データを受信するためのインバウンドデータセッションを作成する
GetInboundDataSession()	以前作成されたインバウンドデータセッションをインポートする
UnsupportInboundDataSession()	アプリケーションがストリームIDをサポートしていないことを送信側に通知する

新しいデータセッションについての通知を受信する

送信側で新しいデータセッションを作成すると、OnDataSessionIncomingを通じて受信側にイベントが通知されます。

// For 1-to-1 calls
virtual void OnDataSessionIncoming(DataSessionStreamIdT nStreamId, EDataSessionType eType) = 0;

// For group calls
virtual void OnDataSessionIncoming(const WStringOptional& strSubgroupName, DataSessionStreamIdT nStreamId, EDataSessionType eType) = 0;

パラメーター	説明
strSubgroupName	（グループ通話のみ）サブグループ名。NullOptionalはメインルームを指します。
nStreamId	発信者が設定したストリームIDです。詳しくは、ストリームIDを参照してください。
eType	データセッションタイプ。詳しくは、データセッションタイプを参照してください。

グループ通話で誰かがメインルームのデータセッションを使用してデータストリーミングを開始した後の参加者は、参加フローが完了してデータを受信するときにOnDataSessionIncomingも受信します。この場合、データセッションはメインルーム向けであるため、サブグループ名はNullOptionalです。

サブグループの場合、誰かがサブグループのデータセッションを使用してデータストリーミングを開始した後に加入したメンバーは、加入フローが完了してデータを受信する際に適切なサブグループ名と共にOnDataSessionIncomingも受信します。

インバウンドデータセッションの作成

インバウンドデータセッションを作成するには、MakeInboundDataSession()を使用します。

virtual bool MakeInboundDataSession(
    int nStreamId,
    NULLABLE void *pResultUserData,
    IInboundDataSessionHandler* pDataSessionHandler
) = 0;

パラメーター	説明
nStreamId	アプリケーションで定義したストリーム識別子。詳しくは、ストリームIDを参照してください。
pResultUserData	pDataSessionHandlerのためのユーザーデータ
pDataSessionHandler	データセッションに対するコールバックハンドラー

インバウンドデータセッションの作成結果はpDataSessionHandlerのコールバックで確認できます。

• インバウンドデータセッションの作成に成功すると、OnSuccessが呼び出されます。
• インバウンドデータセッションを作成できない場合は、失敗の理由と共にOnErrorが呼び出されます。詳しくは、データセッションの失敗理由を参照してください。

pDataSessionHandlerのOnReceiveでデータ受信イベント通知を受け取ることができます。

インバウンドデータセッションのインポート

既存のインバウンドデータセッションをインポートするには、GetInboundDataSession()を使用します。

virtual bool GetInboundDataSession(int nStreamId, InboundDataSessionPtr* pResult) = 0;

パラメーター	説明
nStreamId	ストリームID。詳しくは、ストリームIDを参照してください。
pResult	インポートしたインバウンドデータセッション

サポートされていないデータセッションを通知する

アプリケーションがストリームIDをサポートしていないことを送信側に通知するには、UnsupportInboundDataSession()を使用します。

virtual bool UnsupportInboundDataSession(DataSessionStreamIdT nStreamId) = 0;

パラメーター	説明
nStreamId	ストリームID。詳しくは、ストリームIDを参照してください。

OnDataSessionIncomingイベントで受信したストリームIDをアプリケーションが処理できない場合（つまり、ストリームIDが受信者に知られていない場合）、このメソッドを呼び出します。

• 1対1通話
  • 送信者は、データセッションの失敗理由「Unsupported」を通じてこのメソッドが呼び出されたことが分かります。その後送信者は、このストリームからデータの送信ができなくなります。
• グループ通話
  • 送信者は、複数の受信者がいるため、このメソッド呼び出されたことが分かりません。 -このメソッドを呼び出したアプリケーションのユーザーは、このストリームを通じてデータを受信しませんが、送信者はこのストリームを通じてデータを送り続けることができます。

データセッションの終了

データセッションが終了されると、IOutboundDataSessionHandler（送信側）またはIInboundDataSessionHandler（受信側）のOnClosedイベントが発生します。

OnClosedイベントは、eClosedReasonパラメーターを使用してデータセッションの終了理由を提供します。EDataSessionClosedReason列挙型で定義されているデータセッションの終了理由は次のとおりです。

列挙値	説明
PLNK_DATA_SESSION_CLOSED_REASON_SESSION_END	データセッションは正常に終了しました。
PLNK_DATA_SESSION_CLOSED_REASON_INTERNAL	内部で予期しないエラーが発生しました。
PLNK_DATA_SESSION_CLOSED_REASON_UNSUPPORTED	データセッションIDはピアでサポートされていません。

データセッションの失敗理由

データセッションの失敗理由（data session fail reason）を通じて、データセッションの作成結果と作成に失敗した理由が分かります。EDataSessionFailReason列挙型で定義されているデータセッションの失敗理由は次のとおりです。

列挙値	説明
PLNK_DATA_SESS_FAIL_REASON_NONE	データセッションの作成に成功しました。
PLNK_DATA_SESS_FAIL_REASON_INTERNAL	内部で予期しないエラーが発生しました。
PLNK_DATA_SESS_FAIL_REASON_NOT_INCOMING	データ受信イベント（OnDataSessionIncoming）なしではインバウンドデータセッションを作成できません。
PLNK_DATA_SESS_FAIL_REASON_ALREADY_EXIST	すでにデータセッションストリームIDが存在します。
PLNK_DATA_SESS_FAIL_REASON_INVALID_ID	データセッションストリームIDが正しくありません。
PLNK_DATA_SESS_FAIL_REASON_INVALID_TYPE	データセッションタイプが正しくありません。

Tip

データセッションの失敗理由は、PlanetKit 5.1以上のバージョンで使用できます。

データセッションの互換性

通話タイプによって次のようにデータセッションの互換性を確認できます。

• 1対1通話
  • OnConnectedが渡すCallConnectedParam::IsSupportDataSession()値からピアがデータセッションをサポートしているかどうかを確認できます。
• グループ通話
  • Peer::IsDataSessionSupported()値からピアがデータセッションをサポートしているかどうかを確認できます。

ピアがデータセッション機能をサポートしていても、特定のストリームIDを処理することは互換性の問題です。この問題は、ストリームIDの処理が実装されていない古いバージョンのクライアントで特定のストリームIDを処理することに関係があります。

以下のいずれかの方法で、特定のストリームIDの互換性問題を解決できます。

• 旧バージョンのクライアントでは、未知のストリームIDはUnsupportInboundDataSession()を呼び出してリジェクトする
• 旧バージョンのクライアントを開発する時点で、特定のストリームIDをreliableタイプの、互換性を検査するためのものとして割り当て、互換性検査のためのプロトコルを設計します。以降のバージョンのクライアントでは、これを活用して互換性の問題を希望する方法で解決します。

関連API

データセッション機能に関連するAPIは、以下のとおりです。

共通

• OutboundDataSession::Send()
• OutboundDataSession::ChangeDestination()
• IOutboundDataSessionHandler::OnTooLongQueuedData
• IOutboundDataSessionHandler::OnClosed
• IInboundDataSessionHandler::OnReceive
• IInboundDataSessionHandler::OnClosed
• EDataSessionClosedReason
• EDataSessionFailReason

1対1通話

• PlanetKitCall::MakeOutboundDataSession()
• PlanetKitCall::GetOutboundDataSession()
• PlanetKitCall::MakeInboundDataSession()
• PlanetKitCall::GetInboundDataSession()
• PlanetKitCall::UnsupportInboundDataSession()
• ICallEvent::OnDataSessionIncoming

グループ通話

• Subgroup::MakeOutboundDataSession()
• Subgroup::GetOutboundDataSession()
• Subgroup::MakeInboundDataSession()
• Subgroup::GetInboundDataSession()
• Subgroup::UnsupportInboundDataSession()
• IConferenceEvent::OnDataSessionIncoming