IOBluetoothOBEXSession

Overview

An OBEX Session with a Bluetooth RFCOMM channel as the transport.

Methods

-closeTransportConnection

An OBEXSession override. When this is called by the session baseclass, we will close the transport connection if it is opened. In our case, it will be the RFCOMM channel that needs closing.

-getDevice

Get the Bluetooth Device being used by the session object.

-getRFCOMMChannel

Get the Bluetooth RFCOMM channel being used by the session object.

-hasOpenTransportConnection

An OBEXSession override. When this is called by the session baseclass, we will return whether or not we have a transport connection established to another OBEX server/client. In our case we will tell whether or not the RFCOMM channel to a remote device is still open.

-initWithDevice:channelID:

Initializes a Bluetooth-based OBEX Session using a Bluetooth device.

-initWithIncomingRFCOMMChannel:eventSelector:selectorTarget:refCon:

Initializes a Bluetooth-based OBEX Session using an incoming RFCOMM channel.

-initWithSDPServiceRecord:

Initializes a Bluetooth-based OBEX Session using an SDP service record.

-isSessionTargetAMac

Tells whether the target device is a Mac by checking its service record.

-openTransportConnection:selectorTarget:refCon:

An OBEXSession override. When this is called by the session baseclass, we will attempt to open the transport connection. In our case, this would be an RFCOMM channel to another Bluetooth device.

-restartTransmission

If the transmission was stopped due to the lack of buffers this call restarts it.

-sendBufferTroughChannel

Sends the next block of data through the RFCOMM channel.

-sendDataToTransport:dataLength:

An OBEXSession override. When this is called by the session baseclass, we will send the data we are given over our transport connection. If none is open, we could try to open it, or just return an error. In our case, it will be sent over the RFCOMM channel.

-setOBEXSessionOpenConnectionCallback:refCon:

For C API support. Allows you to set the callback to be invoked when the OBEX connection is actually opened.

-setOpenTransportConnectionAsyncSelector:target:refCon:

Allows you to set the selector to be used when a transport connection is opened, or fails to open.

+withDevice:channelID:

Creates a Bluetooth-based OBEX Session using a Bluetooth device and a Bluetooth RFCOMM channel ID.

+withIncomingRFCOMMChannel:eventSelector:selectorTarget:refCon:

Creates a Bluetooth-based OBEX Session using an incoming RFCOMM channel.

+withSDPServiceRecord:

Creates a Bluetooth-based OBEX Session using an SDP service record, typically obtained from a device/service browser window controller.

An OBEXSession override. When this is called by the session baseclass, we will close the transport connection if it is opened. In our case, it will be the RFCOMM channel that needs closing.

-(OBEXError)closeTransportConnection; 

Return Value

Success or failure code, describing whether the call succeeded in closing the transport connection successfully.

Get the Bluetooth Device being used by the session object.

-(IOBluetoothDevice*)getDevice; 

Return Value

An IOBluetoothDevice object.

Get the Bluetooth RFCOMM channel being used by the session object.

-(IOBluetoothRFCOMMChannel*)getRFCOMMChannel; 

Return Value

A IOBluetoothRFCOMMChannel object.

Discussion

This could potentially be nil even though you have a valid OBEX session, because the RFCOMM channel is only valid when the session is connected.

An OBEXSession override. When this is called by the session baseclass, we will return whether or not we have a transport connection established to another OBEX server/client. In our case we will tell whether or not the RFCOMM channel to a remote device is still open.

-(BOOL)hasOpenTransportConnection; 

Return Value

True or false, whether there is already an open transport connection for this OBEX session.

Initializes a Bluetooth-based OBEX Session using a Bluetooth device.

-(id) initWithDevice:(IOBluetoothDevice*)inDevice channelID:(BluetoothRFCOMMChannelID)inChannelID; 

Parameters

inDevice

The bluetooth device on which to open the OBEXSession.

inChannelID

The RFCOMM channel ID to use when opening the connection.

Initializes a Bluetooth-based OBEX Session using an incoming RFCOMM channel.

-(id) initWithIncomingRFCOMMChannel:(IOBluetoothRFCOMMChannel*)inChannel eventSelector:(SEL)inEventSelector selectorTarget:(id)inEventSelectorTarget refCon:(void *)inUserRefCon; 

Parameters

inChannel

RFCOMM channel of the desired channel to be used.

inEventSelector

The selector to be called when an event is received.

inEventSelectorTarget

The target object that get the selector message.

inUserRefCon

caller reference constant, pass whatever you want, it will be returned to you in the selector.

Initializes a Bluetooth-based OBEX Session using an SDP service record.

-(id) initWithSDPServiceRecord:(IOBluetoothSDPServiceRecord*)inSDPServiceRecord; 

Parameters

inSDPServiceRecord

Tells whether the target device is a Mac by checking its service record.

- (BOOL)isSessionTargetAMac; 

Return Value

TRUE only if device service record has Mac entry, FALSE for all else.

Discussion

Tells whether the target device is a Mac by checking its service record.

An OBEXSession override. When this is called by the session baseclass, we will attempt to open the transport connection. In our case, this would be an RFCOMM channel to another Bluetooth device.

-(OBEXError)openTransportConnection:(SEL)inSelector selectorTarget:(id)inTarget refCon:(void *)inUserRefCon; 

