IOBluetoothL2CAPChannel

Overview

An instance of IOBluetoothL2CAPChannel represents a single open L2CAP channel.

Discussion

A client won't create IOBluetoothL2CAPChannel objects directly. Instead, the IOBluetoothDevice's L2CAP channel open API is responsible for opening a new L2CAP channel and returning an IOBluetoothL2CAPChannel instance representing that newly opened channel. Additionally, the IOBluetooth notification system will send notifications when new L2CAP channels are open (if requested).

After a new L2CAP channel is opened, the L2CAP configuration process will not be completed until an incoming data listener is registered with the IOBluetoothL2CAPChannel object. The reason for this is to due to the limited buffering done of incoming L2CAP data. This way, we avoid the situation where incoming data is received before the client is ready for it. Once a client is done with an IOBluetoothL2CAPChannel that it opened, it should call -closeChannel. Additionally, if the client does not intend to use the connection to the remote device any further, it should call -closeConnection on the IOBluetoothDevice object.

Methods

-closeChannel

Initiates the close process on an open L2CAP channel.

-getDevice

Returns the IOBluetoothDevice to which the target L2CAP channel is open.

-getIncomingMTU

Returns the current incoming MTU for the L2CAP channel.

-getL2CAPChannelRef

Returns an IOBluetoothL2CAPChannelRef representation of the target IOBluetoothL2CAPChannel object.

-getLocalChannelID

Returns the local L2CAP channel ID for the target L2CAP channel.

-getObjectID

Returns the IOBluetoothObjectID of the given IOBluetoothL2CAPChannel.

-getOutgoingMTU

Returns the current outgoing MTU for the L2CAP channel.

-getPSM

Returns the PSM for the target L2CAP channel.

-getRemoteChannelID

Returns the remote L2CAP channel ID for the target L2CAP channel.

-isIncoming

Returns TRUE if the channel is an incoming channel.

-registerForChannelCloseNotification:selector:

Allows a client to register for a channel close notification.

+registerForChannelOpenNotifications:selector:

Allows a client to register for L2CAP channel open notifications for any L2CAP channel.

+registerForChannelOpenNotifications:selector:withPSM:direction:

Allows a client to register for L2CAP channel open notifications for certain types of L2CAP channels.

-registerIncomingDataListener:refCon:

***WARNING*** This method is being deprecated in favor of -setDelegate: Allows a client to register a callback that gets called when new incoming data arrives.

-requestRemoteMTU:

Initiates the process to reconfigure the L2CAP channel with a new outgoing MTU.

-setDelegate:

Allows an object to register itself as client of the L2CAP channel.

-setDelegate:withConfiguration:

Allows an object to register itself as client of the L2CAP channel.

+withL2CAPChannelRef:

Method call to convert an IOBluetoothL2CAPChannelRef into an IOBluetoothL2CAPChannel *.

+withObjectID:

Returns the IObluetoothL2CAPChannel with the given IOBluetoothObjectID.

-write:length:

Writes the given data over the target L2CAP channel to the remote device.

-writeAsync:length:refcon:

Writes the given data over the target L2CAP channel asynchronously to the remote device.

-writeSync:length:

Writes the given data synchronously over the target L2CAP channel to the remote device.

Initiates the close process on an open L2CAP channel.

- (IOReturn)closeChannel; 

Return Value

Returns kIOReturnSuccess on success.

Discussion

This method may only be called by the client that opened the channel in the first place. In the future asynchronous and synchronous versions will be provided that let the client know when the close process has been finished.

Returns the IOBluetoothDevice to which the target L2CAP channel is open.

- (IOBluetoothDevice *)getDevice; 

Return Value

Returns the IOBluetoothDevice to which the target L2CAP channel is open.

Returns the current incoming MTU for the L2CAP channel.

- (BluetoothL2CAPMTU)getIncomingMTU; 

Return Value

Returns the current incoming MTU for the L2CAP channel.

Discussion

The incoming MTU represents the maximum L2CAP packet size for packets being sent by the remote device.

Returns an IOBluetoothL2CAPChannelRef representation of the target IOBluetoothL2CAPChannel object.

- (IOBluetoothL2CAPChannelRef)getL2CAPChannelRef; 

Return Value

Returns an IOBluetoothL2CAPChannelRef representation of the target IOBluetoothL2CAPChannel object.

Returns the local L2CAP channel ID for the target L2CAP channel.

- (BluetoothL2CAPChannelID)getLocalChannelID; 

Return Value

Returns the local L2CAP channel ID for the target L2CAP channel.

Returns the IOBluetoothObjectID of the given IOBluetoothL2CAPChannel.

- (IOBluetoothObjectID)getObjectID; 

Return Value

Returns the IOBluetoothObjectID of the given IOBluetoothL2CAPChannel.

Discussion

The IOBluetoothObjectID can be used as a global reference for a given IOBluetoothL2CAPChannel. It allows two separate applications to refer to the same IOBluetoothL2CAPChannel.

