path: root/core/java/android/bluetooth/RfcommSocket.java

/*
 * Copyright (C) 2007 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.bluetooth;

import java.io.IOException;
import java.io.FileOutputStream;
import java.io.FileInputStream;
import java.io.OutputStream;
import java.io.InputStream;
import java.io.FileDescriptor;

/**
 * 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
 * {@link #bind(String, int) bind}, {@link #listen(int) listen}, and
 * {@link #accept(RfcommSocket, int) accept}, as well as for the making of
 * outgoing connections with {@link #connect(String, int) connect},
 * {@link #connectAsync(String, int) connectAsync}, and
 * {@link #waitForAsyncConnect(int) waitForAsyncConnect}.
 * 
 * After constructing a socket, you need to {@link #create() create} it and then
 * {@link #destroy() destroy} it when you are done using it. Both
 * {@link #create() create} and {@link #accept(RfcommSocket, int) accept} return
 * a {@link java.io.FileDescriptor FileDescriptor} for the actual data.
 * Alternatively, you may call {@link #getInputStream() getInputStream} and
 * {@link #getOutputStream() getOutputStream} to retrieve the respective streams
 * without going through the FileDescriptor.
 *
 * @hide
 */
public class RfcommSocket {

    /**
     * Used by the native implementation of the class.
     */
    private int mNativeData;

    /**
     * Used by the native implementation of the class.
     */
    private int mPort;

    /**
     * Used by the native implementation of the class.
     */
    private String mAddress;

    /**
     * We save the return value of {@link #create() create} and
     * {@link #accept(RfcommSocket,int) accept} in this variable, and use it to
     * retrieve the I/O streams.
     */
    private FileDescriptor mFd;

    /**
     * After a call to {@link #waitForAsyncConnect(int) waitForAsyncConnect},
     * if the return value is zero, then, the the remaining time left to wait is
     * written into this variable (by the native implementation). It is possible
     * that {@link #waitForAsyncConnect(int) waitForAsyncConnect} returns before
     * the user-specified timeout expires, which is why we save the remaining
     * time in this member variable for the user to retrieve by calling method
     * {@link #getRemainingAsyncConnectWaitingTimeMs() getRemainingAsyncConnectWaitingTimeMs}.
     */
    private int mTimeoutRemainingMs;

    /**
     * Set to true when an asynchronous (nonblocking) connect is in progress.
     * {@see #connectAsync(String,int)}.
     */
    private boolean mIsConnecting;

    /**
     * Set to true after a successful call to {@link #bind(String,int) bind} and
     * used for error checking in {@link #listen(int) listen}. Reset to false
     * on {@link #destroy() destroy}.
     */
    private boolean mIsBound = false;

    /**
     * Set to true after a successful call to {@link #listen(int) listen} and
     * used for error checking in {@link #accept(RfcommSocket,int) accept}.
     * Reset to false on {@link #destroy() destroy}.
     */
    private boolean mIsListening = false;

    /**
     * Used to store the remaining time after an accept with a non-negative
     * timeout returns unsuccessfully. It is possible that a blocking
     * {@link #accept(int) accept} may wait for less than the time specified by
     * the user, which is why we store the remainder in this member variable for
     * it to be retrieved with method
     * {@link #getRemainingAcceptWaitingTimeMs() getRemainingAcceptWaitingTimeMs}.
     */
    private int mAcceptTimeoutRemainingMs;

    /**
     * Maintained by {@link #getInputStream() getInputStream}.
     */
    protected FileInputStream mInputStream;

    /**
     * Maintained by {@link #getOutputStream() getOutputStream}.
     */
    protected FileOutputStream mOutputStream;

    private native void initializeNativeDataNative();

    /**
     * Constructor.
     */
    public RfcommSocket() {
        initializeNativeDataNative();
    }

    private native void cleanupNativeDataNative();

    /**
     * Called by the GC to clean up the native data that we set up when we
     * construct the object.
     */
    protected void finalize() throws Throwable {
        try {
            cleanupNativeDataNative();
        } finally {
            super.finalize();
        }
    }

    private native static void classInitNative();

    static {
        classInitNative();
    }

