1 /* 2 * Copyright (c) 2008-2009, Motorola, Inc. 3 * 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * - Redistributions of source code must retain the above copyright notice, 10 * this list of conditions and the following disclaimer. 11 * 12 * - Redistributions in binary form must reproduce the above copyright notice, 13 * this list of conditions and the following disclaimer in the documentation 14 * and/or other materials provided with the distribution. 15 * 16 * - Neither the name of the Motorola, Inc. nor the names of its contributors 17 * may be used to endorse or promote products derived from this software 18 * without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 24 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30 * POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 package javax.obex; 34 35 import java.io.IOException; 36 37 /** 38 * The <code>SessionNotifier</code> interface defines a connection notifier for 39 * server-side OBEX connections. When a <code>SessionNotifier</code> is created 40 * and calls <code>acceptAndOpen()</code>, it will begin listening for clients 41 * to create a connection at the transport layer. When the transport layer 42 * connection is received, the <code>acceptAndOpen()</code> method will return a 43 * <code>javax.microedition.io.Connection</code> that is the connection to the 44 * client. The <code>acceptAndOpen()</code> method also takes a 45 * <code>ServerRequestHandler</code> argument that will process the requests 46 * from the client that connects to the server. 47 * @hide 48 */ 49 public interface SessionNotifier { 50 51 /** 52 * Waits for a transport layer connection to be established and specifies 53 * the handler to handle the requests from the client. No authenticator is 54 * associated with this connection, therefore, it is implementation 55 * dependent as to how an authentication challenge and authentication 56 * response header will be received and processed. 57 * <P> 58 * <H4>Additional Note for OBEX over Bluetooth</H4> If this method is called 59 * on a <code>SessionNotifier</code> object that does not have a 60 * <code>ServiceRecord</code> in the SDDB, the <code>ServiceRecord</code> 61 * for this object will be added to the SDDB. This method requests the BCC 62 * to put the local device in connectable mode so that it will respond to 63 * connection attempts by clients. 64 * <P> 65 * The following checks are done to verify that the service record provided 66 * is valid. If any of these checks fail, then a 67 * <code>ServiceRegistrationException</code> is thrown. 68 * <UL> 69 * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service 70 * attributes for a <code>btgoep</code> service record, must be present in 71 * the <code>ServiceRecord</code> associated with this notifier. 72 * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList 73 * <LI>The <code>ServiceRecord</code> associated with this notifier must not 74 * have changed the RFCOMM server channel number 75 * </UL> 76 * <P> 77 * This method will not ensure that <code>ServiceRecord</code> associated 78 * with this notifier is a completely valid service record. It is the 79 * responsibility of the application to ensure that the service record 80 * follows all of the applicable syntactic and semantic rules for service 81 * record correctness. 82 * @param handler the request handler that will respond to OBEX requests 83 * @return the connection to the client 84 * @throws IOException if an error occurs in the transport layer 85 * @throws NullPointerException if <code>handler</code> is <code>null</code> 86 */ 87 ObexSession acceptAndOpen(ServerRequestHandler handler) throws IOException; 88 89 /** 90 * Waits for a transport layer connection to be established and specifies 91 * the handler to handle the requests from the client and the 92 * <code>Authenticator</code> to use to respond to authentication challenge 93 * and authentication response headers. 94 * <P> 95 * <H4>Additional Note for OBEX over Bluetooth</H4> If this method is called 96 * on a <code>SessionNotifier</code> object that does not have a 97 * <code>ServiceRecord</code> in the SDDB, the <code>ServiceRecord</code> 98 * for this object will be added to the SDDB. This method requests the BCC 99 * to put the local device in connectable mode so that it will respond to 100 * connection attempts by clients. 101 * <P> 102 * The following checks are done to verify that the service record provided 103 * is valid. If any of these checks fail, then a 104 * <code>ServiceRegistrationException</code> is thrown. 105 * <UL> 106 * <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service 107 * attributes for a <code>btgoep</code> service record, must be present in 108 * the <code>ServiceRecord</code> associated with this notifier. 109 * <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList 110 * <LI>The <code>ServiceRecord</code> associated with this notifier must not 111 * have changed the RFCOMM server channel number 112 * </UL> 113 * <P> 114 * This method will not ensure that <code>ServiceRecord</code> associated 115 * with this notifier is a completely valid service record. It is the 116 * responsibility of the application to ensure that the service record 117 * follows all of the applicable syntactic and semantic rules for service 118 * record correctness. 119 * @param handler the request handler that will respond to OBEX requests 120 * @param auth the <code>Authenticator</code> to use with this connection; 121 * if <code>null</code> then no <code>Authenticator</code> will be 122 * used 123 * @return the connection to the client 124 * @throws IOException if an error occurs in the transport layer 125 * @throws NullPointerException if <code>handler</code> is <code>null</code> 126 */ 127 ObexSession acceptAndOpen(ServerRequestHandler handler, Authenticator auth) throws IOException; 128 } 129