Returns the current outgoing MTU for the L2CAP channel.

- (BluetoothL2CAPMTU)getOutgoingMTU; 

Return Value

Returns the current outgoing MTU for the L2CAP channel.

Discussion

The outgoing MTU represents the maximum L2CAP packet size for packets being sent to the remote device.

Returns the PSM for the target L2CAP channel.

- (BluetoothL2CAPPSM)getPSM; 

Return Value

Returns the PSM for the target L2CAP channel.

Returns the remote L2CAP channel ID for the target L2CAP channel.

- (BluetoothL2CAPChannelID)getRemoteChannelID; 

Return Value

Returns the remote L2CAP channel ID for the target L2CAP channel.

Returns TRUE if the channel is an incoming channel.

- (BOOL)isIncoming; 

Return Value

Returns TRUE if the channel is an incoming channel.

Discussion

An incoming channel is one that was initiated by a remote device.

Allows a client to register for a channel close notification.

- (IOBluetoothUserNotification *)
        registerForChannelCloseNotification:(id)observer selector:(SEL)inSelector; 

Parameters

observer

Target observer object

inSelector

Selector to be sent to the observer when the L2CAP channel is closed.

Return Value

Returns an IOBluetoothUserNotification representing the outstanding L2CAP channel close notification. To unregister the notification, call -unregister of the returned IOBluetoothUserNotification object. If an error is encountered creating the notification, nil is returned.

Discussion

The given selector will be called on the target observer when the L2CAP channel is closed. The selector should contain two arguments. The first is the user notification object. The second is the IOBluetoothL2CAPChannel that was closed.

Allows a client to register for L2CAP channel open notifications for any L2CAP channel.

+ (IOBluetoothUserNotification *)
        registerForChannelOpenNotifications:(id)object selector:(SEL)selector; 

Parameters

object

Target object

selector

Selector to be called on the target object when a new L2CAP channel is opened.

Return Value

Returns an IOBluetoothUserNotification representing the outstanding L2CAP channel notification. To unregister the notification, call -unregister on the resulting IOBluetoothUserNotification object. If an error is encountered creating the notification, nil is returned. The returned IOBluetoothUserNotification will be valid for as long as the notification is registered. It is not necessary to retain the result. Once -unregister is called on it, it will no longer be valid.

Discussion

The given selector will be called on the target object whenever any L2CAP channel is opened. The selector should accept two arguments. The first is the user notification object. The second is the IOBluetoothL2CAPChannel that was opened.

Allows a client to register for L2CAP channel open notifications for certain types of L2CAP channels.

+ (IOBluetoothUserNotification *)
        registerForChannelOpenNotifications:(id)object selector:(SEL)selector 
        withPSM:(BluetoothL2CAPPSM)psm direction:(IOBluetoothUserNotificationChannelDirection)inDirection; 

Parameters

object

Target object

selector

Selector to be called on the target object when a new L2CAP channel is opened.

psm

PSM to match a new L2CAP channel. If the PSM doesn't matter, 0 may be passed in.

inDirection

The desired direction of the L2CAP channel - kIOBluetoothUserNotificationChannelDirectionAny if the direction doesn't matter.

Return Value

Returns an IOBluetoothUserNotification representing the outstanding L2CAP channel notification. To unregister the notification, call -unregister on the resulting IOBluetoothUserNotification object. If an error is encountered creating the notification, nil is returned. The returned IOBluetoothUserNotification will be valid for as long as the notification is registered. It is not necessary to retain the result. Once -unregister is called on it, it will no longer be valid.

Discussion

The given selector will be called on the target object whenever an L2CAP channel with the given attributes is opened. The selector should accept two arguments. The first is the user notification object. The second is the IOBluetoothL2CAPChannel that was opened.

***WARNING*** This method is being deprecated in favor of -setDelegate: Allows a client to register a callback that gets called when new incoming data arrives.

- (IOReturn)registerIncomingDataListener:(IOBluetoothL2CAPChannelIncomingDataListener)listener 
        refCon:(void *)refCon DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER; 

Parameters

listener

Callback function that gets called when new incoming data is received.

refCon

Client-supplied reference that gets passed to the listener function.

Return Value

Returns kIOReturnSuccess if the listener is successfully registered.

Discussion

A newly opened L2CAP channel will not complete its configuration process until the client that opened it registers an incoming data listener. This prevents that case where incoming data is received before the client is ready. The incoming data listener callback is currently a C function. In the future, API will be available that allows an objective-c listener to be set.

Initiates the process to reconfigure the L2CAP channel with a new outgoing MTU.

- (IOReturn)requestRemoteMTU:(BluetoothL2CAPMTU)remoteMTU; 

Parameters

remoteMTU

The desired outgoing MTU.

Return Value

Returns kIOReturnSuccess if the channel re-configure process was successfully initiated.

