Mac Dev Center Mac OS X Reference Library Drivers, Kernel, & Hardware: User-Space Device Access Bluetooth Framework Reference

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

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

-initWithDevice:channelID:

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

-initWithIncomingRFCOMMChannel

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

-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

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.

-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 stopeed due to the lack of buffers this call restarts it.

-sendBufferTroughChannel

Sends the next block of data trough the rfcomm channel.

-sendDataToTransport

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.

-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

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

-setOBEXSessionOpenConnectionCallback:refCon:

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

-setOpenTransportConnectionAsyncSelector

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

-setOpenTransportConnectionAsyncSelector:target:refCon:

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

+withDevice

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

+withDevice:channelID:

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

+withIncomingRFCOMMChannel

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

+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

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

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

Parameters

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

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

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

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

Parameters

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.

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; 

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 stopeed due to the lack of buffers this call restarts it.

- (void)restartTransmission; 

Discussion

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

Sends the next block of data trough 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.

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; 

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

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

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

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.

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

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

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 a Bluetooth device and a Bluetooth RFCOMM channel ID.

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

Parameters

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

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 incoming RFCOMM channel.

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

Parameters

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

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.