Core BluetoothのL2CAP関連のドキュメントを全部読む - APIリファレンス編

Core Bluetooth の L2CAP ^[1] 関連の公式情報はかなり少ない。WWDC 2017のセッション "What's New in Core Bluetooth" で言及はあったもののもう公式では動画は公開されていないし、サンプルは認識している限りでは公式では出てなくて、APIリファレンスがほぼ唯一に近い貴重な一次情報となっている。

そんな希少な一次情報を一通り網羅して把握すべく、Core BluetoothのL2CAP関連の全APIについてApple公式ドキュメント（APIリファレンス）の記載を集めてみた。

• ストリーム系等、Core Bluetoothフレームワーク外のものは割愛。
• 翻訳は基本的にはDeepL頼みだが、"peripheral manager" → 「周辺管理者」のような読みにくい翻訳結果は適宜修正

本記事は2023年4月に noteのマガジン に書いた「[Core Bluetooth] L2CAP関連のAPIリファレンスを全部読む」という記事をリライトしたものであり、引用しているAPIリファレンスの記載も2023年4月当時のものとなっています。もし記載が古くなっている箇所に気付いた方はコメントなりDMなりでご指摘いただけると嬉しいです。

また本記事は「APIリファレンス編」としているが、もう1つの一次情報であるWWDC 2017の"What's New in Core Bluetooth"についても、同セッションでL2CAPについて言及のある箇所のトランスクリプトとスライドを別記事にてまとめたいと思っている。

CBPeripheralManager

publishL2CAPChannel(withEncryption:)

func publishL2CAPChannel(withEncryption encryptionRequired: Bool)

Creates a listener for incoming L2CAP channel connections.

引数：

encryptionRequired
true if the service requires link encryption before a stream can be established. false if the service supports use over an unsecured link.

サービスがストリームを確立する前にリンクの暗号化を必要とする場合はtrue、サービスが安全でないリンクでの使用をサポートする場合はfalse。

ディスカッション：

The system determines an unused Protocol and Service Multiplexer (PSM) at the time of publishing, and provides it to your app with peripheralManager(_:didPublishL2CAPChannel:error:). L2CAP channels aren’t discoverable by themselves, so it’s the app’s responsibility to handle PSM discovery on the client.

システムは、パブリッシュ時に未使用のPSM（Protocol and Service Multiplexer）を決定し、peripheralManager(_:didPublishL2CAPChannel:error:)でアプリに提供します。L2CAPチャンネルはそれ自体では発見できないので、クライアントでPSMの発見を処理するのはアプリの責任である。

メモ

• パブリッシュ時にPSM番号の指定はできない。
• ドキュメントに記載はないが、実行してみると初回はいつも PSM として 192 が発行される
  • 『システムは、パブリッシュ時に未使用のPSMを決定し』とあるので、同じデバイスで（前のPSMをunpublishしないまま）さらに次の L2CAP チャンネルをパブリッシュしようとすると違う番号のPSMが生成されるのだろう。

unpublishL2CAPChannel(_:)

func unpublishL2CAPChannel(_ PSM: CBL2CAPPSM)

Removes a published service from the local system.

引数：

PSM
The Protocol and Service Multiplexer (PSM) to remove from the system.

ディスカッション：

After you make this call, the peripheral manager accepts no new connections for this PSM, and closes any existing L2CAP channels using this PSM.

この呼び出しを行った後、ペリフェラルマネージャはこのPSMに対する新しい接続を受け付けず、このPSMを使用する既存のL2CAPチャネルを閉じます。

メモ

• CBPeripheral には openL2CAPChannel に対して close〜 というメソッドがないのだが（後述）、本メソッドのディスカッションには "closes any existing L2CAP channels using this PSM" とチャンネルを閉じる機能があることが明記されている。

• unpublishを行うことでチャンネルに紐づくストリームが自動的に閉じられるか、そうでないか、といったことは明記されていない。

  • リファレンスには明記されていないが、Streamのopen等は自分でする必要があるわけで、当然close等の後片付けも自分でする必要がある（勝手によしなにはやってくれない）

• CBPeripheralManager で add(_:) や startAdvertising(_:) も行う中で、どのようなタイミングでL2CAPのpublishやunpublishを行うべきか、についてはドキュメントでは明言されていない。

  • CBUUIDL2CAPPSMCharacteristicString をもつキャラクタリスティックの値にPSMを載せる必要があるのと、上述のunpublishによってチャンネルをcloseできる点が、publish/unpublishのタイミングを決めるポイントになる

CBPeripheralManagerDelegate

peripheralManager(_:didPublishL2CAPChannel:error:)

optional func peripheralManager(
    _ peripheral: CBPeripheralManager,
    didPublishL2CAPChannel PSM: CBL2CAPPSM,
    error: Error?
)

Tells the delegate that the peripheral manager created a listener for incoming L2CAP channel connections.

周辺マネージャが受信L2CAPチャネル接続のリスナーを作成したことをデリゲートに伝える。

ディスカッション

The peripheral manager calls this method after you call publishL2CAPChannel(withEncryption:). The PSM parameter contains the PSM assigned for the published channel.

publishL2CAPChannel(withEncryption:)を呼び出した後、ペリフェラルマネージャはこのメソッドを呼び出す。PSMパラメータには、公開されたチャネルに割り当てられたPSMが含まれます。