Discussion

Currently, this API does not give an indication that the re-config process has completed. In the future additional API will be available to provide that information both synchronously and asynchronously.

Allows an object to register itself as client of the L2CAP channel.

- (IOReturn)setDelegate:(id)channelDelegate; 

Parameters

channelDelegate

the object that will play the role of channel delegate [NOTE the l2cap channel will retain the delegate].

Return Value

Returns kIOReturnSuccess if the delegate is successfully registered.

Discussion

A channel delegate is the object the L2CAP channel uses as target for data and events. The developer will implement only the the methods he/she is interested in. A list of the possible methods is at the end of this file in the definition of the informal protocol IOBluetoothL2CAPChannelDelegate. A newly opened L2CAP channel will not complete its configuration process until the client that opened it registers a connectionHandler. This prevents that case where incoming data is received before the client is ready.

NOTE: This method is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

Allows an object to register itself as client of the L2CAP channel.

- (IOReturn)setDelegate:(id)channelDelegate 
        withConfiguration:(NSDictionary*)channelConfiguration; 

Parameters

channelDelegate

the object that will play the role of channel delegate.

channelConfiguration

the dictionary that describes the initial configuration for the channel.

Return Value

Returns kIOReturnSuccess if the delegate is successfully registered.

Discussion

A channel delegate is the object the L2CAP channel uses as target for data and events. The developer will implement only the the methods he/she is interested in. A list of the possible methods is at the end of this file in the definition of the informal protocol IOBluetoothL2CAPChannelDelegate. A newly opened L2CAP channel will not complete its configuration process until the client that opened it registers a connectionHandler. This prevents that case where incoming data is received before the client is ready.

NOTE: This method is only available in Mac OS X 10.5 (Bluetooth v2.0) or later.

Method call to convert an IOBluetoothL2CAPChannelRef into an IOBluetoothL2CAPChannel *.

+ (IOBluetoothL2CAPChannel *)withL2CAPChannelRef:(IOBluetoothL2CAPChannelRef)l2capChannelRef; 

Parameters

l2capChannelRef

IOBluetoothL2CAPChannelRef for which an IOBluetoothL2CAPChannel * is desired.

Return Value

Returns the IOBluetoothL2CAPChannel * for the given IOBluetoothL2CAPChannelRef.

Returns the IObluetoothL2CAPChannel with the given IOBluetoothObjectID.

+ (IOBluetoothL2CAPChannel *)withObjectID:(IOBluetoothObjectID)objectID; 

Parameters

objectID

IOBluetoothObjectID of the desired IOBluetoothL2CAPChannel.

Return Value

Returns the IOBluetoothL2CAPChannel that matches the given IOBluetoothObjectID if one exists. If no matching L2CAP channel exists, nil is returned.

Discussion

The IOBluetoothObjectID can be used as a global reference for a given IOBluetoothL2CAPChannel. It allows two separate applications to refer to the same IOBluetoothL2CAPChannel object.

Writes the given data over the target L2CAP channel to the remote device.

- (IOReturn)write:(void *)data length:(UInt16)length DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER; 

Parameters

data

Pointer to the buffer containing the data to send.

length

The length of the given data buffer.

Return Value

Returns kIOReturnSuccess if the data was written successfully.

Discussion

***WARNING*** This method is being deprecated in favor of -writeSync:... and -writeAsync:... The length of the data may not exceed the L2CAP channel's ougoing MTU. The fact that this method has returned doesn't mean that the data has been delivered successfully. It just means that it has been scheduled to be delivered. In the future, additional API will be available to provide a notification that the write has been completed (both synchronously and asynchronously). This method may block if previous writes have not been delivered.

Writes the given data over the target L2CAP channel asynchronously to the remote device.

- (IOReturn)writeAsync:(void *)data length:(UInt16)length 
        refcon:(void*)refcon; 

Parameters

data

Pointer to the buffer containing the data to send.

length

The length of the given data buffer.

refcon

User supplied value that gets passed to the write callback.

Return Value

Returns kIOReturnSuccess if the data was buffered successfully.

Discussion

The length of the data may not exceed the L2CAP channel's ougoing MTU. When the data has been successfully passed to the hardware to be transmitted, the delegate method -l2capChannelWriteComplete:refcon:status: will be called with the refcon passed into this method.

NOTE: This method is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

Writes the given data synchronously over the target L2CAP channel to the remote device.

- (IOReturn)writeSync:(void *)data length:(UInt16)length; 

Parameters

data

Pointer to the buffer containing the data to send.

length

The length of the given data buffer.

Return Value

Returns kIOReturnSuccess if the data was written successfully.

Discussion

The length of the data may not exceed the L2CAP channel's ougoing MTU. This method will block until the data has been successfully sent to the hardware for transmission (or an error occurs).

NOTE: This method is only available in Mac OS X 10.2.5 (Bluetooth v1.2) or later.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.