/**
* 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.obex;
import java.io.IOException;
import javax.microedition.io.Connection;
/**
* 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.
*
*/
public interface SessionNotifier extends Connection {
/**
* 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.
* <p>
* Note : once an application invokes {@code close()} on any {@code
* SessionNotifier}, {@code L2CAPConnectionNotifier}, or {@code
* StreamConnectionNotifer} instance, all pending {@code acceptAndOpen()}
* methods that have been invoked previously on that instance MUST throw
* {@code InterruptedIOException}. This mechanism provides an application
* with the means to cancel any outstanding {@code acceptAndOpen()} method
* calls.
*
* @param handler
* the request handler that will respond to OBEX requests
*
* @return the connection to the client
*
* @exception IOException
* if an error occurs in the transport layer
*
* @exception NullPointerException
* if <code>handler</code> is <code>null</code>
*
* @exception ServiceRegistrationException
* if the structure of the associated service record is
* invalid or if the service record could not be added
* successfully to the local SDDB. The structure of service
* record is invalid if the service record is missing any
* mandatory service attributes, or has changed any of the
* values described above which are fixed and cannot be
* changed. Failures to add the record to the SDDB could be
* due to insufficient disk space, database locks, etc.
*
* @exception BluetoothStateException
* if the server device could not be placed in connectable
* mode because the device user has configured the device to
* be non-connectable
*/
public Connection 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.
* <p>
* Note : once an application invokes {@code close()} on any {@code
* SessionNotifier}, {@code L2CAPConnectionNotifier}, or {@code
* StreamConnectionNotifer} instance, all pending {@code acceptAndOpen()}
* methods that have been invoked previously on that instance MUST throw
* {@code InterruptedIOException}. This mechanism provides an application
* with the means to cancel any outstanding {@code acceptAndOpen()} method
* calls.
*
* @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
*
* @exception IOException
* if an error occurs in the transport layer
*
* @exception NullPointerException
* if <code>handler</code> is <code>null</code>
*
* @exception ServiceRegistrationException
* if the structure of the associated service record is
* invalid or if the service record could not be added
* successfully to the local SDDB. The structure of service
* record is invalid if the service record is missing any
* mandatory service attributes, or has changed any of the
* values described above which are fixed and cannot be
* changed. Failures to add the record to the SDDB could be
* due to insufficient disk space, database locks, etc.
*
* @exception BluetoothStateException
* if the server device could not be placed in connectable
* mode because the device user has configured the device to
* be non-connectable
*/
public Connection acceptAndOpen(ServerRequestHandler handler, Authenticator auth) throws IOException;
}