/*
* Copyright (c) 2008-2009, Motorola, Inc.
*
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* - Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* - Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* - Neither the name of the Motorola, Inc. nor the names of its contributors
* may be used to endorse or promote products derived from this software
* without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
*/
package javax.obex;
import java.io.IOException;
/**
* The <code>SessionNotifier</code> interface defines a connection notifier for
* server-side OBEX connections. When a <code>SessionNotifier</code> is created
* and calls <code>acceptAndOpen()</code>, it will begin listening for clients
* to create a connection at the transport layer. When the transport layer
* connection is received, the <code>acceptAndOpen()</code> method will return a
* <code>javax.microedition.io.Connection</code> that is the connection to the
* client. The <code>acceptAndOpen()</code> method also takes a
* <code>ServerRequestHandler</code> argument that will process the requests
* from the client that connects to the server.
* @hide
*/
public interface SessionNotifier {
/**
* Waits for a transport layer connection to be established and specifies
* the handler to handle the requests from the client. No authenticator is
* associated with this connection, therefore, it is implementation
* dependent as to how an authentication challenge and authentication
* response header will be received and processed.
* <P>
* <H4>Additional Note for OBEX over Bluetooth</H4> If this method is called
* on a <code>SessionNotifier</code> object that does not have a
* <code>ServiceRecord</code> in the SDDB, the <code>ServiceRecord</code>
* for this object will be added to the SDDB. This method requests the BCC
* to put the local device in connectable mode so that it will respond to
* connection attempts by clients.
* <P>
* The following checks are done to verify that the service record provided
* is valid. If any of these checks fail, then a
* <code>ServiceRegistrationException</code> is thrown.
* <UL>
* <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
* attributes for a <code>btgoep</code> service record, must be present in
* the <code>ServiceRecord</code> associated with this notifier.
* <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList
* <LI>The <code>ServiceRecord</code> associated with this notifier must not
* have changed the RFCOMM server channel number
* </UL>
* <P>
* This method will not ensure that <code>ServiceRecord</code> associated
* with this notifier is a completely valid service record. It is the
* responsibility of the application to ensure that the service record
* follows all of the applicable syntactic and semantic rules for service
* record correctness.
* @param handler the request handler that will respond to OBEX requests
* @return the connection to the client
* @throws IOException if an error occurs in the transport layer
* @throws NullPointerException if <code>handler</code> is <code>null</code>
*/
ObexSession acceptAndOpen(ServerRequestHandler handler) throws IOException;
/**
* Waits for a transport layer connection to be established and specifies
* the handler to handle the requests from the client and the
* <code>Authenticator</code> to use to respond to authentication challenge
* and authentication response headers.
* <P>
* <H4>Additional Note for OBEX over Bluetooth</H4> If this method is called
* on a <code>SessionNotifier</code> object that does not have a
* <code>ServiceRecord</code> in the SDDB, the <code>ServiceRecord</code>
* for this object will be added to the SDDB. This method requests the BCC
* to put the local device in connectable mode so that it will respond to
* connection attempts by clients.
* <P>
* The following checks are done to verify that the service record provided
* is valid. If any of these checks fail, then a
* <code>ServiceRegistrationException</code> is thrown.
* <UL>
* <LI>ServiceClassIDList and ProtocolDescriptorList, the mandatory service
* attributes for a <code>btgoep</code> service record, must be present in
* the <code>ServiceRecord</code> associated with this notifier.
* <LI>L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList
* <LI>The <code>ServiceRecord</code> associated with this notifier must not
* have changed the RFCOMM server channel number
* </UL>
* <P>
* This method will not ensure that <code>ServiceRecord</code> associated
* with this notifier is a completely valid service record. It is the
* responsibility of the application to ensure that the service record
* follows all of the applicable syntactic and semantic rules for service
* record correctness.
* @param handler the request handler that will respond to OBEX requests
* @param auth the <code>Authenticator</code> to use with this connection;
* if <code>null</code> then no <code>Authenticator</code> will be
* used
* @return the connection to the client
* @throws IOException if an error occurs in the transport layer
* @throws NullPointerException if <code>handler</code> is <code>null</code>
*/
ObexSession acceptAndOpen(ServerRequestHandler handler, Authenticator auth) throws IOException;
}