RPC 機能¶

概要¶

RPC 機能は DataChannel 経由で Sora の一部 HTTP API をクライアント側から呼び出しを行うための仕組みです。

RPC 機能の詳細については Sora ドキュメントの RPC 機能 をご確認ください。

前提条件¶

RPC を使う前提は次のとおりです。

• Sora 接続が確立していること

  例: conn = Sora.createConnection() で作成した接続オブジェクトが、 conn.connect() で接続されている状態である

• 利用したいメソッド名が、 Sora から払い出された rpc_methods に含まれていること
• rpc DataChannel が使える状態になっていること

利用可能な RPC メソッド¶

利用可能なメソッド名は、 SoraSignalingMessageEvent イベント通知から取得することができます。 event.type が offer のとき、 event.data?['rpc_methods'] にメソッド名のリストが入ります。 またメソッドは Sora の認証ウェブフックで払い出されたものだけが含まれます。

conn.events.listen((event) {
  if (event case SoraSignalingMessageEvent(:final event)) {
    if (event.direction == 'received' &&
        event.data?['type'] == 'offer') {
      final methods = event.data?['rpc_methods'];
      if (methods is List) {
        for (final method in methods.whereType<String>()) {
          print(method);
        }
      }
    }
  }
});

RPC を送信する¶

RPC リクエストを送信するには rpc() を実行します。利用可能なメソッド名は、 offer の rpc_methods に含まれる文字列をそのまま使います。

// TimeoutException に必要
import 'dart:async';

try {
  final result = await conn.rpc(
    // サンプルのためダミーのメソッド名です
    'example.method',
    params: <String, Object?>{'value': 123},
    options: const SoraRpcOptions(timeout: 5000),
  );
  print(result);
} on SoraRpcError catch (error) {
  print('${error.code} ${error.message}');
} on TimeoutException {
  print('timeout');
}

await client.rpc(
  'example.notify',
  params: <String, Object?>{'message': 'hello'},
  options: const SoraRpcOptions(notification: true),
);

await conn.rpc(
  'RequestSimulcastRid',
  params: <String, Object?>{
    'channel_id': 'example-channel',
    'receiver_connection_id': conn.connectionId,
    'sender_connection_id': '',
    'rid': 'r1',
  },
);

await conn.rpc(
  'PutSignalingNotifyMetadataItem',
  params: <String, Object?>{
    'channel_id': 'example-channel',
    'connection_id': conn.connectionId,
    'key': 'display_name',
    'value': 'Alice',
  },
);

エラーハンドリング¶

• サーバーから RPC エラーが返ると SoraRpcError
• タイムアウトを超えると TimeoutException
• 切断時は待機中の RPC が SoraRpcError(code: -1, message: 'Disconnected') で完了

import 'dart:async';

try {
  await client.rpc(
    'example.method',
    options: const SoraRpcOptions(timeout: 3000),
  );
} on SoraRpcError catch (error) {
  print(error);
} on TimeoutException {
  print('timeout');
}