javax.obex.SessionNotifier Maven / Gradle / Ivy
Show all versions of bluecove Show documentation
/**
* 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: SessionNotifier.java 2532 2008-12-09 20:23:14Z skarzhevskyy $
*/
package javax.obex;
import java.io.IOException;
import javax.microedition.io.Connection;
/**
* The SessionNotifier interface defines a connection notifier for
* server-side OBEX connections. When a SessionNotifier is created
* and calls acceptAndOpen(), it will begin listening for clients
* to create a connection at the transport layer. When the transport layer
* connection is received, the acceptAndOpen() method will return a
* javax.microedition.io.Connection that is the connection to the
* client. The acceptAndOpen() method also takes a
* ServerRequestHandler 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.
*
*
Additional Note for OBEX over Bluetooth
* If this method is called on a SessionNotifier object that
* does not have a ServiceRecord in the SDDB, the
* ServiceRecord 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.
*
* The following checks are done to verify that the service record provided
* is valid. If any of these checks fail, then a
* ServiceRegistrationException is thrown.
*
* - ServiceClassIDList and ProtocolDescriptorList, the mandatory service
* attributes for a
btgoep service record, must be present in
* the ServiceRecord associated with this notifier.
* - L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList
*
- The
ServiceRecord associated with this notifier must not
* have changed the RFCOMM server channel number
*
*
* This method will not ensure that ServiceRecord 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.
*
* 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 handler is null
*
* @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
* Authenticator to use to respond to authentication challenge
* and authentication response headers.
*
*
Additional Note for OBEX over Bluetooth
* If this method is called on a SessionNotifier object that
* does not have a ServiceRecord in the SDDB, the
* ServiceRecord 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.
*
* The following checks are done to verify that the service record provided
* is valid. If any of these checks fail, then a
* ServiceRegistrationException is thrown.
*
* - ServiceClassIDList and ProtocolDescriptorList, the mandatory service
* attributes for a
btgoep service record, must be present in
* the ServiceRecord associated with this notifier.
* - L2CAP, RFCOMM and OBEX must all be in the ProtocolDescriptorList
*
- The
ServiceRecord associated with this notifier must not
* have changed the RFCOMM server channel number
*
*
* This method will not ensure that ServiceRecord 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.
*
* 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 Authenticator to use with this connection; if
* null then no Authenticator will be
* used
*
* @return the connection to the client
*
* @exception IOException
* if an error occurs in the transport layer
*
* @exception NullPointerException
* if handler is null
*
* @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;
}