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 * {@hide}
28 */
29
30public interface EventHandler {
31
32    /**
33     * Error codes used in the error() callback.  Positive error codes
34     * are reserved for codes sent by http servers.  Negative error
35     * codes are connection/parsing failures, etc.
36     */
37
38    /** Success */
39    public static final int OK = 0;
40    /** Generic error */
41    public static final int ERROR = -1;
42    /** Server or proxy hostname lookup failed */
43    public static final int ERROR_LOOKUP = -2;
44    /** Unsupported authentication scheme (ie, not basic or digest) */
45    public static final int ERROR_UNSUPPORTED_AUTH_SCHEME = -3;
46    /** User authentication failed on server */
47    public static final int ERROR_AUTH = -4;
48    /** User authentication failed on proxy */
49    public static final int ERROR_PROXYAUTH = -5;
50    /** Could not connect to server */
51    public static final int ERROR_CONNECT = -6;
52    /** Failed to write to or read from server */
53    public static final int ERROR_IO = -7;
54    /** Connection timed out */
55    public static final int ERROR_TIMEOUT = -8;
56    /** Too many redirects */
57    public static final int ERROR_REDIRECT_LOOP = -9;
58    /** Unsupported URI scheme (ie, not http, https, etc) */
59    public static final int ERROR_UNSUPPORTED_SCHEME = -10;
60    /** Failed to perform SSL handshake */
61    public static final int ERROR_FAILED_SSL_HANDSHAKE = -11;
62    /** Bad URL */
63    public static final int ERROR_BAD_URL = -12;
64    /** Generic file error for file:/// loads */
65    public static final int FILE_ERROR = -13;
66    /** File not found error for file:/// loads */
67    public static final int FILE_NOT_FOUND_ERROR = -14;
68    /** Too many requests queued */
69    public static final int TOO_MANY_REQUESTS_ERROR = -15;
70
71    /**
72     * Called after status line has been sucessfully processed.
73     * @param major_version HTTP version advertised by server.  major
74     * is the part before the "."
75     * @param minor_version HTTP version advertised by server.  minor
76     * is the part after the "."
77     * @param code HTTP Status code.  See RFC 2616.
78     * @param reason_phrase Textual explanation sent by server
79     */
80    public void status(int major_version,
81                       int minor_version,
82                       int code,
83                       String reason_phrase);
84
85    /**
86     * Called after all headers are successfully processed.
87     */
88    public void headers(Headers headers);
89
90    /**
91     * An array containing all or part of the http body as read from
92     * the server.
93     * @param data A byte array containing the content
94     * @param len The length of valid content in data
95     *
96     * Note: chunked and compressed encodings are handled within
97     * android.net.http.  Decoded data is passed through this
98     * interface.
99     */
100    public void data(byte[] data, int len);
101
102    /**
103     * Called when the document is completely read.  No more data()
104     * callbacks will be made after this call
105     */
106    public void endData();
107
108    /**
109     * SSL certificate callback called before resource request is
110     * made, which will be null for insecure connection.
111     */
112    public void certificate(SslCertificate certificate);
113
114    /**
115     * There was trouble.
116     * @param id One of the error codes defined below
117     * @param description of error
118     */
119    public void error(int id, String description);
120
121    /**
122     * SSL certificate error callback. Handles SSL error(s) on the way
123     * up to the user. The callback has to make sure that restartConnection() is called,
124     * otherwise the connection will be suspended indefinitely.
125     * @return True if the callback can handle the error, which means it will
126     *              call restartConnection() to unblock the thread later,
127     *              otherwise return false.
128     */
129    public boolean handleSslErrorRequest(SslError error);
130
131}
132