Build 1.0_r1(from source)

android.bluetooth
Class RfcommSocket

java.lang.Object
  extended by 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).


Build 1.0_r1(from source)

Please submit a feedback, bug or feature