peripheralManager(_:didUnpublishL2CAPChannel:error:)

optional func peripheralManager(
    _ peripheral: CBPeripheralManager,
    didUnpublishL2CAPChannel PSM: CBL2CAPPSM,
    error: Error?
)

Tells the delegate that the peripheral manager removed a published service from the local system.

ペリフェラルマネージャがローカルシステムから公開サービスを削除したことをデリゲートに伝えます。

ディスカッション：

The peripheral manager calls this method after you call unpublishL2CAPChannel(_:).

peripheralManager(_:didOpen:error:)

optional func peripheralManager(
    _ peripheral: CBPeripheralManager,
    didOpen channel: CBL2CAPChannel?,
    error: Error?
)

Tells the delegate that the peripheral manager opened an L2CAP channel.

ペリフェラルマネージャがL2CAPチャネルを開いたことをデリゲートに伝える。

ディスカッション：

The peripheral manager calls this method after you call publishL2CAPChannel(withEncryption:).

メモ

• ディスカッションにある publishL2CAPChannel の後に呼ばれる、という表記は間違っている！？
  • publishL2CAPChannel の後に呼ばれるのは didPublishL2CAPChannel メソッドであり、
  • セントラルロール側で、CBPeripheral の openL2CAPChannel を呼んだ後に呼ばれる、の間違いかと。
  • ただ CBPeripheralManager 側にはopenするメソッドはなく、たしかにこのデリゲートメソッドの前に明示的に呼ぶL2CAP関連メソッドはpublishしかないので、間違いでもないのかもしれない

CBPeripheral

openL2CAPChannel(_:)

func openL2CAPChannel(_ PSM: CBL2CAPPSM)

Attempts to open an L2CAP channel to the peripheral using the supplied Protocol/Service Multiplexer (PSM).

付属のPSM（Protocol/Service Multiplexer）を使用して、ペリフェラルへのL2CAPチャネルを開こうとする。

引数

**PSM
**The PSM of the channel to open.

メモ

• この openL2CAPChannel メソッドに対して、closeL2CAPChannel というメソッドは用意されていない。
  • closeしたい場合はどうすべきかといったこともドキュメントには書かれていない
• 引数に指定するのは CBL2CAPPSM だけ
  • 後述するが CBL2CAPPSM はただの UInt16
    • しかも前述の通り最初はいつも 192 が発行される
    • だからといって別のペリフェラルが同じPSM番号を指定してopenしても同じ通信経路として確立されるわけではない。
    • つまり CBL2CAPPSM によってL2CAPチャンネルが一意に決定されるわけではない
  • CBL2CAPPSM の数値を知っていればpublishしなくてもopenできるのかというとそれはできない ^[2]
• このopenメソッドは CBPeripheral のメソッドなので、つまりセントラルロール側から当該ペリフェラルとのL2CAPチャンネルのオープンをトリガーすることになる。

CBPeripheralDelegate

peripheral(_:didOpen:error:)

optional func peripheral(
    _ peripheral: CBPeripheral,
    didOpen channel: CBL2CAPChannel?,
    error: Error?
)

Delivers the result of an attempt to open an L2CAP channel.

L2CAP チャネルを開こうとした結果を配信する。

ディスカッション

This method delivers the result of a previous call to openL2CAPChannel(_:).

このメソッドは、以前にopenL2CAPChannel(_:)を呼び出した結果を配信します。

メモ

• openL2CAPChannel メソッドはあるが closeL2CAPChannelはないのと同様に、このデリゲートメソッドの対となる 〜:didClose:〜 というようなデリゲートメソッドはない
• CBError や CBError.Code にL2CAP専用の定義が追加されてないか調べたが、とくに見当たらなかった。

CBUUIDL2CAPPSMCharacteristicString

let CBUUIDL2CAPPSMCharacteristicString: String

The PSM of an L2CAP channel associated with the GATT service containing this characteristic.

この特性を含む GATT サービスに関連する L2CAP チャネルの PSM を示す。

ディスカッション：

This PSM is a little-endian UInt16. Servers can publish this characteristic with the UUID ABDD3056-28FA-441D-A470-55A75A52553A.

このPSMは、リトルエンディアンUInt16である。サーバーは、この特性を UUID ABDD3056-28FA-441D-A470-55A75A52553A で公開できます。

CBL2CAPChannel

class CBL2CAPChannel : NSObject

A live L2CAP connection to a remote device.

peer

var peer: CBPeer! { get }

The peer connected to the channel.

psm

var psm: CBL2CAPPSM { get }

The PSM of the channel.

inputStream

var inputStream: InputStream!

The stream used for reading data from the remote peer.

outputStream

var outputStream: OutputStream!

The stream used for writing data to the peer.

メモ

• PSMと組み合わせることでL2CAPのチャンネルを一意に識別するためのCID（チャンネルのID）は取得できない。
  • CBL2CAPPSM はただの UInt16 （後述）であり同じ値でも必ずしも同じ通信経路を表すわけではない（前述）ので、 peer.identifier と組み合わせて識別する

CBL2CAPPSM

typealias CBL2CAPPSM = UInt16

The type of PSM identifiers.

脚注

1. Logical Link Control and Adaptation Protocol、略してL2CAP（エルツ―キャップ）は、

2. こういったドキュメントに記載されていない挙動はまた別記事に書きたいと思う）