    /**
     * Creates a socket. You need to call this method before performing any
     * other operation on a socket.
     * 
     * @return FileDescriptor for the data stream.
     * @throws IOException
     * @see #destroy()
     */
    public FileDescriptor create() throws IOException {
        if (mFd == null) {
            mFd = createNative();
        }
        if (mFd == null) {
            throw new IOException("socket not created");
        }
        return mFd;
    }

    private native FileDescriptor createNative();

    /**
     * Destroys a socket created by {@link #create() create}. Call this
     * function when you no longer use the socket in order to release the
     * underlying OS resources.
     * 
     * @see #create()
     */
    public void destroy() {
        synchronized (this) {
            destroyNative();
            mFd = null;
            mIsBound = false;
            mIsListening = false;
        }
    }

    private native void destroyNative();

    /**
     * Returns the {@link java.io.FileDescriptor FileDescriptor} of the socket.
     * 
     * @return the FileDescriptor
     * @throws IOException
     *             when the socket has not been {@link #create() created}.
     */
    public FileDescriptor getFileDescriptor() throws IOException {
        if (mFd == null) {
            throw new IOException("socket not created");
        }
        return mFd;
    }

    /**
     * Retrieves the input stream from the socket. Alternatively, you can do
     * that from the FileDescriptor returned by {@link #create() create} or
     * {@link #accept(RfcommSocket, int) accept}.
     * 
     * @return InputStream
     * @throws IOException
     *             if you have not called {@link #create() create} on the
     *             socket.
     */
    public InputStream getInputStream() throws IOException {
        if (mFd == null) {
            throw new IOException("socket not created");
        }

        synchronized (this) {
            if (mInputStream == null) {
                mInputStream = new FileInputStream(mFd);
            }

            return mInputStream;
        }
    }

    /**
     * Retrieves the output stream from the socket. Alternatively, you can do
     * that from the FileDescriptor returned by {@link #create() create} or
     * {@link #accept(RfcommSocket, int) accept}.
     * 
     * @return OutputStream
     * @throws IOException
     *             if you have not called {@link #create() create} on the
     *             socket.
     */
    public OutputStream getOutputStream() throws IOException {
        if (mFd == null) {
            throw new IOException("socket not created");
        }

        synchronized (this) {
            if (mOutputStream == null) {
                mOutputStream = new FileOutputStream(mFd);
            }

            return mOutputStream;
        }
    }

    /**
     * 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.
     * 
     * @param address
     *            is the Bluetooth address of the remote device.
     * @param port
     *            is the RFCOMM channel
     * @return true on success, false on failure
     * @throws IOException
     *             if {@link #create() create} has not been called.
     * @see #connectAsync(String, int)
     */
    public boolean connect(String address, int port) throws IOException {
        synchronized (this) {
            if (mFd == null) {
                throw new IOException("socket not created");
            }
            return connectNative(address, port);
        }
    }

    private native boolean connectNative(String address, int port);

    /**
     * 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 {@link #waitForAsyncConnect(int) waitForAsyncConnect} to
     * block for up to a specified number of milliseconds while waiting for the
     * asyncronous connect to complete.
     * 
     * @param address
     *            of remote device
     * @param port
     *            the RFCOMM channel
     * @return true when the asynchronous connect has successfully started,
     *         false if there was an error.
     * @throws IOException
     *             is you have not called {@link #create() create}
     * @see #waitForAsyncConnect(int)
     * @see #getRemainingAsyncConnectWaitingTimeMs()
     * @see #connect(String, int)
     */
    public boolean connectAsync(String address, int port) throws IOException {
        synchronized (this) {
            if (mFd == null) {
                throw new IOException("socket not created");
            }
            mIsConnecting = connectAsyncNative(address, port);
            return mIsConnecting;
        }
    }

    private native boolean connectAsyncNative(String address, int port);

    /**
     * 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 {@link #create() create}.
     * @see #connectAsync(String, int)
     */
    public void interruptAsyncConnect() throws IOException {
        synchronized (this) {
            if (mFd == null) {
                throw new IOException("socket not created");
            }
            if (mIsConnecting) {
                mIsConnecting = !interruptAsyncConnectNative();
            }
        }
    }

