android.bluetooth
Class RfcommSocket

java.lang.Object
  android.bluetooth.RfcommSocket

public class RfcommSocket
extends Object

The Android Bluetooth API is not finalized, and *will* change. Use at your own risk. This class implements an API to the Bluetooth RFCOMM layer. An RFCOMM socket is similar to a normal socket in that it takes an address and a port number. The difference is of course that the address is a Bluetooth-device address, and the port number is an RFCOMM channel. The API allows for the establishment of listening sockets via methods bind, listen, and accept, as well as for the making of outgoing connections with connect, connectAsync, and waitForAsyncConnect. After constructing a socket, you need to create it and then destroy it when you are done using it. Both create and accept return a FileDescriptor for the actual data. Alternatively, you may call getInputStream and getOutputStream to retrieve the respective streams without going through the FileDescriptor.

Field Summary

protected FileInputStream	mInputStream Maintained by getInputStream.
protected FileOutputStream	mOutputStream Maintained by getOutputStream.

Constructor Summary

RfcommSocket()
Constructor.

Method Summary

FileDescriptor	accept(RfcommSocket newSock, int timeoutMs) Accepts incoming-connection requests for a listening socket bound to an RFCOMM channel.
boolean	bind(String device) Binds a listening socket to the local device, or a non-listening socket to a remote device.
boolean	bind(String device, int port) Binds a listening socket to the local device, or a non-listening socket to a remote device.
boolean	connect(String address, int port) Starts a blocking connect to a remote RFCOMM socket.
boolean	connectAsync(String address, int port) Starts an asynchronous (nonblocking) connect to a remote RFCOMM socket.
FileDescriptor	create() Creates a socket.
void	destroy() Destroys a socket created by create.
protected void	finalize() Called by the GC to clean up the native data that we set up when we construct the object.
FileDescriptor	getFileDescriptor() Returns the FileDescriptor of the socket.
InputStream	getInputStream() Retrieves the input stream from the socket.
OutputStream	getOutputStream() Retrieves the output stream from the socket.
int	getPort() Get the port (rfcomm channel) associated with this socket.
int	getRemainingAcceptWaitingTimeMs() Returns the number of milliseconds left to wait after the last call to accept.
int	getRemainingAsyncConnectWaitingTimeMs() Returns the number of milliseconds left to wait after the last call to waitForAsyncConnect.
void	interruptAsyncConnect() Interrupts an asynchronous connect in progress.
boolean	isConnected() Tells you whether a socket is connected to another socket.
boolean	isConnecting() Tells you whether there is an asynchronous connect in progress.
boolean	isInputConnected() Determines whether input is connected (i.e., whether you can receive data on this socket.)
boolean	isListening() Return true if this socket is listening (listen(int) has been called successfully).
boolean	isOutputConnected() Determines whether output is connected (i.e., whether you can send data on this socket.)
boolean	listen(int backlog) Starts listening for incoming connections on this socket, after it has been bound to an address and RFCOMM channel with bind.
boolean	shutdown() Shuts down both directions on a socket.
boolean	shutdownInput() Shuts down the input stream of the socket, but leaves the output stream in its current state.
boolean	shutdownOutput() Shut down the output stream of the socket, but leaves the input stream in its current state.
int	waitForAsyncConnect(int timeoutMs) Blocks for a specified amount of milliseconds while waiting for an asynchronous connect to complete.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mInputStream

protected FileInputStream mInputStream

Maintained by getInputStream.

mOutputStream

protected FileOutputStream mOutputStream

Maintained by getOutputStream.

Constructor Detail

RfcommSocket

public RfcommSocket()

Constructor.

Method Detail

finalize

protected void finalize()
                 throws Throwable

Called by the GC to clean up the native data that we set up when we construct the object.

Overrides:

finalize in class Object

Throws:

Throwable - The virtual machine ignores any exceptions which are thrown during finalization.

create

public FileDescriptor create()
                      throws IOException

Creates a socket. You need to call this method before performing any other operation on a socket.

Returns:

FileDescriptor for the data stream.

Throws:

IOException

See Also:

destroy()

destroy

public void destroy()

Destroys a socket created by create. Call this function when you no longer use the socket in order to release the underlying OS resources.

