Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 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 | /** |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 36 | * The <code>ServerRequestHandler</code> class defines an event listener that |
| 37 | * will respond to OBEX requests made to the server. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 38 | * <P> |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 39 | * The <code>onConnect()</code>, <code>onSetPath()</code>, |
| 40 | * <code>onDelete()</code>, <code>onGet()</code>, and <code>onPut()</code> |
| 41 | * methods may return any response code defined in the |
| 42 | * <code>ResponseCodes</code> class except for <code>OBEX_HTTP_CONTINUE</code>. |
| 43 | * If <code>OBEX_HTTP_CONTINUE</code> or a value not defined in the |
| 44 | * <code>ResponseCodes</code> class is returned, the server implementation will |
| 45 | * send an <code>OBEX_HTTP_INTERNAL_ERROR</code> response to the client. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 46 | * <P> |
| 47 | * <STRONG>Connection ID and Target Headers</STRONG> |
| 48 | * <P> |
| 49 | * According to the IrOBEX specification, a packet may not contain a Connection |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 50 | * ID and Target header. Since the Connection ID header is managed by the |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 51 | * implementation, it will not send a Connection ID header, if a Connection ID |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 52 | * was specified, in a packet that has a Target header. In other words, if an |
| 53 | * application adds a Target header to a <code>HeaderSet</code> object used in |
| 54 | * an OBEX operation and a Connection ID was specified, no Connection ID will be |
| 55 | * sent in the packet containing the Target header. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 56 | * <P> |
| 57 | * <STRONG>CREATE-EMPTY Requests</STRONG> |
| 58 | * <P> |
| 59 | * A CREATE-EMPTY request allows clients to create empty objects on the server. |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 60 | * When a CREATE-EMPTY request is received, the <code>onPut()</code> method will |
| 61 | * be called by the implementation. To differentiate between a normal PUT |
| 62 | * request and a CREATE-EMPTY request, an application must open the |
| 63 | * <code>InputStream</code> from the <code>Operation</code> object passed to the |
| 64 | * <code>onPut()</code> method. For a PUT request, the application will be able |
| 65 | * to read Body data from this <code>InputStream</code>. For a CREATE-EMPTY |
| 66 | * request, there will be no Body data to read. Therefore, a call to |
| 67 | * <code>InputStream.read()</code> will return -1. |
Nick Pelly | 2e0da96 | 2009-06-30 16:28:54 -0700 | [diff] [blame] | 68 | * @hide |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 69 | */ |
| 70 | public class ServerRequestHandler { |
| 71 | |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 72 | private long mConnectionId; |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 73 | |
| 74 | /** |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 75 | * Creates a <code>ServerRequestHandler</code>. |
| 76 | */ |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 77 | protected ServerRequestHandler() { |
| 78 | /* |
| 79 | * A connection ID of -1 implies there is no conenction ID |
| 80 | */ |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 81 | mConnectionId = -1; |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 82 | } |
| 83 | |
| 84 | /** |
| 85 | * Sets the connection ID header to include in the reply packets. |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 86 | * @param connectionId the connection ID to use; -1 if no connection ID |
| 87 | * should be sent |
| 88 | * @throws IllegalArgumentException if <code>id</code> is not in the range |
| 89 | * -1 to 2<sup>32</sup>-1 |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 90 | */ |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 91 | public void setConnectionId(final long connectionId) { |
| 92 | if ((connectionId < -1) || (connectionId > 0xFFFFFFFFL)) { |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 93 | throw new IllegalArgumentException("Illegal Connection ID"); |
| 94 | } |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 95 | mConnectionId = connectionId; |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 96 | } |
| 97 | |
| 98 | /** |
| 99 | * Retrieves the connection ID that is being used in the present connection. |
| 100 | * This method will return -1 if no connection ID is being used. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 101 | * @return the connection id being used or -1 if no connection ID is being |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 102 | * used |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 103 | */ |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 104 | public long getConnectionId() { |
| 105 | return mConnectionId; |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 106 | } |
| 107 | |
| 108 | /** |
| 109 | * Called when a CONNECT request is received. |
| 110 | * <P> |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 111 | * If this method is not implemented by the class that extends this class, |
| 112 | * <code>onConnect()</code> will always return an <code>OBEX_HTTP_OK</code> |
| 113 | * response code. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 114 | * <P> |
| 115 | * The headers received in the request can be retrieved from the |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 116 | * <code>request</code> argument. The headers that should be sent in the |
| 117 | * reply must be specified in the <code>reply</code> argument. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 118 | * @param request contains the headers sent by the client; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 119 | * <code>request</code> will never be <code>null</code> |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 120 | * @param reply the headers that should be sent in the reply; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 121 | * <code>reply</code> will never be <code>null</code> |
| 122 | * @return a response code defined in <code>ResponseCodes</code> that will |
| 123 | * be returned to the client; if an invalid response code is |
| 124 | * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code |
| 125 | * will be used |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 126 | */ |
| 127 | public int onConnect(HeaderSet request, HeaderSet reply) { |
| 128 | return ResponseCodes.OBEX_HTTP_OK; |
| 129 | } |
| 130 | |
| 131 | /** |
| 132 | * Called when a DISCONNECT request is received. |
| 133 | * <P> |
| 134 | * The headers received in the request can be retrieved from the |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 135 | * <code>request</code> argument. The headers that should be sent in the |
| 136 | * reply must be specified in the <code>reply</code> argument. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 137 | * @param request contains the headers sent by the client; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 138 | * <code>request</code> will never be <code>null</code> |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 139 | * @param reply the headers that should be sent in the reply; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 140 | * <code>reply</code> will never be <code>null</code> |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 141 | */ |
| 142 | public void onDisconnect(HeaderSet request, HeaderSet reply) { |
| 143 | } |
| 144 | |
| 145 | /** |
| 146 | * Called when a SETPATH request is received. |
| 147 | * <P> |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 148 | * If this method is not implemented by the class that extends this class, |
| 149 | * <code>onSetPath()</code> will always return an |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 150 | * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code. |
| 151 | * <P> |
| 152 | * The headers received in the request can be retrieved from the |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 153 | * <code>request</code> argument. The headers that should be sent in the |
| 154 | * reply must be specified in the <code>reply</code> argument. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 155 | * @param request contains the headers sent by the client; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 156 | * <code>request</code> will never be <code>null</code> |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 157 | * @param reply the headers that should be sent in the reply; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 158 | * <code>reply</code> will never be <code>null</code> |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 159 | * @param backup <code>true</code> if the client requests that the server |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 160 | * back up one directory before changing to the path described by |
| 161 | * <code>name</code>; <code>false</code> to apply the request to the |
| 162 | * present path |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 163 | * @param create <code>true</code> if the path should be created if it does |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 164 | * not already exist; <code>false</code> if the path should not be |
| 165 | * created if it does not exist and an error code should be returned |
| 166 | * @return a response code defined in <code>ResponseCodes</code> that will |
| 167 | * be returned to the client; if an invalid response code is |
| 168 | * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code |
| 169 | * will be used |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 170 | */ |
| 171 | public int onSetPath(HeaderSet request, HeaderSet reply, boolean backup, boolean create) { |
| 172 | |
| 173 | return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; |
| 174 | } |
| 175 | |
| 176 | /** |
| 177 | * Called when a DELETE request is received. |
| 178 | * <P> |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 179 | * If this method is not implemented by the class that extends this class, |
| 180 | * <code>onDelete()</code> will always return an |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 181 | * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code. |
| 182 | * <P> |
| 183 | * The headers received in the request can be retrieved from the |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 184 | * <code>request</code> argument. The headers that should be sent in the |
| 185 | * reply must be specified in the <code>reply</code> argument. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 186 | * @param request contains the headers sent by the client; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 187 | * <code>request</code> will never be <code>null</code> |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 188 | * @param reply the headers that should be sent in the reply; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 189 | * <code>reply</code> will never be <code>null</code> |
| 190 | * @return a response code defined in <code>ResponseCodes</code> that will |
| 191 | * be returned to the client; if an invalid response code is |
| 192 | * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code |
| 193 | * will be used |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 194 | */ |
| 195 | public int onDelete(HeaderSet request, HeaderSet reply) { |
| 196 | return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; |
| 197 | } |
| 198 | |
| 199 | /** |
Lixin Yue | 8258ebd | 2010-03-02 17:21:09 +0800 | [diff] [blame] | 200 | * Called when a ABORT request is received. |
| 201 | */ |
| 202 | public int onAbort(HeaderSet request, HeaderSet reply) { |
| 203 | return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; |
| 204 | } |
| 205 | |
| 206 | /** |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 207 | * Called when a PUT request is received. |
| 208 | * <P> |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 209 | * If this method is not implemented by the class that extends this class, |
| 210 | * <code>onPut()</code> will always return an |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 211 | * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code. |
| 212 | * <P> |
| 213 | * If an ABORT request is received during the processing of a PUT request, |
| 214 | * <code>op</code> will be closed by the implementation. |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 215 | * @param operation contains the headers sent by the client and allows new |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 216 | * headers to be sent in the reply; <code>op</code> will never be |
| 217 | * <code>null</code> |
| 218 | * @return a response code defined in <code>ResponseCodes</code> that will |
| 219 | * be returned to the client; if an invalid response code is |
| 220 | * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code |
| 221 | * will be used |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 222 | */ |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 223 | public int onPut(Operation operation) { |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 224 | return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; |
| 225 | } |
| 226 | |
| 227 | /** |
| 228 | * Called when a GET request is received. |
| 229 | * <P> |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 230 | * If this method is not implemented by the class that extends this class, |
| 231 | * <code>onGet()</code> will always return an |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 232 | * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code. |
| 233 | * <P> |
| 234 | * If an ABORT request is received during the processing of a GET request, |
| 235 | * <code>op</code> will be closed by the implementation. |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 236 | * @param operation contains the headers sent by the client and allows new |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 237 | * headers to be sent in the reply; <code>op</code> will never be |
| 238 | * <code>null</code> |
| 239 | * @return a response code defined in <code>ResponseCodes</code> that will |
| 240 | * be returned to the client; if an invalid response code is |
| 241 | * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code |
| 242 | * will be used |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 243 | */ |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 244 | public int onGet(Operation operation) { |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 245 | return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; |
| 246 | } |
| 247 | |
| 248 | /** |
| 249 | * Called when this object attempts to authenticate a client and the |
| 250 | * authentication request fails because the response digest in the |
| 251 | * authentication response header was wrong. |
| 252 | * <P> |
| 253 | * If this method is not implemented by the class that extends this class, |
| 254 | * this method will do nothing. |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 255 | * @param userName the user name returned in the authentication response; |
Tao Liejun | 05ff98bb | 2009-07-13 15:57:11 -0700 | [diff] [blame] | 256 | * <code>null</code> if no user name was provided in the response |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 257 | */ |
| 258 | public void onAuthenticationFailure(byte[] userName) { |
| 259 | } |
| 260 | |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 261 | /** |
| 262 | * Called by ServerSession to update the status of current transaction |
| 263 | * <P> |
| 264 | * If this method is not implemented by the class that extends this class, |
| 265 | * this method will do nothing. |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 266 | */ |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 267 | public void updateStatus(String message) { |
| 268 | } |
| 269 | |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 270 | /** |
| 271 | * Called when session is closed. |
| 272 | * <P> |
| 273 | * If this method is not implemented by the class that extends this class, |
| 274 | * this method will do nothing. |
Tao Liejun | 3998bf0 | 2009-07-02 19:29:09 +0800 | [diff] [blame] | 275 | */ |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 276 | public void onClose() { |
| 277 | } |
Casper Bonde | 238e0f9 | 2015-04-09 09:24:48 +0200 | [diff] [blame] | 278 | |
| 279 | /** |
| 280 | * Override to add Single Response Mode support - e.g. if the supplied |
| 281 | * transport is l2cap. |
| 282 | * @return True if SRM is supported, else False |
| 283 | */ |
| 284 | public boolean isSrmSupported() { |
| 285 | return false; |
| 286 | } |
Nick Pelly | 9439a7f | 2009-06-30 12:04:36 -0700 | [diff] [blame] | 287 | } |