IOBluetoothRFCOMMChannel

Overview

An instance of this class represents an RFCOMM channel as defined by the Bluetooth SDP spec.

Discussion

An RFCOMM channel object can be obtained by opening an RFCOMM channel in a device, or by requesting a notification when a channel is created (this is commonly used to provide services).

Methods

-channelNumber

Returns the object's RFCOMM channel ID.

-closeChannel

Close the channel.

-getChannelID

Returns the object's RFCOMM channel ID.

-getDevice

Returns the Bluetooth Device that carries the RFCOMM data.

-getMTU

Returns the channel maximum transfer unit.

-getObjectID

Returns the IOBluetoothObjectID of the given IOBluetoothRFCOMMChannel.

-getRFCOMMChannelRef

Returns an IOBluetoothRFCOMMChannelRef representation of the target IOBluetoothRFCOMMChannel object.

-isIncoming

Returns the direction of the channel. An incoming channel is one that was opened by the remote device.

-isOpen

Returns the state of the channel.

-isTransmissionPaused

Returns TRUE if flow control is off.

-registerForChannelCloseNotification:selector:

Allows a client to register for a channel close notification.

+registerForChannelOpenNotifications:selector:

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

+registerForChannelOpenNotifications:selector:withChannelID:direction:

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

-registerIncomingDataListener:refCon:

Registers a callback for incoming data.

-registerIncomingDataListener:refCon:refCon:

Registers a callback for incoming data.

-registerIncomingEventListener:refCon:

Registers a callback for events.

-registerIncomingEventListener:refCon:refCon:

Registers a callback for events.

-sendRemoteLineStatus:

Sends an error to the remote side.

-setDelegate:

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

-setSerialParameters:dataBits:parity:stopBits:

Changes the parameters of the serial connection.

+withObjectID:

Returns the IObluetoothRFCOMMChannel with the given IOBluetoothObjectID.

+withRFCOMMChannelRef:

Method call to convert an IOBluetoothRFCOMMChannelRef into an IOBluetoothRFCOMMChannel *.

-write:length:sleep:

Sends a block of data in the channel syncronously.

-writeAsync:length:refcon:

Sends a block of data in the channel asynchronously.

-writeSimple:length:sleep:bytesSent:

Sends a block of data in the channel.

-writeSync:length:

Sends a block of data in the channel synchronously.

-writeSync:length:refcon:

Sends a block of data in the channel synchronously.

Returns the object's RFCOMM channel ID.

getChannelID

- (BluetoothRFCOMMChannelID)getChannelID; 

Return Value

Returns the RFCOMM channel number.

Close the channel.

- (IOReturn)closeChannel; 

Return Value

An error code value. 0 if successful.

Returns the object's RFCOMM channel ID.

channelNumber

- (BluetoothRFCOMMChannelID)getChannelID; 

Returns the Bluetooth Device that carries the RFCOMM data.

- (IOBluetoothDevice *)getDevice; 

Return Value

Returns the IOBluetoothDevice object.

Returns the channel maximum transfer unit.

- (BluetoothRFCOMMMTU)getMTU; 

Return Value

Channel MTU size.

Discussion

Returns the length of the largest chunk of data that this channel can carry. If the caller wishes to use the write:length:sleep: api the length of the data can not be bigger than the channel MTU (maximum transfer unit).

Returns the IOBluetoothObjectID of the given IOBluetoothRFCOMMChannel.

- (IOBluetoothObjectID)getObjectID; 

Return Value

Returns the IOBluetoothObjectID of the given IOBluetoothRFCOMMChannel.

Discussion

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

Returns an IOBluetoothRFCOMMChannelRef representation of the target IOBluetoothRFCOMMChannel object.

- (IOBluetoothRFCOMMChannelRef)getRFCOMMChannelRef; 

Return Value

Returns an IOBluetoothRFCOMMChannelRef representation of the target IOBluetoothRFCOMMChannel object.

Returns the direction of the channel. An incoming channel is one that was opened by the remote device.

- (BOOL)isIncoming; 

Return Value

Returns TRUE if the channel was opened by the remote device, FALSE if the channel was opened by this object.

Returns the state of the channel.

- (BOOL)isOpen; 

Return Value

TRUE if the channel state is open, FALSE otherwise.

Discussion

note that "not open" means closed, opening and closing.

Returns TRUE if flow control is off.

- (BOOL)isTransmissionPaused; 

Return Value

TRUE if the action of sending data will block the current thread, FALSE otherwise.

Discussion

Returns true if the remote device flow control is stopping out transmission. This is useful because we do not buffer data, we stop the transmitting actor. With this method the transmitter can check if sending data is going to be successful or is going to block.

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 RFCOMM channel is closed.

Return Value

Returns an IOBluetoothUserNotification representing the outstanding RFCOMM 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 RFCOMM channel is closed. The selector should contain two arguments. The first is the user notification object. The second is the IOBluetoothRFCOMMChannel that was closed.

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

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

Parameters

rfcommChannelRef

IOBluetoothRFCOMMChannelRef for which an IOBluetoothRFCOMMChannel * is desired.