See Also:

create()

getFileDescriptor

public FileDescriptor getFileDescriptor()
                                 throws IOException

Returns the FileDescriptor of the socket.

Returns:

the FileDescriptor

Throws:

IOException - when the socket has not been created.

getInputStream

public InputStream getInputStream()
                           throws IOException

Retrieves the input stream from the socket. Alternatively, you can do that from the FileDescriptor returned by create or accept.

Returns:

InputStream

Throws:

IOException - if you have not called create on the socket.

getOutputStream

public OutputStream getOutputStream()
                             throws IOException

Retrieves the output stream from the socket. Alternatively, you can do that from the FileDescriptor returned by create or accept.

Returns:

OutputStream

Throws:

IOException - if you have not called create on the socket.

connect

public boolean connect(String address,
                       int port)
                throws IOException

Starts a blocking connect to a remote RFCOMM socket. It takes the address of a device and the RFCOMM channel (port) to which to connect.

Parameters:

address - is the Bluetooth address of the remote device.

port - is the RFCOMM channel

Returns:

true on success, false on failure

Throws:

IOException - if create has not been called.

See Also:

connectAsync(String, int)

connectAsync

public boolean connectAsync(String address,
                            int port)
                     throws IOException

Starts an asynchronous (nonblocking) connect to a remote RFCOMM socket. It takes the address of the device to connect to, as well as the RFCOMM channel (port). On successful return (return value is true), you need to call method waitForAsyncConnect to block for up to a specified number of milliseconds while waiting for the asyncronous connect to complete.

Parameters:

address - of remote device

port - the RFCOMM channel

Returns:

true when the asynchronous connect has successfully started, false if there was an error.

Throws:

IOException - is you have not called create

See Also:

waitForAsyncConnect(int), getRemainingAsyncConnectWaitingTimeMs(), connect(String, int)

interruptAsyncConnect

public void interruptAsyncConnect()
                           throws IOException

Interrupts an asynchronous connect in progress. This method does nothing when there is no asynchronous connect in progress.

Throws:

IOException - if you have not called create.

See Also:

connectAsync(String, int)

isConnecting

public boolean isConnecting()

Tells you whether there is an asynchronous connect in progress. This method returns an undefined value when there is a synchronous connect in progress.

Returns:

true if there is an asyc connect in progress, false otherwise

See Also:

connectAsync(String, int)

waitForAsyncConnect

public int waitForAsyncConnect(int timeoutMs)
                        throws IOException

Blocks for a specified amount of milliseconds while waiting for an asynchronous connect to complete. Returns an integer value to indicate one of the following: the connect succeeded, the connect is still in progress, or the connect failed. It is possible for this method to block for less than the time specified by the user, and still return zero (i.e., async connect is still in progress.) For this reason, if the return value is zero, you need to call method getRemainingAsyncConnectWaitingTimeMs to retrieve the remaining time.

Parameters:

timeoutMs - the time to block while waiting for the async connect to complete.

Returns:

a positive value if the connect succeeds; zero, if the connect is still in progress, and a negative value if the connect failed.

Throws:

IOException

See Also:

getRemainingAsyncConnectWaitingTimeMs(), connectAsync(String, int)

getRemainingAsyncConnectWaitingTimeMs

public int getRemainingAsyncConnectWaitingTimeMs()

Returns the number of milliseconds left to wait after the last call to waitForAsyncConnect. It is possible that waitForAsyncConnect() waits for less than the time specified by the user, and still returns zero (i.e., async connect is still in progress.) For this reason, if the return value is zero, you need to call this method to retrieve the remaining time before you call waitForAsyncConnect again.

Returns:

the remaining timeout in milliseconds.

See Also:

waitForAsyncConnect(int), connectAsync(String, int)

shutdown

public boolean shutdown()
                 throws IOException

Shuts down both directions on a socket.

Returns:

true on success, false on failure; if the return value is false, the socket might be left in a patially shut-down state (i.e. one direction is shut down, but the other is still open.) In this case, you should destroy and then create the socket again.

Throws:

IOException - is you have not caled create.

See Also:

shutdownInput(), shutdownOutput()

shutdownInput

public boolean shutdownInput()
                      throws IOException

