com.stollmann.terminalIO
Class TIOPeripheral

java.lang.Object
  extended by com.stollmann.terminalIO.TIOPeripheral

public class TIOPeripheral
extends java.lang.Object

TIOPeripheral instances represent remote devices that have been identified as TerminalIO servers during a TIOManager scan procedure. The application retrieves TIOPeripheral instances by calling the TIOManager TIOManager.getPeripherals property or via invocations of one of the peripheral relevant TIOManagerCallback methods. The application shall not create any TIOPeripheral instances of its own.


Method Summary
 void connect()
          Initiates the establishing of a TerminalIO connection to the remote device.
static TIOPeripheral createFromBluetoothDevice(BluetoothDevice device)
          // * @deprecated (exclude for javadoc documentation generation) Internal method to be called by TIOManager only; do not call from application code.
static TIOPeripheral createFromScanResult(BluetoothDevice device, TIOAdvertisement advertisement)
          // * @deprecated (exclude for javadoc documentation generation) Internal method to be called by TIOManager only; do not call from application code.
 void disconnect()
          Requests the operating system to disconnect from the remote device.
 java.lang.String getAddress()
          Gets the preripheral's Bluetooth address.
 TIOAdvertisement getAdvertisement()
          Gets the TIOAdvertisement instance representing the latest advertisement received from the peripheral within a scan procedure.
 java.lang.String getAdvertisementDisplayString()
          Gets a string representation of the current advertisement, see also TIOAdvertisement.getDisplayString().
 int getLocalUARTCreditsCount()
          Gets the current number of UART credits available on the local device.
 int getMaxLocalUARTCreditsCount()
          Gets the maximum number of local credits that are granted to the remote device, see setMaxLocalUARTCreditsCount().
 int getMinLocalUARTCreditsCount()
          Gets the minimum number of local credits the remote device should have at its disposal, see setMinLocalUARTCreditsCount().
 java.lang.String getName()
          Gets the preripheral's Bluetooth GATT name.
 int getRemoteUARTCreditsCount()
          Gets the current number of UART credits available on the remote device.
 java.lang.Object getTag()
          Gets the tag object.
 boolean isConnected()
          Gets the peripheral's TerminalIO connection state.
 boolean isConnecting()
          Gets the peripheral's connecting state.
 void readRSSI()
          Initiates the reading of the current RSSI value.
 void setListener(TIOPeripheralCallback listener)
          Sets the listener object to receive TIOPeripheral events, see TIOPeripheralCallback.
 void setMaxLocalUARTCreditsCount(int maxLocalUARTCreditsCount)
          Sets the maximum number of local credits that shall be granted to the remote device.
 void setMinLocalUARTCreditsCount(int minLocalUARTCreditsCount)
          Sets the minimum number of local credits that shall be granted to the remote device.
 void setShallBeSaved(boolean shallBeSaved)
          Determines whether the peripheral shall be persistently saved to file by the TIOManager.savePeripherals() method or not.
 void setTag(java.lang.Object tag)
          Sets a tag object.
 boolean shallBeSaved()
          Gets the information whether the peripheral shall be persistently saved to file by the TIOManager.savePeripherals() method or not.
 java.lang.String toString()
          Gets a string representation of this instance consisting of Bluetooth name and Bluetooth address.
 boolean updateWithAdvertisement(TIOAdvertisement advertisement)
          // * @deprecated (exclude for javadoc documentation generation) Internal method to be called by TIOManager only; do not call from application code.
 void writeUARTData(byte[] data)
          Writes UART data to the remote device.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Method Detail

connect

public void connect()
Initiates the establishing of a TerminalIO connection to the remote device. The TerminalIO connection establishment consists of various asynchronous operations over the air. In case of a successful connection establishment, the TIOPeripheralCallback method tioPeripheralDidConnect() method is invoked; otherwise tioPeripheralDidFailToConnect() will be invoked. Data exchange operations cannot be performed unless TIOPeripheralCallback.tioPeripheralDidConnect() has been invoked; the application may also check for isConnected(). To cancel a pending connection request, call disconnect(). If the remote device is configured to require security and has not been paired before with the local device, a silently running Bluetooth pairing process will be initiated.


createFromBluetoothDevice

public static TIOPeripheral createFromBluetoothDevice(BluetoothDevice device)
// * @deprecated (exclude for javadoc documentation generation) Internal method to be called by TIOManager only; do not call from application code.


createFromScanResult

public static TIOPeripheral createFromScanResult(BluetoothDevice device,
                                                 TIOAdvertisement advertisement)
// * @deprecated (exclude for javadoc documentation generation) Internal method to be called by TIOManager only; do not call from application code.


disconnect

public void disconnect()
Requests the operating system to disconnect from the remote device. The connection termination will be reported via the TIOPeripheralCallback method tioPeripheralDidDisconnect().


getAddress

public java.lang.String getAddress()
Gets the preripheral's Bluetooth address.

Returns:
A String instance representing the peripheral's Bluetooth address.

getAdvertisement

public TIOAdvertisement getAdvertisement()
Gets the TIOAdvertisement instance representing the latest advertisement received from the peripheral within a scan procedure. This property may be null if the TIOPeripheral instance has been reconstructed via a call to TIOManager.loadPeripherals() method and no subsequent scan has been performed yet.

Returns:
A TIOAdvertisement instance representing the peripheral's TerminalIO advertisement, or null.

getAdvertisementDisplayString

public java.lang.String getAdvertisementDisplayString()
Gets a string representation of the current advertisement, see also TIOAdvertisement.getDisplayString().

Returns:
A String representing the current advertisement, or an empty String if the advertisement is null.

getLocalUARTCreditsCount

