Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 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 | |
| 17 | package android.bluetooth; |
| 18 | |
Nick Pelly | 24bb9b8 | 2009-10-02 20:34:18 -0700 | [diff] [blame] | 19 | import android.os.Handler; |
| 20 | |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 21 | import java.io.Closeable; |
| 22 | import java.io.IOException; |
| 23 | |
| 24 | /** |
Nick Pelly | 45e2704 | 2009-08-19 11:00:00 -0700 | [diff] [blame] | 25 | * A listening Bluetooth socket. |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 26 | * |
Nick Pelly | 45e2704 | 2009-08-19 11:00:00 -0700 | [diff] [blame] | 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 |
Scott Main | 9fab0ae | 2009-11-03 18:17:59 -0800 | [diff] [blame] | 30 | * socket. When a connection is accepted by the {@link BluetoothServerSocket}, |
| 31 | * it will return a new {@link BluetoothSocket} to manage the connection. |
Jake Hamby | f51eada | 2010-09-21 13:39:53 -0700 | [diff] [blame] | 32 | * On the client side, use a single {@link BluetoothSocket} to both initiate |
Scott Main | 9fab0ae | 2009-11-03 18:17:59 -0800 | [diff] [blame] | 33 | * an outgoing connection and to manage the connection. |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 34 | * |
Scott Main | 9fab0ae | 2009-11-03 18:17:59 -0800 | [diff] [blame] | 35 | * <p>The most common type of Bluetooth socket is RFCOMM, which is the type |
| 36 | * supported by the Android APIs. RFCOMM is a connection-oriented, streaming |
| 37 | * transport over Bluetooth. It is also known as the Serial Port Profile (SPP). |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 38 | * |
Jake Hamby | f51eada | 2010-09-21 13:39:53 -0700 | [diff] [blame] | 39 | * <p>To create a listening {@link BluetoothServerSocket} that's ready for |
Scott Main | 9fab0ae | 2009-11-03 18:17:59 -0800 | [diff] [blame] | 40 | * incoming connections, use |
| 41 | * {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord |
| 42 | * BluetoothAdapter.listenUsingRfcommWithServiceRecord()}. Then call |
| 43 | * {@link #accept()} to listen for incoming connection requests. This call |
| 44 | * will block until a connection is established, at which point, it will return |
Scott Main | 6d95fc0 | 2009-11-19 17:00:19 -0800 | [diff] [blame] | 45 | * a {@link BluetoothSocket} to manage the connection. Once the {@link |
| 46 | * BluetoothSocket} is acquired, it's a good idea to call {@link #close()} on |
| 47 | * the {@link BluetoothServerSocket} when it's no longer needed for accepting |
| 48 | * connections. Closing the {@link BluetoothServerSocket} will <em>not</em> |
| 49 | * close the returned {@link BluetoothSocket}. |
Nick Pelly | 45e2704 | 2009-08-19 11:00:00 -0700 | [diff] [blame] | 50 | * |
Scott Main | 9fab0ae | 2009-11-03 18:17:59 -0800 | [diff] [blame] | 51 | * <p>{@link BluetoothServerSocket} is thread |
Nick Pelly | 45e2704 | 2009-08-19 11:00:00 -0700 | [diff] [blame] | 52 | * safe. In particular, {@link #close} will always immediately abort ongoing |
Scott Main | 9fab0ae | 2009-11-03 18:17:59 -0800 | [diff] [blame] | 53 | * operations and close the server socket. |
Nick Pelly | cf44059 | 2009-09-08 10:12:06 -0700 | [diff] [blame] | 54 | * |
Scott Main | 9fab0ae | 2009-11-03 18:17:59 -0800 | [diff] [blame] | 55 | * <p class="note"><strong>Note:</strong> |
| 56 | * Requires the {@link android.Manifest.permission#BLUETOOTH} permission. |
| 57 | * |
| 58 | * {@see BluetoothSocket} |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 59 | */ |
| 60 | public final class BluetoothServerSocket implements Closeable { |
Nick Pelly | 71c3c78 | 2009-09-02 11:51:35 -0700 | [diff] [blame] | 61 | |
Nick Pelly | bd022f4 | 2009-08-14 18:33:38 -0700 | [diff] [blame] | 62 | /*package*/ final BluetoothSocket mSocket; |
Nick Pelly | 24bb9b8 | 2009-10-02 20:34:18 -0700 | [diff] [blame] | 63 | private Handler mHandler; |
| 64 | private int mMessage; |
Ben Dodson | 6d8b80d | 2011-07-08 14:36:42 -0700 | [diff] [blame] | 65 | private final int mChannel; |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 66 | |
| 67 | /** |
| 68 | * Construct a socket for incoming connections. |
Nick Pelly | 6a669fa | 2009-06-02 15:57:18 -0700 | [diff] [blame] | 69 | * @param type type of socket |
| 70 | * @param auth require the remote device to be authenticated |
| 71 | * @param encrypt require the connection to be encrypted |
| 72 | * @param port remote port |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 73 | * @throws IOException On error, for example Bluetooth not available, or |
Jake Hamby | f51eada | 2010-09-21 13:39:53 -0700 | [diff] [blame] | 74 | * insufficient privileges |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 75 | */ |
Nick Pelly | bd022f4 | 2009-08-14 18:33:38 -0700 | [diff] [blame] | 76 | /*package*/ BluetoothServerSocket(int type, boolean auth, boolean encrypt, int port) |
Nick Pelly | 6a669fa | 2009-06-02 15:57:18 -0700 | [diff] [blame] | 77 | throws IOException { |
Ben Dodson | 6d8b80d | 2011-07-08 14:36:42 -0700 | [diff] [blame] | 78 | mChannel = port; |
Nick Pelly | 16fb88a | 2009-10-07 07:44:03 +0200 | [diff] [blame] | 79 | mSocket = new BluetoothSocket(type, -1, auth, encrypt, null, port, null); |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 80 | } |
| 81 | |
| 82 | /** |
| 83 | * Block until a connection is established. |
Nick Pelly | 45e2704 | 2009-08-19 11:00:00 -0700 | [diff] [blame] | 84 | * <p>Returns a connected {@link BluetoothSocket} on successful connection. |
| 85 | * <p>Once this call returns, it can be called again to accept subsequent |
| 86 | * incoming connections. |
| 87 | * <p>{@link #close} can be used to abort this call from another thread. |
| 88 | * @return a connected {@link BluetoothSocket} |
| 89 | * @throws IOException on error, for example this call was aborted, or |
| 90 | * timeout |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 91 | */ |
| 92 | public BluetoothSocket accept() throws IOException { |
| 93 | return accept(-1); |
| 94 | } |
| 95 | |
| 96 | /** |
| 97 | * Block until a connection is established, with timeout. |
Nick Pelly | 45e2704 | 2009-08-19 11:00:00 -0700 | [diff] [blame] | 98 | * <p>Returns a connected {@link BluetoothSocket} on successful connection. |
| 99 | * <p>Once this call returns, it can be called again to accept subsequent |
| 100 | * incoming connections. |
| 101 | * <p>{@link #close} can be used to abort this call from another thread. |
| 102 | * @return a connected {@link BluetoothSocket} |
| 103 | * @throws IOException on error, for example this call was aborted, or |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 104 | * timeout |
| 105 | */ |
| 106 | public BluetoothSocket accept(int timeout) throws IOException { |
Nick Pelly | 71c3c78 | 2009-09-02 11:51:35 -0700 | [diff] [blame] | 107 | return mSocket.accept(timeout); |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 108 | } |
| 109 | |
| 110 | /** |
Nick Pelly | 45e2704 | 2009-08-19 11:00:00 -0700 | [diff] [blame] | 111 | * Immediately close this socket, and release all associated resources. |
| 112 | * <p>Causes blocked calls on this socket in other threads to immediately |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 113 | * throw an IOException. |
Scott Main | 6d95fc0 | 2009-11-19 17:00:19 -0800 | [diff] [blame] | 114 | * <p>Closing the {@link BluetoothServerSocket} will <em>not</em> |
| 115 | * close any {@link BluetoothSocket} received from {@link #accept()}. |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 116 | */ |
| 117 | public void close() throws IOException { |
Nick Pelly | 24bb9b8 | 2009-10-02 20:34:18 -0700 | [diff] [blame] | 118 | synchronized (this) { |
| 119 | if (mHandler != null) { |
| 120 | mHandler.obtainMessage(mMessage).sendToTarget(); |
| 121 | } |
| 122 | } |
Nick Pelly | 71c3c78 | 2009-09-02 11:51:35 -0700 | [diff] [blame] | 123 | mSocket.close(); |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 124 | } |
Nick Pelly | 24bb9b8 | 2009-10-02 20:34:18 -0700 | [diff] [blame] | 125 | |
| 126 | /*package*/ synchronized void setCloseHandler(Handler handler, int message) { |
| 127 | mHandler = handler; |
| 128 | mMessage = message; |
| 129 | } |
Ben Dodson | 6d8b80d | 2011-07-08 14:36:42 -0700 | [diff] [blame] | 130 | |
| 131 | /** |
| 132 | * Returns the channel on which this socket is bound. |
| 133 | * @hide |
| 134 | */ |
| 135 | public int getChannel() { |
| 136 | return mChannel; |
| 137 | } |
Nick Pelly | 0b6955a | 2009-05-26 19:13:43 -0700 | [diff] [blame] | 138 | } |