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.IOException; 369439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 379439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly/** 389439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * The <code>SessionNotifier</code> interface defines a connection notifier for 3905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * server-side OBEX connections. When a <code>SessionNotifier</code> is created 4005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * and calls <code>acceptAndOpen()</code>, it will begin listening for clients 4105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * to create a connection at the transport layer. When the transport layer 4205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * connection is received, the <code>acceptAndOpen()</code> method will return a 4305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>javax.microedition.io.Connection</code> that is the connection to the 4405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * client. The <code>acceptAndOpen()</code> method also takes a 459439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>ServerRequestHandler</code> argument that will process the requests 469439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * from the client that connects to the server. 472e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @hide 489439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 499439a7fe517b858bc5e5c654b459315e4722feb2Nick Pellypublic interface SessionNotifier { 509439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 519439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly /** 529439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Waits for a transport layer connection to be established and specifies 5305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * the handler to handle the requests from the client. No authenticator is 5405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * associated with this connection, therefore, it is implementation 559439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * dependent as to how an authentication challenge and authentication 569439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * response header will be received and processed. 579439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 5805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <H4>Additional Note for OBEX over Bluetooth</H4> If this method is called 5905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * on a <code>SessionNotifier</code> object that does not have a 6005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>ServiceRecord</code> in the SDDB, the <code>ServiceRecord</code> 6105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * for this object will be added to the SDDB. This method requests the BCC 6205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * to put the local device in connectable mode so that it will respond to 639439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * connection attempts by clients. 649439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 6505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * The following checks are done to verify that the service record provided 6605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * is valid. If any of these checks fail, then a 679439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>ServiceRegistrationException</code> is thrown. 689439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <UL> 6905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service 7005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * attributes for a <code>btgoep</code> service record, must be present in 7105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * the <code>ServiceRecord</code> associated with this notifier. 729439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList 7305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <LI>The <code>ServiceRecord</code> associated with this notifier must not 7405ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * have changed the RFCOMM server channel number 759439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * </UL> 769439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 779439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * This method will not ensure that <code>ServiceRecord</code> associated 7805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * with this notifier is a completely valid service record. It is the 7905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * responsibility of the application to ensure that the service record 8005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * follows all of the applicable syntactic and semantic rules for service 8105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * record correctness. 829439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @param handler the request handler that will respond to OBEX requests 839439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @return the connection to the client 842e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @throws IOException if an error occurs in the transport layer 8505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * @throws NullPointerException if <code>handler</code> is <code>null</code> 869439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 873998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun ObexSession acceptAndOpen(ServerRequestHandler handler) throws IOException; 889439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly 899439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly /** 909439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * Waits for a transport layer connection to be established and specifies 919439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * the handler to handle the requests from the client and the 929439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>Authenticator</code> to use to respond to authentication challenge 939439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * and authentication response headers. 949439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 9505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <H4>Additional Note for OBEX over Bluetooth</H4> If this method is called 9605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * on a <code>SessionNotifier</code> object that does not have a 9705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <code>ServiceRecord</code> in the SDDB, the <code>ServiceRecord</code> 9805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * for this object will be added to the SDDB. This method requests the BCC 9905ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * to put the local device in connectable mode so that it will respond to 1009439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * connection attempts by clients. 1019439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 10205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * The following checks are done to verify that the service record provided 10305ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * is valid. If any of these checks fail, then a 1049439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <code>ServiceRegistrationException</code> is thrown. 1059439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <UL> 10605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service 10705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * attributes for a <code>btgoep</code> service record, must be present in 10805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * the <code>ServiceRecord</code> associated with this notifier. 1099439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList 11005ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * <LI>The <code>ServiceRecord</code> associated with this notifier must not 11105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * have changed the RFCOMM server channel number 1129439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * </UL> 1139439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * <P> 1149439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * This method will not ensure that <code>ServiceRecord</code> associated 11505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * with this notifier is a completely valid service record. It is the 11605ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * responsibility of the application to ensure that the service record 11705ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * follows all of the applicable syntactic and semantic rules for service 11805ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * record correctness. 1199439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @param handler the request handler that will respond to OBEX requests 1209439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @param auth the <code>Authenticator</code> to use with this connection; 12105ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * if <code>null</code> then no <code>Authenticator</code> will be 12205ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * used 1239439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly * @return the connection to the client 1242e0da96e757a977154063f980d3f4e1abd41cf09Nick Pelly * @throws IOException if an error occurs in the transport layer 12505ff98bbefda39b9ff26f8bca132cfd0248745c6Tao Liejun * @throws NullPointerException if <code>handler</code> is <code>null</code> 1269439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly */ 1273998bf009acaf8cde4d7f837f8b8e41ae0a65141Tao Liejun ObexSession acceptAndOpen(ServerRequestHandler handler, Authenticator auth) throws IOException; 1289439a7fe517b858bc5e5c654b459315e4722feb2Nick Pelly} 129