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 com.android.obex; 34 35 /** 36 * The <code>ServerRequestHandler</code> class defines an event listener that 37 * will respond to OBEX requests made to the server. 38 * <P> 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. 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 50 * ID and Target header. Since the Connection ID header is managed by the 51 * implementation, it will not send a Connection ID header, if a Connection ID 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. 56 * <P> 57 * <STRONG>CREATE-EMPTY Requests</STRONG> 58 * <P> 59 * A CREATE-EMPTY request allows clients to create empty objects on the server. 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. 68 */ 69 public class ServerRequestHandler { 70 71 private long mConnectionId; 72 73 /** 74 * Creates a <code>ServerRequestHandler</code>. 75 */ ServerRequestHandler()76 protected ServerRequestHandler() { 77 /* 78 * A connection ID of -1 implies there is no connection ID 79 */ 80 mConnectionId = -1; 81 } 82 83 /** 84 * Sets the connection ID header to include in the reply packets. 85 * @param connectionId the connection ID to use; -1 if no connection ID 86 * should be sent 87 * @throws IllegalArgumentException if <code>id</code> is not in the range 88 * -1 to 2<sup>32</sup>-1 89 * 90 * @hide 91 */ setConnectionId(final long connectionId)92 public void setConnectionId(final long connectionId) { 93 if ((connectionId < -1) || (connectionId > 0xFFFFFFFFL)) { 94 throw new IllegalArgumentException("Illegal Connection ID"); 95 } 96 mConnectionId = connectionId; 97 } 98 99 /** 100 * Retrieves the connection ID that is being used in the present connection. 101 * This method will return -1 if no connection ID is being used. 102 * @return the connection id being used or -1 if no connection ID is being 103 * used 104 * 105 * @hide 106 */ getConnectionId()107 public long getConnectionId() { 108 return mConnectionId; 109 } 110 111 /** 112 * Called when a CONNECT request is received. 113 * <P> 114 * If this method is not implemented by the class that extends this class, 115 * <code>onConnect()</code> will always return an <code>OBEX_HTTP_OK</code> 116 * response code. 117 * <P> 118 * The headers received in the request can be retrieved from the 119 * <code>request</code> argument. The headers that should be sent in the 120 * reply must be specified in the <code>reply</code> argument. 121 * @param request contains the headers sent by the client; 122 * <code>request</code> will never be <code>null</code> 123 * @param reply the headers that should be sent in the reply; 124 * <code>reply</code> will never be <code>null</code> 125 * @return a response code defined in <code>ResponseCodes</code> that will 126 * be returned to the client; if an invalid response code is 127 * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code 128 * will be used 129 */ onConnect(HeaderSet request, HeaderSet reply)130 public int onConnect(HeaderSet request, HeaderSet reply) { 131 return ResponseCodes.OBEX_HTTP_OK; 132 } 133 134 /** 135 * Called when a DISCONNECT request is received. 136 * <P> 137 * The headers received in the request can be retrieved from the 138 * <code>request</code> argument. The headers that should be sent in the 139 * reply must be specified in the <code>reply</code> argument. 140 * @param request contains the headers sent by the client; 141 * <code>request</code> will never be <code>null</code> 142 * @param reply the headers that should be sent in the reply; 143 * <code>reply</code> will never be <code>null</code> 144 */ onDisconnect(HeaderSet request, HeaderSet reply)145 public void onDisconnect(HeaderSet request, HeaderSet reply) { 146 } 147 148 /** 149 * Called when a SETPATH request is received. 150 * <P> 151 * If this method is not implemented by the class that extends this class, 152 * <code>onSetPath()</code> will always return an 153 * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code. 154 * <P> 155 * The headers received in the request can be retrieved from the 156 * <code>request</code> argument. The headers that should be sent in the 157 * reply must be specified in the <code>reply</code> argument. 158 * @param request contains the headers sent by the client; 159 * <code>request</code> will never be <code>null</code> 160 * @param reply the headers that should be sent in the reply; 161 * <code>reply</code> will never be <code>null</code> 162 * @param backup <code>true</code> if the client requests that the server 163 * back up one directory before changing to the path described by 164 * <code>name</code>; <code>false</code> to apply the request to the 165 * present path 166 * @param create <code>true</code> if the path should be created if it does 167 * not already exist; <code>false</code> if the path should not be 168 * created if it does not exist and an error code should be returned 169 * @return a response code defined in <code>ResponseCodes</code> that will 170 * be returned to the client; if an invalid response code is 171 * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code 172 * will be used 173 */ onSetPath(HeaderSet request, HeaderSet reply, boolean backup, boolean create)174 public int onSetPath(HeaderSet request, HeaderSet reply, boolean backup, boolean create) { 175 176 return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; 177 } 178 179 /** 180 * Called when a DELETE request is received. 181 * <P> 182 * If this method is not implemented by the class that extends this class, 183 * <code>onDelete()</code> will always return an 184 * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code. 185 * <P> 186 * The headers received in the request can be retrieved from the 187 * <code>request</code> argument. The headers that should be sent in the 188 * reply must be specified in the <code>reply</code> argument. 189 * @param request contains the headers sent by the client; 190 * <code>request</code> will never be <code>null</code> 191 * @param reply the headers that should be sent in the reply; 192 * <code>reply</code> will never be <code>null</code> 193 * @return a response code defined in <code>ResponseCodes</code> that will 194 * be returned to the client; if an invalid response code is 195 * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code 196 * will be used 197 */ onDelete(HeaderSet request, HeaderSet reply)198 public int onDelete(HeaderSet request, HeaderSet reply) { 199 return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; 200 } 201 202 /** 203 * Called when a ABORT request is received. 204 */ onAbort(HeaderSet request, HeaderSet reply)205 public int onAbort(HeaderSet request, HeaderSet reply) { 206 return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; 207 } 208 209 /** 210 * Called when a PUT request is received. 211 * <P> 212 * If this method is not implemented by the class that extends this class, 213 * <code>onPut()</code> will always return an 214 * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code. 215 * <P> 216 * If an ABORT request is received during the processing of a PUT request, 217 * <code>op</code> will be closed by the implementation. 218 * @param operation contains the headers sent by the client and allows new 219 * headers to be sent in the reply; <code>op</code> will never be 220 * <code>null</code> 221 * @return a response code defined in <code>ResponseCodes</code> that will 222 * be returned to the client; if an invalid response code is 223 * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code 224 * will be used 225 */ onPut(Operation operation)226 public int onPut(Operation operation) { 227 return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; 228 } 229 230 /** 231 * Called when a GET request is received. 232 * <P> 233 * If this method is not implemented by the class that extends this class, 234 * <code>onGet()</code> will always return an 235 * <code>OBEX_HTTP_NOT_IMPLEMENTED</code> response code. 236 * <P> 237 * If an ABORT request is received during the processing of a GET request, 238 * <code>op</code> will be closed by the implementation. 239 * @param operation contains the headers sent by the client and allows new 240 * headers to be sent in the reply; <code>op</code> will never be 241 * <code>null</code> 242 * @return a response code defined in <code>ResponseCodes</code> that will 243 * be returned to the client; if an invalid response code is 244 * provided, the <code>OBEX_HTTP_INTERNAL_ERROR</code> response code 245 * will be used 246 */ onGet(Operation operation)247 public int onGet(Operation operation) { 248 return ResponseCodes.OBEX_HTTP_NOT_IMPLEMENTED; 249 } 250 251 /** 252 * Called when this object attempts to authenticate a client and the 253 * authentication request fails because the response digest in the 254 * authentication response header was wrong. 255 * <P> 256 * If this method is not implemented by the class that extends this class, 257 * this method will do nothing. 258 * @param userName the user name returned in the authentication response; 259 * <code>null</code> if no user name was provided in the response 260 */ onAuthenticationFailure(byte[] userName)261 public void onAuthenticationFailure(byte[] userName) { 262 } 263 264 /** 265 * Called by ServerSession to update the status of current transaction 266 * <P> 267 * If this method is not implemented by the class that extends this class, 268 * this method will do nothing. 269 */ updateStatus(String message)270 public void updateStatus(String message) { 271 } 272 273 /** 274 * Called when session is closed. 275 * <P> 276 * If this method is not implemented by the class that extends this class, 277 * this method will do nothing. 278 */ onClose()279 public void onClose() { 280 } 281 282 /** 283 * Override to add Single Response Mode support - e.g. if the supplied 284 * transport is l2cap. 285 * @return True if SRM is supported, else False 286 */ isSrmSupported()287 public boolean isSrmSupported() { 288 return false; 289 } 290 } 291