BluetoothServerSocket.java revision 52cde7279bad58285704498eea57bdaf9e595b49 
1/*
2 * Copyright (C) 2009 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.bluetooth;
18
19import android.os.Handler;
20
21import java.io.Closeable;
22import java.io.IOException;
23
24/**
25 * A listening Bluetooth socket.
26 *
27 * <p>The interface for Bluetooth Sockets is similar to that of TCP sockets:
28 * {@link java.net.Socket} and {@link java.net.ServerSocket}. On the server
29 * side, use a {@link BluetoothServerSocket} to create a listening server
30 * socket. It will return a new, connected {@link BluetoothSocket} on an
31 * accepted connection. On the client side, use the same
32 * {@link BluetoothSocket} object to both intiate the outgoing connection,
33 * and to manage the connected socket.
34 *
35 * <p>The most common type of Bluetooth Socket is RFCOMM. RFCOMM is a
36 * connection orientated, streaming transport over Bluetooth. It is also known
37 * as the Serial Port Profile (SPP).
38 *
39 * <p>Use {@link BluetoothDevice#createRfcommSocket} to create a new {@link
40 * BluetoothSocket} ready for an outgoing connection to a remote
41 * {@link BluetoothDevice}.
42 *
43 * <p>Use {@link BluetoothAdapter#listenUsingRfcomm} to create a listening
44 * {@link BluetoothServerSocket} ready for incoming connections to the local
45 * {@link BluetoothAdapter}.
46 *
47 * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread
48 * safe. In particular, {@link #close} will always immediately abort ongoing
49 * operations and close the socket.
50 *
51 * <p>All methods on a {@link BluetoothServerSocket} require
52 * {@link android.Manifest.permission#BLUETOOTH}
53 */
54public final class BluetoothServerSocket implements Closeable {
55
56    /*package*/ final BluetoothSocket mSocket;
57    private Handler mHandler;
58    private int mMessage;
59
60    /**
61     * Construct a socket for incoming connections.
62     * @param type    type of socket
63     * @param auth    require the remote device to be authenticated
64     * @param encrypt require the connection to be encrypted
65     * @param port    remote port
66     * @throws IOException On error, for example Bluetooth not available, or
67     *                     insufficient priveleges
68     */
69    /*package*/ BluetoothServerSocket(int type, boolean auth, boolean encrypt, int port)
70            throws IOException {
71        mSocket = new BluetoothSocket(type, -1, auth, encrypt, null, port);
72    }
73
74    /**
75     * Block until a connection is established.
76     * <p>Returns a connected {@link BluetoothSocket} on successful connection.
77     * <p>Once this call returns, it can be called again to accept subsequent
78     * incoming connections.
79     * <p>{@link #close} can be used to abort this call from another thread.
80     * @return a connected {@link BluetoothSocket}
81     * @throws IOException on error, for example this call was aborted, or
82     *                     timeout
83     */
84    public BluetoothSocket accept() throws IOException {
85        return accept(-1);
86    }
87
88    /**
89     * Block until a connection is established, with timeout.
90     * <p>Returns a connected {@link BluetoothSocket} on successful connection.
91     * <p>Once this call returns, it can be called again to accept subsequent
92     * incoming connections.
93     * <p>{@link #close} can be used to abort this call from another thread.
94     * @return a connected {@link BluetoothSocket}
95     * @throws IOException on error, for example this call was aborted, or
96     *                     timeout
97     */
98    public BluetoothSocket accept(int timeout) throws IOException {
99        return mSocket.accept(timeout);
100    }
101
102    /**
103     * Immediately close this socket, and release all associated resources.
104     * <p>Causes blocked calls on this socket in other threads to immediately
105     * throw an IOException.
106     */
107    public void close() throws IOException {
108        synchronized (this) {
109            if (mHandler != null) {
110                mHandler.obtainMessage(mMessage).sendToTarget();
111            }
112        }
113        mSocket.close();
114    }
115
116    /*package*/ synchronized void setCloseHandler(Handler handler, int message) {
117        mHandler = handler;
118        mMessage = message;
119    }
120}
121