19439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly/* 29439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Copyright (c) 2008-2009, Motorola, Inc. 39439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 49439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * All rights reserved. 59439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 69439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Redistribution and use in source and binary forms, with or without 79439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * modification, are permitted provided that the following conditions are met: 89439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 99439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * - Redistributions of source code must retain the above copyright notice, 109439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * this list of conditions and the following disclaimer. 119439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 129439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * - Redistributions in binary form must reproduce the above copyright notice, 139439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * this list of conditions and the following disclaimer in the documentation 149439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * and/or other materials provided with the distribution. 159439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 169439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * - Neither the name of the Motorola, Inc. nor the names of its contributors 179439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * may be used to endorse or promote products derived from this software 189439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * without specific prior written permission. 199439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * 209439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 219439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 229439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 239439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 249439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 259439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 269439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 279439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 289439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 299439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 309439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * POSSIBILITY OF SUCH DAMAGE. 319439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 329439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 339439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellypackage javax.obex; 349439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 359439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellyimport java.io.DataInputStream; 369439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellyimport java.io.DataOutputStream; 379439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellyimport java.io.IOException; 389439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellyimport java.io.InputStream; 399439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellyimport java.io.OutputStream; 409439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 419439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly/** 429439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * The <code>Operation</code> interface provides ways to manipulate a single 4305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * OBEX PUT or GET operation. The implementation of this interface sends OBEX 4405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * packets as they are built. If during the operation the peer in the operation 4505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * ends the operation, an <code>IOException</code> is thrown on the next read 4605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * from the input stream, write to the output stream, or call to 479439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>sendHeaders()</code>. 489439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 4905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <STRONG>Definition of methods inherited from <code>ContentConnection</code> 5005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * </STRONG> 519439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 5205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>getEncoding()</code> will always return <code>null</code>. <BR> 5305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>getLength()</code> will return the length specified by the OBEX Length 5405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * header or -1 if the OBEX Length header was not included. <BR> 5505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>getType()</code> will return the value specified in the OBEX Type 569439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * header or <code>null</code> if the OBEX Type header was not included.<BR> 579439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 589439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <STRONG>How Headers are Handled</STRONG> 599439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 609439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * As headers are received, they may be retrieved through the 6105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>getReceivedHeaders()</code> method. If new headers are set during the 629439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * operation, the new headers will be sent during the next packet exchange. 639439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 649439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <STRONG>PUT example</STRONG> 659439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 669439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <PRE> 6705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * void putObjectViaOBEX(ClientSession conn, HeaderSet head, byte[] obj) throws IOException { 689439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // Include the length header 699439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * head.setHeader(head.LENGTH, new Long(obj.length)); 709439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // Initiate the PUT request 719439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Operation op = conn.put(head); 729439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // Open the output stream to put the object to it 739439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * DataOutputStream out = op.openDataOutputStream(); 749439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // Send the object to the server 759439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * out.write(obj); 769439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // End the transaction 779439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * out.close(); 789439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * op.close(); 799439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * } 809439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * </PRE> 819439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 829439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <STRONG>GET example</STRONG> 839439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 849439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <PRE> 859439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * byte[] getObjectViaOBEX(ClientSession conn, HeaderSet head) throws IOException { 869439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // Send the initial GET request to the server 879439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Operation op = conn.get(head); 889439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // Retrieve the length of the object being sent back 899439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * int length = op.getLength(); 9005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * // Create space for the object 9105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * byte[] obj = new byte[length]; 929439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // Get the object from the input stream 939439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * DataInputStream in = trans.openDataInputStream(); 949439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * in.read(obj); 959439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * // End the transaction 969439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * in.close(); 979439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * op.close(); 989439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * return obj; 999439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * } 1009439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * </PRE> 10105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * 10205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <H3>Client PUT Operation Flow</H3> For PUT operations, a call to 10305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>close()</code> the <code>OutputStream</code> returned from 10405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>openOutputStream()</code> or <code>openDataOutputStream()</code> will 10505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * signal that the request is done. (In OBEX terms, the End-Of-Body header 10605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * should be sent and the final bit in the request will be set.) At this point, 10705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * the reply from the server may begin to be processed. A call to 1089439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>getResponseCode()</code> will do an implicit close on the 1099439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>OutputStream</code> and therefore signal that the request is done. 11005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <H3>Client GET Operation Flow</H3> For GET operation, a call to 11105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>openInputStream()</code> or <code>openDataInputStream()</code> will 11205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * signal that the request is done. (In OBEX terms, the final bit in the request 11305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * will be set.) A call to <code>getResponseCode()</code> will cause an implicit 11405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * close on the <code>InputStream</code>. No further data may be read at this 11505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * point. 1162e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @hide 1179439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 1189439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellypublic interface Operation { 1199439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1209439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly /** 12105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * Sends an ABORT message to the server. By calling this method, the 1229439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * corresponding input and output streams will be closed along with this 12305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * object. No headers are sent in the abort request. This will end the 1249439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * operation since <code>close()</code> will be called by this method. 12505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * @throws IOException if the transaction has already ended or if an OBEX 12605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * server calls this method 1279439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 1283998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun void abort() throws IOException; 1299439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1309439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly /** 1319439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Returns the headers that have been received during the operation. 13205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * Modifying the object returned has no effect on the headers that are sent 13305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * or retrieved. 1349439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @return the headers received during this <code>Operation</code> 1352e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @throws IOException if this <code>Operation</code> has been closed 1369439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 1373998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun HeaderSet getReceivedHeader() throws IOException; 1389439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1399439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly /** 1409439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Specifies the headers that should be sent in the next OBEX message that 1419439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * is sent. 1429439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @param headers the headers to send in the next message 14305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * @throws IOException if this <code>Operation</code> has been closed or the 14405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * transaction has ended and no further messages will be exchanged 1452e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @throws IllegalArgumentException if <code>headers</code> was not created 14605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * by a call to <code>ServerRequestHandler.createHeaderSet()</code> 14705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * or <code>ClientSession.createHeaderSet()</code> 1482e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @throws NullPointerException if <code>headers</code> if <code>null</code> 1499439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 1503998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun void sendHeaders(HeaderSet headers) throws IOException; 1519439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1529439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly /** 15305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * Returns the response code received from the server. Response codes are 15405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * defined in the <code>ResponseCodes</code> class. 1559439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @see ResponseCodes 1569439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @return the response code retrieved from the server 1572e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @throws IOException if an error occurred in the transport layer during 15805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * the transaction; if this object was created by an OBEX server 1599439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 1603998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun int getResponseCode() throws IOException; 1619439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1623998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun String getEncoding(); 1639439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1643998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun long getLength(); 1659439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 16665208317ba9d16486b47ebcaa868c596d424c87fLixin Yue int getHeaderLength(); 16765208317ba9d16486b47ebcaa868c596d424c87fLixin Yue 1683998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun String getType(); 1699439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1703998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun InputStream openInputStream() throws IOException; 1719439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1723998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun DataInputStream openDataInputStream() throws IOException; 1739439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1743998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun OutputStream openOutputStream() throws IOException; 1759439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1763998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun DataOutputStream openDataOutputStream() throws IOException; 1779439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1783998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun void close() throws IOException; 1799439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 1803998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun int getMaxPacketSize(); 181fe3807a5b23f54f6539436d71aa0cd931a2b76f0Matthew Xie 182fe3807a5b23f54f6539436d71aa0cd931a2b76f0Matthew Xie public void noBodyHeader(); 1839439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly} 184