public int getLocalUARTCreditsCount()
Gets the current number of UART credits available on the local device.

Returns:
An Integer containing the current number of UART credits available on the local device.

getMaxLocalUARTCreditsCount

public int getMaxLocalUARTCreditsCount()
Gets the maximum number of local credits that are granted to the remote device, see setMaxLocalUARTCreditsCount().

Returns:
An Integer containing the maximum number of local credits that are granted to the remote device.

getMinLocalUARTCreditsCount

public int getMinLocalUARTCreditsCount()
Gets the minimum number of local credits the remote device should have at its disposal, see setMinLocalUARTCreditsCount().

Returns:
An Integer containing the minimum number of local credits that are granted to the remote device.

getName

public java.lang.String getName()
Gets the preripheral's Bluetooth GATT name.

Returns:
A String instance representing the peripheral's Bluetooth GATT name.

getRemoteUARTCreditsCount

public int getRemoteUARTCreditsCount()
Gets the current number of UART credits available on the remote device.

Returns:
An Integer containing the current number of UART credits available on the remote device.

getTag

public java.lang.Object getTag()
Gets the tag object. This property is not used within the TIOPeripheral implementation.

Returns:
tag The Object instance tagged to this TIOPeripheral instance.

isConnected

public boolean isConnected()
Gets the peripheral's TerminalIO connection state.

Returns:
true if the TIOPeripheral instance is TerminalIO connected to the remote device, false otherwise.

isConnecting

public boolean isConnecting()
Gets the peripheral's connecting state.

Returns:
true if the TIOPeripheral instance is in the process of establishing a TerminalIO connection to the remote device, false otherwise.

readRSSI

public void readRSSI()
Initiates the reading of the current RSSI value. Requires the peripheral to be TerminalIO connected. Reading of the RSSI value is performed asynchronously. The identified RSSI value will be reported via the TIOPeripheralCallback method tioPeripheralDidUpdateRSSI().


setListener

public void setListener(TIOPeripheralCallback listener)
Sets the listener object to receive TIOPeripheral events, see TIOPeripheralCallback. If listener extends Activity, the event methods will be invoked on the UI thread.

Parameters:
listener - TIOPeripheralCallback implementor receiving TIOPeripheralCallback events.

setMaxLocalUARTCreditsCount

public void setMaxLocalUARTCreditsCount(int maxLocalUARTCreditsCount)
Sets the maximum number of local credits that shall be granted to the remote device. A credit is defined as the permission to send one data packet of 1 to 20 bytes. Receiving a UART data packet (1 to 20 bytes) from the remote device decrements the local credit counter by 1. As soon as the local credit counter reaches minLocalUARTCreditsCount, a number of (maxLocalUARTCreditsCount - minLocalUARTCreditsCount) credits will automatically be granted to the remote device; the local credit counter will then have the value of maxLocalUARTCreditsCount. maxLocalUARTCreditsCount shall only be set to values > minLocalUARTCreditsCount and <= 255. Default value is 255.

Parameters:
maxLocalUARTCreditsCount - Maximum number of local credits that shall be granted to the remote device.

setMinLocalUARTCreditsCount

public void setMinLocalUARTCreditsCount(int minLocalUARTCreditsCount)
Sets the minimum number of local credits that shall be granted to the remote device. A credit is defined as the permission to send one data packet of 1 to 20 bytes. Receiving a UART data packet (1 to 20 bytes) from the remote device decrements the local credit counter by 1. As soon as the local credit counter reaches minLocalUARTCreditsCount, a number of (maxLocalUARTCreditsCount - minLocalUARTCreditsCount) credits will automatically be granted to the remote device; the local credit counter will then have the value of maxLocalUARTCreditsCount. minLocalUARTCreditsCount shall only be set to values < maxLocalUARTCreditsCount and >= 0. Default value is 32.

Parameters:
minLocalUARTCreditsCount - Minimum number of local credits that shall be granted to the remote device.

setShallBeSaved

public void setShallBeSaved(boolean shallBeSaved)
Determines whether the peripheral shall be persistently saved to file by the TIOManager.savePeripherals() method or not.


setTag

public void setTag(java.lang.Object tag)
Sets a tag object. Allows for 'tagging' any application-defined object to the peripheral instance. This property is not used within the TIOPeripheral implementation.

Parameters:
tag - An Object instance to tag to this TIOPeripheral instance.

shallBeSaved

public boolean shallBeSaved()
Gets the information whether the peripheral shall be persistently saved to file by the TIOManager.savePeripherals() method or not.

Returns:
true if the peripheral shall be persistently saved to file by the TIOManager.savePeripherals() method, false otherwise.

toString

public java.lang.String toString()
Gets a string representation of this instance consisting of Bluetooth name and Bluetooth address.

Overrides:
toString in class java.lang.Object
Returns:
A String instance consisting of this instance's Bluetooth name and Bluetooth address.

updateWithAdvertisement

public boolean updateWithAdvertisement(TIOAdvertisement advertisement)
// * @deprecated (exclude for javadoc documentation generation) Internal method to be called by TIOManager only; do not call from application code.


writeUARTData

public void writeUARTData(byte[] data)
Writes UART data to the remote device. Requires the peripheral to be TerminalIO connected. The specified data will be appended to a write buffer, so there is generally no limitation for the data's size except for memory conditions within the operating system. Nevertheless, data sizes should be considered carefully and transmission rates and power consumption should be taken into account. For each data block written, the TIOPeripheralCallback method tioPeripheralDidWriteNumberOfUARTBytes() will be invoked reporting the number of bytes written. If there are no more data to be written, the TIOPeripheralDelegate method tioPeripheralUARTWriteBufferEmpty() will be invoked.

Parameters:
data - Data to be written.