    private native boolean interruptAsyncConnectNative();

    /**
     * Tells you whether there is an asynchronous connect in progress. This
     * method returns an undefined value when there is a synchronous connect in
     * progress.
     * 
     * @return true if there is an asyc connect in progress, false otherwise
     * @see #connectAsync(String, int)
     */
    public boolean isConnecting() {
        return mIsConnecting;
    }

    /**
     * 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
     * {@link #getRemainingAsyncConnectWaitingTimeMs() getRemainingAsyncConnectWaitingTimeMs}
     * to retrieve the remaining time.
     * 
     * @param timeoutMs
     *            the time to block while waiting for the async connect to
     *            complete.
     * @return 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 #getRemainingAsyncConnectWaitingTimeMs()
     * @see #connectAsync(String, int)
     */
    public int waitForAsyncConnect(int timeoutMs) throws IOException {
        synchronized (this) {
            if (mFd == null) {
                throw new IOException("socket not created");
            }
            int ret = waitForAsyncConnectNative(timeoutMs);
            if (ret != 0) {
                mIsConnecting = false;
            }
            return ret;
        }
    }

    private native int waitForAsyncConnectNative(int timeoutMs);

    /**
     * Returns the number of milliseconds left to wait after the last call to
     * {@link #waitForAsyncConnect(int) 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.
     * 
     * @return the remaining timeout in milliseconds.
     * @see #waitForAsyncConnect(int)
     * @see #connectAsync(String, int)
     */
    public int getRemainingAsyncConnectWaitingTimeMs() {
        return mTimeoutRemainingMs;
    }

    /**
     * Shuts down both directions on a socket.
     * 
     * @return 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 {@link #destroy() destroy} and then
     *         {@link #create() create} the socket again.
     * @throws IOException
     *             is you have not caled {@link #create() create}.
     * @see #shutdownInput()
     * @see #shutdownOutput()
     */
    public boolean shutdown() throws IOException {
        synchronized (this) {
            if (mFd == null) {
                throw new IOException("socket not created");
            }
            if (shutdownNative(true)) {
                return shutdownNative(false);
            }

            return false;
        }
    }

    /**
     * Shuts down the input stream of the socket, but leaves the output stream
     * in its current state.
     * 
     * @return true on success, false on failure
     * @throws IOException
     *             is you have not called {@link #create() create}
     * @see #shutdown()
     * @see #shutdownOutput()
     */
    public boolean shutdownInput() throws IOException {
        synchronized (this) {
            if (mFd == null) {
                throw new IOException("socket not created");
            }
            return shutdownNative(true);
        }
    }

    /**
     * Shut down the output stream of the socket, but leaves the input stream in
     * its current state.
     * 
     * @return true on success, false on failure
     * @throws IOException
     *             is you have not called {@link #create() create}
     * @see #shutdown()
     * @see #shutdownInput()
     */
    public boolean shutdownOutput() throws IOException {
        synchronized (this) {
            if (mFd == null) {
                throw new IOException("socket not created");
            }
            return shutdownNative(false);
        }
    }

    private native boolean shutdownNative(boolean shutdownInput);

    /**
     * Tells you whether a socket is connected to another socket. This could be
     * for input or output or both.
     * 
     * @return true if connected, false otherwise.
     * @see #isInputConnected()
     * @see #isOutputConnected()
     */
    public boolean isConnected() {
        return isConnectedNative() > 0;
    }

    /**
     * Determines whether input is connected (i.e., whether you can receive data
     * on this socket.)
     * 
     * @return true if input is connected, false otherwise.
     * @see #isConnected()
     * @see #isOutputConnected()
     */
    public boolean isInputConnected() {
        return (isConnectedNative() & 1) != 0;
    }

    /**
     * Determines whether output is connected (i.e., whether you can send data
     * on this socket.)
     * 
     * @return true if output is connected, false otherwise.
     * @see #isConnected()
     * @see #isInputConnected()
     */
    public boolean isOutputConnected() {
        return (isConnectedNative() & 2) != 0;
    }

    private native int isConnectedNative();

