1 /**
2 * Java docs licensed under the Apache License, Version 2.0
3 * http://www.apache.org/licenses/LICENSE-2.0
4 * (c) Copyright 2001, 2002 Motorola, Inc. ALL RIGHTS RESERVED.
5 *
6 *
7 * @version $Id: L2CAPConnection.java 1379 2007-10-13 02:00:43Z vlads $
8 */
9
10 package javax.bluetooth;
11
12 import java.io.IOException;
13
14 import javax.microedition.io.Connection;
15
16 /**
17 * The <code>L2CAPConnection</code> interface represents a
18 * connection-oriented L2CAP channel. This interface is to be
19 * used as part of the CLDC Generic Connection Framework.
20 * <P>
21 * To create a client connection, the protocol is <code>btl2cap</code>.
22 * The target is the combination of the address
23 * of the Bluetooth device to connect to and the Protocol
24 * Service Multiplexor (PSM) of the service.
25 * The PSM value is used by the
26 * L2CAP to determine which higher level protocol or application is the
27 * recipient of the messages the layer receives.
28 * <P>
29 * The parameters defined specific to L2CAP are ReceiveMTU (Maximum
30 * Transmission Unit (MTU)) and TransmitMTU. The ReceiveMTU and TransmitMTU
31 * parameters are optional. ReceiveMTU
32 * specifies the maximum payload size this connection can accept, and
33 * TransmitMTU specifies the maximum payload size this connection can
34 * send. An example of a valid L2CAP client connection string is:<BR>
35 * <code>btl2cap://0050CD00321B:1003;ReceiveMTU=512;TransmitMTU=512</code>
36 *
37 * @version 1.0 February 11, 2002
38 */
39 public interface L2CAPConnection extends Connection {
40
41 /**
42 * Default MTU value for connection-oriented channels
43 * is 672 bytes.
44 * <P>
45 * The value of <code>DEFAULT_MTU</code> is 0x02A0 (672).
46 */
47 public static final int DEFAULT_MTU = 672;
48
49 /**
50 * Minimum MTU value for connection-oriented channels
51 * is 48 bytes.
52 * <P>
53 * The value of <code>MINIMUM_MTU</code> is 0x30 (48).
54 */
55 public static final int MINIMUM_MTU = 48;
56
57 /**
58 * Returns the MTU that the remote device supports. This value
59 * is obtained after the connection has been configured. If the
60 * application had specified TransmitMTU in the <code>Connector.open()</code>
61 * string then this value should be equal to that. If the application did
62 * not specify any TransmitMTU, then this value should be less than or
63 * equal to the ReceiveMTU the remote device advertised during
64 * channel configuration.
65 *
66 * @return the maximum number of bytes that can be sent in a single call to
67 * <code>send()</code> without losing any data
68 *
69 * @exception IOException if the connection is closed
70 */
71 public int getTransmitMTU() throws IOException;
72
73 /**
74 * Returns the ReceiveMTU that the connection supports. If the
75 * connection string did not specify a ReceiveMTU, the value returned will be
76 * less than or equal to the <code>DEFAULT_MTU</code>. Also, if the connection
77 * string did specify an MTU, this value will be less than or equal to the
78 * value specified in the connection string.
79 *
80 * @return the maximum number of bytes that can be read in a single call
81 * to <code>receive()</code>
82 *
83 * @exception IOException if the connection is closed
84 *
85 */
86 public int getReceiveMTU() throws IOException;
87
88 /**
89 * Requests that data be sent to the remote device. The TransmitMTU
90 * determines the amount of data that can be successfully sent in
91 * a single send operation. If the size of <code>data</code> is
92 * greater than the TransmitMTU, then only the first TransmitMTU bytes
93 * of the packet are sent, and the rest will be discarded. If
94 * <code>data</code> is of length 0, an empty L2CAP packet will be sent.
95 *
96 * @param data data to be sent
97 *
98 * @exception IOException if <code>data</code> cannot be sent successfully
99 * or if the connection is closed
100 *
101 * @exception NullPointerException if the <code>data</code> is
102 * <code>null</code>
103 */
104 public void send(byte[] data) throws IOException;
105
106 /**
107 * Reads a packet of data. The amount of data received in
108 * this operation is related to the value of ReceiveMTU. If
109 * the size of <code>inBuf</code> is greater than or equal to ReceiveMTU, then
110 * no data will be lost. Unlike <code>read()</code> on an
111 * <code>java.io.InputStream</code>, if the size of <code>inBuf</code> is
112 * smaller than ReceiveMTU, then the portion of the L2CAP payload that will
113 * fit into <code>inBuf</code> will be placed in <code>inBuf</code>, the
114 * rest will be discarded. If the application is aware of the number of
115 * bytes (less than ReceiveMTU) it will receive in any transaction, then
116 * the size of <code>inBuf</code> can be less than ReceiveMTU and no data
117 * will be lost. If <code>inBuf</code> is of length 0, all data sent in
118 * one packet is lost unless the length of the packet is 0.
119 *
120 * @param inBuf byte array to store the received data
121 *
122 * @return the actual number of bytes read; 0 if a zero length packet is
123 * received; 0 if <code>inBuf</code> length is zero
124 *
125 * @exception IOException if an I/O error occurs or the connection has been
126 * closed
127 *
128 * @exception InterruptedIOException if the request timed out
129 *
130 * @exception NullPointerException if <code>inBuf</code> is <code>null</code>
131 */
132 public int receive(byte[] inBuf) throws IOException;
133
134 /**
135 * Determines if there is a packet that can be read via a call to
136 * <code>receive()</code>. If <code>true</code>, a call to
137 * <code>receive()</code> will not block the application.
138 *
139 * @see #receive
140 *
141 * @return <code>true</code> if there is data to read;
142 * <code>false</code> if there is no data to read
143 *
144 * @exception IOException if the connection is closed
145 *
146 */
147 public boolean ready() throws IOException;
148
149 }