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
33package javax.obex;
34
35import 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 */
49public 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