    /**
     * 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.
     *
     * @param device
     *            Bluetooth address of device to bind to (currently ignored).
     * @return true on success, false on failure
     * @throws IOException
     *             if you have not called {@link #create() create}
     * @see #listen(int)
     * @see #accept(RfcommSocket,int)
     */
    public boolean bind(String device) throws IOException {
        if (mFd == null) {
            throw new IOException("socket not created");
        }
        for (int port = 12; port <= 30; port++) {
            if (bindNative(device, port)) {
                mIsBound = true;
                return true;
            }
        }
        mIsBound = false;
        return false;
    }

    /**
     * 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.
     *
     * @param device
     *            Bluetooth address of device to bind to (currently ignored).
     * @param port
     *            RFCOMM channel to bind socket to.
     * @return true on success, false on failure
     * @throws IOException
     *             if you have not called {@link #create() create}
     * @see #listen(int)
     * @see #accept(RfcommSocket,int)
     */
    public boolean bind(String device, int port) throws IOException {
        if (mFd == null) {
            throw new IOException("socket not created");
        }
        mIsBound = bindNative(device, port);
        return mIsBound;
    }

    private native boolean bindNative(String device, int port);

    /**
     * Starts listening for incoming connections on this socket, after it has
     * been bound to an address and RFCOMM channel with
     * {@link #bind(String,int) bind}.
     * 
     * @param backlog
     *            the number of pending incoming connections to queue for
     *            {@link #accept(RfcommSocket, int) accept}.
     * @return true on success, false on failure
     * @throws IOException
     *             if you have not called {@link #create() create} or if the
     *             socket has not been bound to a device and RFCOMM channel.
     */
    public boolean listen(int backlog) throws IOException {
        if (mFd == null) {
            throw new IOException("socket not created");
        }
        if (!mIsBound) {
            throw new IOException("socket not bound");
        }
        mIsListening = listenNative(backlog);
        return mIsListening;
    }

    private native boolean listenNative(int backlog);

    /**
     * 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
     * {@link #getRemainingAcceptWaitingTimeMs() getRemainingAcceptWaitingTimeMs}
     * in order to see how much time is left to wait, before you call this
     * method again.
     * 
     * @param newSock
     *            is set to the new socket that is created as a result of a
     *            successful accept.
     * @param timeoutMs
     *            time (in milliseconds) to block while waiting to an
     *            incoming-connection request. A negative value is an infinite
     *            wait.
     * @return 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 {@link #create() create}ed, is
     *             not bound, or is not a listening socket.
     * @see #bind(String, int)
     * @see #listen(int)
     * @see #getRemainingAcceptWaitingTimeMs()
     */
    public FileDescriptor accept(RfcommSocket newSock, int timeoutMs)
            throws IOException {
        synchronized (newSock) {
            if (mFd == null) {
                throw new IOException("socket not created");
            }
            if (mIsListening == false) {
                throw new IOException("not listening on socket");
            }
            newSock.mFd = acceptNative(newSock, timeoutMs);
            return newSock.mFd;
        }
    }

    /**
     * Returns the number of milliseconds left to wait after the last call to
     * {@link #accept(RfcommSocket, int) 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.
     * 
     * @return the remaining time, in milliseconds.
     */
    public int getRemainingAcceptWaitingTimeMs() {
        return mAcceptTimeoutRemainingMs;
    }

    private native FileDescriptor acceptNative(RfcommSocket newSock,
            int timeoutMs);

    /**
     * Get the port (rfcomm channel) associated with this socket.
     *
     * This is only valid if the port has been set via a successful call to
     * {@link #bind(String, int)}, {@link #connect(String, int)}
     * or {@link #connectAsync(String, int)}. This can be checked
     * with {@link #isListening()} and {@link #isConnected()}.
     * @return Port (rfcomm channel)
     */
    public int getPort() throws IOException {
        if (mFd == null) {
            throw new IOException("socket not created");
        }
        if (!mIsListening && !isConnected()) {
            throw new IOException("not listening or connected on socket");
        }
        return mPort;
    }

    /**
     * Return true if this socket is listening ({@link #listen(int)}
     * has been called successfully).
     */
    public boolean isListening() {
        return mIsListening;
    }
}