1 // Copyright 2016 The Chromium Authors 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 package android.net.http; 6 7 import androidx.annotation.Nullable; 8 9 /** 10 * Exception passed to {@link UrlRequest.Callback#onFailed UrlRequest.Callback.onFailed()} when 11 * the HTTP stack fails to process a network request. In this case {@link #getErrorCode} can be used 12 * to get more information about the specific type of failure. 13 */ 14 public abstract class NetworkException extends HttpException { 15 /** 16 * Error code indicating the host being sent the request could not be resolved to an IP address. 17 */ 18 public static final int ERROR_HOSTNAME_NOT_RESOLVED = 1; 19 /** 20 * Error code indicating the device was not connected to any network. 21 */ 22 public static final int ERROR_INTERNET_DISCONNECTED = 2; 23 /** 24 * Error code indicating that as the request was processed the network configuration changed. 25 * When 26 * {@link #getErrorCode} returns this code, this exception may be cast to {@link QuicException} 27 * for more information if <a href="https://www.chromium.org/quic"> QUIC</a> protocol is used. 28 */ 29 public static final int ERROR_NETWORK_CHANGED = 3; 30 /** 31 * Error code indicating a timeout expired. Timeouts expiring while attempting to connect will 32 * be reported as the more specific {@link #ERROR_CONNECTION_TIMED_OUT}. 33 */ 34 public static final int ERROR_TIMED_OUT = 4; 35 /** 36 * Error code indicating the connection was closed unexpectedly. 37 */ 38 public static final int ERROR_CONNECTION_CLOSED = 5; 39 /** 40 * Error code indicating the connection attempt timed out. 41 */ 42 public static final int ERROR_CONNECTION_TIMED_OUT = 6; 43 /** 44 * Error code indicating the connection attempt was refused. 45 */ 46 public static final int ERROR_CONNECTION_REFUSED = 7; 47 /** 48 * Error code indicating the connection was unexpectedly reset. 49 */ 50 public static final int ERROR_CONNECTION_RESET = 8; 51 /** 52 * Error code indicating the IP address being contacted is unreachable, meaning there is no 53 * route to the specified host or network. 54 */ 55 public static final int ERROR_ADDRESS_UNREACHABLE = 9; 56 /** 57 * Error code indicating an error related to the <a href="https://www.chromium.org/quic"> 58 * QUIC</a> protocol. When {@link #getErrorCode} returns this code, this exception can be cast 59 * to {@link QuicException} for more information. 60 */ 61 public static final int ERROR_QUIC_PROTOCOL_FAILED = 10; 62 /** 63 * Error code indicating another type of error was encountered. 64 */ 65 public static final int ERROR_OTHER = 11; 66 67 /** 68 * Constructs an exception that is caused by a network error. 69 * 70 * @param message explanation of failure. 71 * @param cause the cause (which is saved for later retrieval by the {@link 72 * java.io.IOException#getCause getCause()} method). A null value is permitted, and indicates 73 * that the cause is nonexistent or unknown. 74 */ NetworkException(@ullable String message, @Nullable Throwable cause)75 public NetworkException(@Nullable String message, @Nullable Throwable cause) { 76 super(message, cause); 77 } 78 79 /** 80 * Returns error code, one of {@link #ERROR_HOSTNAME_NOT_RESOLVED ERROR_*}. 81 * 82 * @return error code, one of {@link #ERROR_HOSTNAME_NOT_RESOLVED ERROR_*}. 83 */ getErrorCode()84 public abstract int getErrorCode(); 85 86 /** 87 * Returns an internal error code. This may provide more specific error 88 * diagnosis than {@link #getErrorCode}, but the constant values are not exposed publicly and 89 * may change over time. See 90 * <a href=https://chromium.googlesource.com/chromium/src/+/main/net/base/net_error_list.h> 91 * here</a> for the latest list of values. 92 * 93 * @return internal error code or 0 if the internal error code is unknown 94 * 95 * {@hide as semantics aren't stable} 96 */ getInternalErrorCode()97 public int getInternalErrorCode() { 98 return 0; 99 } 100 101 /** 102 * Returns {@code true} if retrying this request right away might succeed, {@code false} 103 * otherwise. For example returns {@code true} when {@link #getErrorCode} returns {@link 104 * #ERROR_NETWORK_CHANGED} because trying the request might succeed using the new network 105 * configuration, but {@code false} when {@code getErrorCode()} returns {@link 106 * #ERROR_INTERNET_DISCONNECTED} because retrying the request right away will encounter the same 107 * failure (instead retrying should be delayed until device regains network connectivity). 108 * 109 * @return {@code true} if retrying this request right away might succeed, {@code false} 110 * otherwise. 111 */ isImmediatelyRetryable()112 public abstract boolean isImmediatelyRetryable(); 113 } 114