Zenn
📚

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

2023/09/28に公開
iOS
Swift
ble
Bluetooth
Core Bluetooth
tech

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

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

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

また本記事は「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の発見を処理するのはアプリの責任である。

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チャネルを閉じます。

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:).

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.

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(_:)を呼び出した結果を配信します。

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.

CBL2CAPPSM 

typealias CBL2CAPPSM = UInt16

The type of PSM identifiers.

脚注

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

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

Discussion