Sora に接続する¶

概要¶

Sora への接続処理の概要について記載しています。

接続の手順¶

サーバーへの接続は次の手順で行います。

Configuration を生成する。
Sora オブジェクトの connect(configuration:webRTCConfiguration:handler:) を呼ぶ。

    import Sora

    // シグナリング URL とチャネル ID を指定する
    let url = URL(string: "wss://sora.example.com/signaling")!
    let soraChannelId = "sora"
    let config = Configuration(url: url,
                                  channelId: soraChannelId,
                                  role: .recvonly,
                                  multistreamEnabled: false)

    // 接続する
    Sora.shared.connect(configuration: config) { mediaChannel, error in
        // 接続に失敗するとエラーが渡される。
        // 接続に成功すると error は nil
        if let error = error {
            // 接続エラー時の処理
            ...
        }

        // 接続成功時の処理
        // 映像を描画するビューをストリームにセットする等
        ...
    }
}

Configuration はサーバーへの接続情報などの設定を保持するオブジェクトです。サーバーの URL 、チャネル ID 、ロール、マルチストリームの可否をセットします。

次に Configuration を引数として Sora オブジェクトの connect(configuration:webRTCConfiguration:handler:) を呼びます。このとき Sora オブジェクトは Sora.shared プロパティでシングルトンを取得できます)。このメソッドはサーバーへの接続を行い、接続の成否に関わらず handler: に指定されたブロックを実行します。接続が成功すると MediaChannel がブロックの引数として渡されます。 MediaChannel は接続後の操作を行うためのオブジェクトです。

connect(configuration:webRTCConfiguration:handler:) のメソッドの型と引数は次の通りです。

func connect(configuration: Configuration,
             webRTCConfiguration: WebRTCConfiguration = WebRTCConfiguration(),
             handler: (_ mediaChannel: MediaChannel?, _ error: Error?) -> Void)

configuration: 接続情報です。シグナリング URL とチャネル ID を指定します。
webRTCConfiguration: WebRTC に関する設定です (省略可) 。このアプリケーションでは扱いません。
handler: 接続試行後に実行するブロックです。ブロックの型は (MediaChannel?, Error?) -> Void です。ブロックの引数は次の通りです。
- mediaChannel: 接続に成功するとメディアチャネルが渡されます。失敗時は nil です。
- error: 接続に失敗するとエラーが渡されます。成功時は nil です。

MediaChannel は映像データを扱うストリームを複数保持します。映像はストリームを通じて Web ブラウザやサーバーと送受信されます。

ストリームは送信か受信のいずれかを担当し、ロールによって扱う数が異なります。シングルストリームにおいて、送信と受信のストリームはそれぞれ 1 つです。つまり、シングルストリームでは 1 回の接続につき送信か受信かのいずれか一方しか行えません。 1 台の端末で映像の送受信を行う場合は、送信と受信で 2 回の接続が必要です。

接続後の映像の送受信については映像を描画するを参考にしてください

DataChannel 経由のシグナリング¶

Sora と DataChannel を経由したシグナリング通信を行うための接続方法について記載します。詳しい仕様は Sora のドキュメントを参照してください。

DataChannel 経由のシグナリングを有効にするには、 Configuration の dataChannelSignaling プロパティに true をセットしてください。 WebSocket が閉じたときに Sora に接続が切断されたと判断して欲しくない場合は ignoreDisconnectWebsocket プロパティに true をセットしてください。

var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv,
                           multistreamEnabled: true)

// DataChannel 経由のシグナリングを有効にする
config.dataChannelSignaling = true

// WebSocket が閉じたことを無視する
config.ignoreDisconnectWebsocket = true

イベントハンドラ¶

DataChannel に関するイベントハンドラは MediaChannelHndlers に用意しています。主なイベントハンドラは以下の通りです。

/// シグナリングが DataChannel 経由に切り替わったタイミングで呼ばれるクロージャー
public var onDataChannel: ((MediaChannel) -> Void)?

/// DataChannel のメッセージ受信時に呼ばれるクロージャー
public var onDataChannelMessage: ((MediaChannel, String, Data) -> Void)?

プロキシ・サーバーの設定¶

プロキシ・サーバーを経由した通信を行う場合は、 Configuration の proxy プロパティにプロキシ情報をセットしてください。

HTTP プロキシに対応しています
SOCKS プロキシも設定できますが、動作を確認していません
HTTP の CONNECT メソッドは HTTPS ではなく HTTP で送信します
Proxy-Authorization ヘッダーを利用した Basic 認証に対応しています
iOS の Wi-Fi に設定されたプロキシの項目を参照しません

var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv,
                           multistreamEnabled: true)

// proxy 情報の設定を行う
configuration.proxy = Proxy(host: "proxy.example.com",
                            port: 3128,
                            agent: nil,
                            username: "ham",
                            password: "egg")