object

Target object

selector

Selector to be called on the target object when a new RFCOMM channel is opened. The format for the selector is: -(void) selectorName:(IOBluetoothUserNotification *)inNotification channel:(IOBluetoothRFCOMMChannel *)newChannel

Return Value

Returns an IOBluetoothUserNotification representing the outstanding RFCOMM 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 RFCOMM channel is opened. The selector should accept two arguments. The first is the user notification object. The second is the IOBluetoothRFCOMMChannel that was opened.

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

+ (IOBluetoothUserNotification *)
        registerForChannelOpenNotifications:(id)object selector:(SEL)selector 
        withChannelID:(BluetoothRFCOMMChannelID)channelID direction:(IOBluetoothUserNotificationChannelDirection)inDirection; 

Parameters

object

Target object

selector

Selector to be called on the target object when a new RFCOMM channel is opened. the format for the selector is: -(void) selectorName:(IOBluetoothUserNotification *)inNotification channel:(IOBluetoothRFCOMMChannel *)newChannel

channelID

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

inDirection

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

Return Value

Returns an IOBluetoothUserNotification representing the outstanding RFCOMM 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 RFCOMM 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.

Registers a callback for incoming data.

registerIncomingDataListener:refCon:refCon:

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

Parameters

listener

is the callback function.

refCon

is a void*, its meaning is up to the developer. This parameter will be passed back as last parameter of the callback function.

Discussion

***WARNING*** This method is being deprecated in favor of -setDelegate: Registers a callback for the incoming data. The form for the callback is:

void function(IOBluetoothRFCOMMChannelRef rfcommChannel, void *data, UInt16 length, void *refCon)

where rfcommChannel is the refernce to the channel that received data, data is a buffer with the received data, length is the buffer length (in bytes) and refCon is a user defined void* (maybe the reference to the object to call back ?).

Registers a callback for incoming data.

registerIncomingDataListener:refCon:

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

Parameters

listener

is the callback function.

refCon

is a void*, its meaning is up to the developer. This parameter will be passed back as last parameter of the callback function.

Return Value

An error code value. 0 if successful.

Discussion

***WARNING*** This method is being deprecated in favor of -setDelegate: Registers a callback for the incoming data. The form for the callback is:

void function(IOBluetoothRFCOMMChannelRef rfcommChannel, void *data, UInt16 length, void *refCon)

where rfcommChannel is the refernce to the channel that received data, data is a buffer with the received data, length is the buffer length (in bytes) and refCon is a user defined void* (maybe the reference to the object to call back ?).

Registers a callback for events.

registerIncomingEventListener:refCon:refCon:

- (IOReturn)registerIncomingEventListener:(IOBluetoothRFCOMMChannelIncomingEventListener)listener 
        refCon:(void *)refCon; 

Parameters

listener

is the callback function.

refCon

is a void*, its meaning is up to the developer. This parameter will be passed back as second parameter of the callback function.

Discussion

***WARNING*** This method is being deprecated in favor of -setDelegate: Registers a callback for events generated by the RFCOMM channel. The form for the callback is:

void function(IOBluetoothRFCOMMChannelRef rfcommChannel, void *refCon, IOBluetoothRFCOMMChannelEvent *event)

where rfcommChannel is the reference to the channel that generated the event, refCon is a user defined void* (maybe the reference to the object to call back?) and event is the generated event. There are three types of events available:

kIOBluetoothRFCOMMNewDataEvent when new data is received.
kIOBluetoothRFCOMMFlowControlChangedEvent change of flow control.
kIOBluetoothRFCOMMChannelTerminatedEvent when the RFCOMM channel is no more valid.

Note that the kIOBluetoothRFCOMMNewDataEvent provides the same functionality of the data listener callback. This means that if the developer has both an event callback and a datalistener callback both functions will be called when new data arrives. It is up to the developer to properly filter the events (or better to use only one callback). For a better descriptions of the events and the event structure see IOBluetoothUserLib.h.

Registers a callback for events.

registerIncomingEventListener:refCon:

- (IOReturn)registerIncomingEventListener:(IOBluetoothRFCOMMChannelIncomingEventListener)listener 
        refCon:(void *)refCon; 

Parameters

listener

is the callback function.

refCon

is a void*, its meaning is up to the developer. This parameter will be passed back as second parameter of the callback function.

Return Value

An error code value. 0 if successful.

Discussion

***WARNING*** This method is being deprecated in favor of -setDelegate: Registers a callback for events generated by the RFCOMM channel. The form for the callback is:

void function(IOBluetoothRFCOMMChannelRef rfcommChannel, void *refCon, IOBluetoothRFCOMMChannelEvent *event)

where rfcommChannel is the reference to the channel that generated the event, refCon is a user defined void* (maybe the reference to the object to call back?) and event is the generated event. There are three types of events available:

kIOBluetoothRFCOMMNewDataEvent when new data is received.
kIOBluetoothRFCOMMFlowControlChangedEvent change of flow control.
kIOBluetoothRFCOMMChannelTerminatedEvent when the RFCOMM channel is no more valid.

