1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

/**
 *  BlueCove - Java library for Bluetooth
 *
 *  Java docs licensed under the Apache License, Version 2.0
 *  http://www.apache.org/licenses/LICENSE-2.0 
 *   (c) Copyright 2001, 2002 Motorola, Inc.  ALL RIGHTS RESERVED.
 *
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you 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.
 * 
 *  @version $Id$
 */
package javax.bluetooth;

import java.io.IOException;

import javax.microedition.io.Connection;

/**
 * The <code>L2CAPConnection</code> interface represents a
 * connection-oriented L2CAP channel.  This  interface is to be
 * used as part of the CLDC Generic Connection Framework.
 * <P>
 * To create a client connection, the protocol is <code>btl2cap</code>.
 * The target is the combination of the address
 * of the Bluetooth device to connect to and the Protocol
 * Service Multiplexor (PSM) of the service.
 * The PSM value is used by the
 * L2CAP to determine which higher level protocol or application is the
 * recipient of the messages the layer receives.
 * <P>
 * The parameters defined specific to L2CAP are ReceiveMTU (Maximum
 * Transmission Unit (MTU)) and TransmitMTU.  The ReceiveMTU and TransmitMTU
 * parameters are optional. ReceiveMTU
 * specifies the maximum payload size this connection can accept, and
 * TransmitMTU specifies the maximum payload size this connection can
 * send. An example of a valid L2CAP client connection string is:<BR>
 * <code>btl2cap://0050CD00321B:1003;ReceiveMTU=512;TransmitMTU=512</code>
 *
 */
public interface L2CAPConnection extends Connection {

	/**
	 * Default MTU value for connection-oriented channels
	 * is 672 bytes.
	 * <P>
	 * The value of <code>DEFAULT_MTU</code> is 0x02A0 (672).
	 */
	public static final int DEFAULT_MTU = 672;

	/**
	 * Minimum MTU value for connection-oriented channels
	 * is 48 bytes.
	 * <P>
	 * The value of <code>MINIMUM_MTU</code> is 0x30 (48).
	 */
	public static final int MINIMUM_MTU = 48;

	/**
	 * Returns the MTU that the remote device supports. This value
	 * is obtained after the connection has been configured. If the
	 * application had specified TransmitMTU in the <code>Connector.open()</code>
	 * string then this value should be equal to that. If the application did
	 * not specify any TransmitMTU, then this value should be  less than or
	 * equal to the ReceiveMTU the remote device advertised during
	 * channel configuration.
	 *
	 * @return the maximum number of bytes that can be sent in a single call to
	 * <code>send()</code> without losing any data
	 *
	 * @exception IOException if the connection is closed
	 */
	public int getTransmitMTU() throws IOException;

	/**
	 * Returns the ReceiveMTU that the connection supports. If the
	 * connection string did not specify a ReceiveMTU, the value returned will be
	 * less than or equal to the <code>DEFAULT_MTU</code>. Also, if the connection
	 * string did specify an MTU, this value will be less than or equal to the
	 * value specified in the connection string.
	 *
	 * @return the maximum number of bytes that can be read in a single call
	 * to <code>receive()</code>
	 *
	 * @exception IOException if the connection is closed
	 *
	 */
	public int getReceiveMTU() throws IOException;

	/**
	 * Requests that data be sent to the remote device. The TransmitMTU
	 * determines the amount of data that can be successfully sent in
	 * a single send operation. If the size of <code>data</code> is
	 * greater than the TransmitMTU, then only the first TransmitMTU bytes
	 * of the packet are sent, and the rest will be discarded.  If
	 * <code>data</code> is of length 0, an empty L2CAP packet will be sent.
	 *
	 * @param data data to be sent
	 *
	 * @exception IOException if <code>data</code> cannot be sent successfully
	 * or if the connection is closed
	 *
	 * @exception NullPointerException if the <code>data</code> is
	 * <code>null</code>
	 */
	public void send(byte[] data) throws IOException;

	/**
	 * Reads a packet of data. The amount of data received in
	 * this operation is related to the value of ReceiveMTU.  If
	 * the size of <code>inBuf</code> is greater than or equal to ReceiveMTU, then
	 * no data will be lost. Unlike  <code>read()</code> on an
	 * <code>java.io.InputStream</code>, if the size of <code>inBuf</code> is
	 * smaller than ReceiveMTU, then the portion of the L2CAP payload that will
	 * fit into <code>inBuf</code> will be placed in <code>inBuf</code>, the
	 * rest will be discarded. If the application is aware of the number of
	 * bytes (less than ReceiveMTU) it will receive in any transaction, then
	 * the size of <code>inBuf</code> can be less than ReceiveMTU and no data
	 * will be lost.  If <code>inBuf</code> is of length 0, all data sent in
	 * one packet is lost unless the length of the packet is 0.
	 *
	 * @param inBuf byte array to store the received data
	 *
	 * @return the actual number of bytes read; 0 if a zero length packet is
	 * received; 0 if <code>inBuf</code> length is zero
	 *
	 * @exception IOException if an I/O error occurs or the connection has been
	 * closed
	 *
	 * @exception InterruptedIOException if the request timed out
	 *
	 * @exception NullPointerException if <code>inBuf</code> is <code>null</code>
	 */
	public int receive(byte[] inBuf) throws IOException;

	/**
	 * Determines if there is a packet that can be read via a call to
	 * <code>receive()</code>.  If <code>true</code>, a call to
	 * <code>receive()</code> will not block the application.
	 *
	 * @see #receive
	 *
	 * @return <code>true</code> if there is data to read;
	 * <code>false</code> if there is no data to read
	 *
	 * @exception IOException if the connection is closed
	 *
	 */
	public boolean ready() throws IOException;

}