Return Value

Success or failure code.

Discussion

Your selector should have the following signature:

                                        -(void)transportConnectionSelector:(id)refcon                status:(OBEXError)status;
                                

Thus you could use it with openTransportConnection like this:

                                        OBEXError        error = [anOBEXSession        openTransportConnection:@selector( transportConnectionSelector:status: )
                                                                                                                selectorTarget:self
                                                                                                                refCon:anOBEXSession];        // or whatever you want to pass as a refCon...

Be sure to check the status code! Assume the connection was not opened unless status is kOBEXSuccess.

If the transmission was stopped due to the lack of buffers this call restarts it.

- (void)restartTransmission; 

Discussion

If the transmission was stopped due to the lack of buffers this call restarts it.

Sends the next block of data through the RFCOMM channel.

- (IOReturn)sendBufferTroughChannel; 

Discussion

Since a send in the RFCOMM channel is broken in multiple write calls (this actually is true only if the size is grater than the RFCOMM MTU). Each write call is performed by sendBufferTroughChannel. This should never need to be overwritten.

An OBEXSession override. When this is called by the session baseclass, we will send the data we are given over our transport connection. If none is open, we could try to open it, or just return an error. In our case, it will be sent over the RFCOMM channel.

-(OBEXError)sendDataToTransport:(void *)inDataToSend dataLength:(size_t)inDataLength; 

Return Value

Success or failure code, describing whether the call succeeded in writing the data to the transport.

For C API support. Allows you to set the callback to be invoked when the OBEX connection is actually opened.

-(void)setOBEXSessionOpenConnectionCallback:(IOBluetoothOBEXSessionOpenConnectionCallback)inCallback refCon:(void*)inUserRefCon; 

Parameters

inCallback

function to call on the target.

inUserRefCon

user's reference constant, will be returned on the callback.

Allows you to set the selector to be used when a transport connection is opened, or fails to open.

-(void)setOpenTransportConnectionAsyncSelector:(SEL)inSelector target:(id)inSelectorTarget refCon:(id)inUserRefCon; 

Parameters

inSelector

Selector to call on the target.

inSelectorTarget

Target to be called with the selector.

inUserRefCon

User's refCon that will get passed to them when their selector is invoked.

Discussion

You do not need to call this on the session typically, unless you have subclassed the OBEXSession to implement a new transport and that transport supports async opening of connections. If it does not support async open, then using this is pointless.

Creates a Bluetooth-based OBEX Session using a Bluetooth device and a Bluetooth RFCOMM channel ID.

+(IOBluetoothOBEXSession*)withDevice:(IOBluetoothDevice*)inDevice channelID:(BluetoothRFCOMMChannelID)inRFCOMMChannelID; 

Parameters

inDevice

A valid Bluetooth device describing which device you want to connect to with Bluetooth/OBEX.

inRFCOMMChannelID

An RFCOMM Channel ID numbe that is available on the remote device. This channel will be used when the transport connection is attempted.

Return Value

An OBEX session representing the device/RFCOMM channel found in the service record. nil if we failed.

Discussion

Note that this does NOT mean the transport connection was open. It will be opened when OBEXConnect is invoked on the session object. IMPORTANT NOTE* In Bluetooth framework version 1.0.0, the session returned will NOT be autoreleased as it should be according to objc convention. This has been changed starting in Bluetooth version 1.0.1 and later, so it WILL be autoreleased upon return, so you will need to retain it if you want to reference it later.

Creates a Bluetooth-based OBEX Session using an incoming RFCOMM channel.

+(IOBluetoothOBEXSession*)withIncomingRFCOMMChannel:(IOBluetoothRFCOMMChannel*)inChannel eventSelector:(SEL)inEventSelector selectorTarget:(id)inEventSelectorTarget refCon:(void *)inUserRefCon; 

Parameters

inChannel

The channel to use to create a connection to a device.

inEventSelector

The selector that gets called when an event occurs on the OBEX Session.

inEventSelectorTarget

The object that is used to call the above selector.

inUserRefCon

The reference constant. Pass whatever you wish - it will be returned to you in the selector.

Discussion

IMPORTANT NOTE* In Bluetooth framework version 1.0.0, the session returned will NOT be autoreleased as it should be according to objc convention. This has been changed starting in Bluetooth version 1.0.1 and later, so it WILL be autoreleased upon return, so you will need to retain it if you want to reference it later.

Creates a Bluetooth-based OBEX Session using an SDP service record, typically obtained from a device/service browser window controller.

+(IOBluetoothOBEXSession*) withSDPServiceRecord:(IOBluetoothSDPServiceRecord*)inSDPServiceRecord; 

Parameters

inSDPServiceRecord

A valid SDP service record describing the service (and RFCOMM channel) you want to connect to with Bluetooth/OBEX.

Return Value

An OBEX session representing the device/RFCOMM channel found in the service record. nil if we failed.

Discussion

Note that this does NOT mean the transport connection was open. It will be opened when OBEXConnect is invoked on the session object. IMPORTANT NOTE* In Bluetooth framework version 1.0.0, the session returned will NOT be autoreleased as it should be according to objc convention. This has been changed starting in Bluetooth version 1.0.1 and later, so it WILL be autoreleased upon return, so you will need to retain it if you want to reference it 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.