Note that the kIOBluetoothRFCOMMNewDataEvent provides the same functionality of the data listener callback. This means that if the developer has both an event callback and a datalistener callback both functions will be called when new data arrives. It is up to the developer to properly filter the events (or better to use only one callback). For a better descriptions of the events and the event structure see IOBluetoothUserLib.h.

Sends an error to the remote side.

- (IOReturn)sendRemoteLineStatus:(BluetoothRFCOMMLineStatus)lineStatus; 

Parameters

lineStatus

the error type. The error code can be NoError, OverrunError, ParityError or FramingError.

Return Value

An error code value. 0 if successful.

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

- (IOReturn)setDelegate:(id)delegate; 

Parameters

delegate

The object that will play the role of channel delegate [NOTE the rfcomm channel will reatin the delegate].

Return Value

Returns kIOReturnSuccess if the delegate is successfully registered.

Discussion

A channel delegate is the object the RFCOMM 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 IOBluetoothRFCOMMChannelDelegate.

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

Changes the parameters of the serial connection.

- (IOReturn)setSerialParameters:(UInt32)speed dataBits:(UInt8)nBits 
        parity:(BluetoothRFCOMMParityType)parity stopBits:(UInt8)bitStop; 

Parameters

speed

the baudrate.

nBits

number of data bits.

parity

the type of parity can be NoParity, OddParity, EvenParity or MaxParity.

bitStop

number of stop bits.

Return Value

An error code value. 0 if successful.

Returns the IObluetoothRFCOMMChannel with the given IOBluetoothObjectID.

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

Parameters

objectID

IOBluetoothObjectID of the desired IObluetoothRFCOMMChannel.

Return Value

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

Discussion

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

Method call to convert an IOBluetoothRFCOMMChannelRef into an IOBluetoothRFCOMMChannel *.

+ (IOBluetoothRFCOMMChannel *)withRFCOMMChannelRef:(IOBluetoothRFCOMMChannelRef)rfcommChannelRef; 

Parameters

rfcommChannelRef

IOBluetoothRFCOMMChannelRef for which an IOBluetoothRFCOMMChannel * is desired.

Return Value

Returns the IOBluetoothRFCOMMChannel * for the given IOBluetoothRFCOMMChannelRef.

Sends a block of data in the channel syncronously.

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

Parameters

data

is a pointer to the data buffer to be sent.

length

the length of the buffer to be sent (in bytes).

sleep

is a boolean if set to TRUE the call will wait until it is possible to send data. If set to FALSE and it is not possible to send data the method will return immediately with an error.

Return Value

An error code value. 0 if successful.

Discussion

***WARNING*** This method is being deprecated in favor of -writeSync:... and -writeAsync:... Sends data tough the channel. The number of bytes to be sent must not exceed the channel MTU. If the return value is an error condition none of the data was sent.

Sends a block of data in the channel asynchronously.

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

Parameters

data

A pointer to the data buffer to be sent.

length

The length of the buffer to be sent (in bytes).

refcon

User supplied value that gets passed to the write callback.

Return Value

Returns kIOReturnSuccess if the data was buffered successfully.

Discussion

The number of bytes to be sent must not exceed the channel MTU. If the return value is an error condition none of the data was sent. Once the data has been successfully passed to the hardware to be transmitted, the delegate method -rfcommChannelWriteComplete:refcon:status: will be called with the refcon that was passed to this method.

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

Sends a block of data in the channel.

- (IOReturn)writeSimple:(void *)data length:(UInt16)length 
        sleep:(BOOL)sleep bytesSent:(UInt32 *)numBytesSent DEPRECATED_IN_BLUETOOTH_VERSION_2_0_AND_LATER; 

Parameters

data

a pointer to the data buffer to be sent.

length

the length of the buffer to be sent (in bytes).

sleep

a boolean if set to TRUE the call will wait until it is possible to send all the data.

numBytesSent

a UInt32 pointer in which the caller received the nuber of bytes sent. If set to FALSE and it is not possible to send part of the data the method will return immediately.

Return Value

An error code value. 0 if successful.

Discussion

***WARNING*** This method is being deprecated in favor of -writeSync:... and -writeAsync:... Sends data tough the channel. The number of bytes to be sent is arbitrary. The caller does not have to worry about the MTU.

Sends a block of data in the channel synchronously.

writeSync:length:refcon:

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

Parameters

data

A pointer to the data buffer to be sent.

length

The length of the buffer to be sent (in bytes).

Discussion

Sends data tough the channel. The number of bytes to be sent must not exceed the channel MTU. If the return value is an error condition none of the data was sent. This method will block until the data has been successfully sent to the hardware for transmission (or until an error occurs).

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

Sends a block of data in the channel synchronously.

writeSync:length:

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

Parameters

data

A pointer to the data buffer to be sent.

length

The length of the buffer to be sent (in bytes).

Return Value

Returns kIOReturnSuccess if the data was written successfully.

Discussion

Sends data tough the channel. The number of bytes to be sent must not exceed the channel MTU. If the return value is an error condition none of the data was sent. This method will block until the data has been successfully sent to the hardware for transmission (or until 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.