1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.net.http;
18
19
20/**
21 * Callbacks in this interface are made as an HTTP request is
22 * processed. The normal order of callbacks is status(), headers(),
23 * then multiple data() then endData().  handleSslErrorRequest(), if
24 * there is an SSL certificate error. error() can occur anywhere
25 * in the transaction.
26 */
27
28public interface EventHandler {
29
30    /**
31     * Error codes used in the error() callback.  Positive error codes
32     * are reserved for codes sent by http servers.  Negative error
33     * codes are connection/parsing failures, etc.
34     */
35
36    /** Success */
37    public static final int OK = 0;
38    /** Generic error */
39    public static final int ERROR = -1;
40    /** Server or proxy hostname lookup failed */
41    public static final int ERROR_LOOKUP = -2;
42    /** Unsupported authentication scheme (ie, not basic or digest) */
43    public static final int ERROR_UNSUPPORTED_AUTH_SCHEME = -3;
44    /** User authentication failed on server */
45    public static final int ERROR_AUTH = -4;
46    /** User authentication failed on proxy */
47    public static final int ERROR_PROXYAUTH = -5;
48    /** Could not connect to server */
49    public static final int ERROR_CONNECT = -6;
50    /** Failed to write to or read from server */
51    public static final int ERROR_IO = -7;
52    /** Connection timed out */
53    public static final int ERROR_TIMEOUT = -8;
54    /** Too many redirects */
55    public static final int ERROR_REDIRECT_LOOP = -9;
56    /** Unsupported URI scheme (ie, not http, https, etc) */
57    public static final int ERROR_UNSUPPORTED_SCHEME = -10;
58    /** Failed to perform SSL handshake */
59    public static final int ERROR_FAILED_SSL_HANDSHAKE = -11;
60    /** Bad URL */
61    public static final int ERROR_BAD_URL = -12;
62    /** Generic file error for file:/// loads */
63    public static final int FILE_ERROR = -13;
64    /** File not found error for file:/// loads */
65    public static final int FILE_NOT_FOUND_ERROR = -14;
66    /** Too many requests queued */
67    public static final int TOO_MANY_REQUESTS_ERROR = -15;
68
69    /**
70     * Called after status line has been sucessfully processed.
71     * @param major_version HTTP version advertised by server.  major
72     * is the part before the "."
73     * @param minor_version HTTP version advertised by server.  minor
74     * is the part after the "."
75     * @param code HTTP Status code.  See RFC 2616.
76     * @param reason_phrase Textual explanation sent by server
77     */
78    public void status(int major_version,
79                       int minor_version,
80                       int code,
81                       String reason_phrase);
82
83    /**
84     * Called after all headers are successfully processed.
85     */
86    public void headers(Headers headers);
87
88    /**
89     * An array containing all or part of the http body as read from
90     * the server.
91     * @param data A byte array containing the content
92     * @param len The length of valid content in data
93     *
94     * Note: chunked and compressed encodings are handled within
95     * android.net.http.  Decoded data is passed through this
96     * interface.
97     */
98    public void data(byte[] data, int len);
99
100    /**
101     * Called when the document is completely read.  No more data()
102     * callbacks will be made after this call
103     */
104    public void endData();
105
106    /**
107     * SSL certificate callback called before resource request is
108     * made, which will be null for insecure connection.
109     */
110    public void certificate(SslCertificate certificate);
111
112    /**
113     * There was trouble.
114     * @param id One of the error codes defined below
115     * @param description of error
116     */
117    public void error(int id, String description);
118
119    /**
120     * SSL certificate error callback. Handles SSL error(s) on the way
121     * up to the user. The callback has to make sure that restartConnection() is called,
122     * otherwise the connection will be suspended indefinitely.
123     * @return True if the callback can handle the error, which means it will
124     *              call restartConnection() to unblock the thread later,
125     *              otherwise return false.
126     */
127    public boolean handleSslErrorRequest(SslError error);
128
129}
130