Shuts down the input stream of the socket, but leaves the output stream in its current state.

Returns:

true on success, false on failure

Throws:

IOException - is you have not called create

See Also:

shutdown(), shutdownOutput()

shutdownOutput

public boolean shutdownOutput()
                       throws IOException

Shut down the output stream of the socket, but leaves the input stream in its current state.

Returns:

true on success, false on failure

Throws:

IOException - is you have not called create

See Also:

shutdown(), shutdownInput()

isConnected

public boolean isConnected()

Tells you whether a socket is connected to another socket. This could be for input or output or both.

Returns:

true if connected, false otherwise.

See Also:

isInputConnected(), isOutputConnected()

isInputConnected

public boolean isInputConnected()

Determines whether input is connected (i.e., whether you can receive data on this socket.)

Returns:

true if input is connected, false otherwise.

See Also:

isConnected(), isOutputConnected()

isOutputConnected

public boolean isOutputConnected()

Determines whether output is connected (i.e., whether you can send data on this socket.)

Returns:

true if output is connected, false otherwise.

See Also:

isConnected(), isInputConnected()

bind

public boolean bind(String device)
             throws IOException

Binds a listening socket to the local device, or a non-listening socket to a remote device. The port is automatically selected as the first available port in the range 12 to 30. NOTE: Currently we ignore the device parameter and always bind the socket to the local device, assuming that it is a listening socket. TODO: Use bind(0) in native code to have the kernel select an unused port.

Parameters:

device - Bluetooth address of device to bind to (currently ignored).

Returns:

true on success, false on failure

Throws:

IOException - if you have not called create

See Also:

listen(int), accept(RfcommSocket,int)

bind

public boolean bind(String device,
                    int port)
             throws IOException

Binds a listening socket to the local device, or a non-listening socket to a remote device. NOTE: Currently we ignore the device parameter and always bind the socket to the local device, assuming that it is a listening socket.

Parameters:

device - Bluetooth address of device to bind to (currently ignored).

port - RFCOMM channel to bind socket to.

Returns:

true on success, false on failure

Throws:

IOException - if you have not called create

See Also:

listen(int), accept(RfcommSocket,int)

listen

public boolean listen(int backlog)
               throws IOException

Starts listening for incoming connections on this socket, after it has been bound to an address and RFCOMM channel with bind.

Parameters:

backlog - the number of pending incoming connections to queue for accept.

Returns:

true on success, false on failure

Throws:

IOException - if you have not called create or if the socket has not been bound to a device and RFCOMM channel.

accept

public FileDescriptor accept(RfcommSocket newSock,
                             int timeoutMs)
                      throws IOException

Accepts incoming-connection requests for a listening socket bound to an RFCOMM channel. The user may provide a time to wait for an incoming connection. Note that this method may return null (i.e., no incoming connection) before the user-specified timeout expires. For this reason, on a null return value, you need to call getRemainingAcceptWaitingTimeMs in order to see how much time is left to wait, before you call this method again.

Parameters:

newSock - is set to the new socket that is created as a result of a successful accept.

timeoutMs - time (in milliseconds) to block while waiting to an incoming-connection request. A negative value is an infinite wait.

Returns:

FileDescriptor of newSock on success, null on failure. Failure occurs if the timeout expires without a successful connect.

Throws:

IOException - if the socket has not been createed, is not bound, or is not a listening socket.

See Also:

bind(String, int), listen(int), getRemainingAcceptWaitingTimeMs()

getRemainingAcceptWaitingTimeMs

public int getRemainingAcceptWaitingTimeMs()

Returns the number of milliseconds left to wait after the last call to accept. Since accept() may return null (i.e., no incoming connection) before the user-specified timeout expires, you need to call this method in order to see how much time is left to wait, and wait for that amount of time before you call accept again.

Returns:

the remaining time, in milliseconds.

getPort

public int getPort()
            throws IOException

Get the port (rfcomm channel) associated with this socket. This is only valid if the port has been set via a successful call to bind(String, int), connect(String, int) or connectAsync(String, int). This can be checked with isListening() and isConnected().

Returns:

Port (rfcomm channel)

Throws:

IOException

isListening

public boolean isListening()

Return true if this socket is listening (listen(int) has been called successfully).