1 /* 2 * Copyright (C) 2011 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 17 package com.squareup.okhttp.internal.framed; 18 19 import java.io.Closeable; 20 import java.io.IOException; 21 import java.util.List; 22 import okio.BufferedSource; 23 import okio.ByteString; 24 25 /** Reads transport frames for SPDY/3 or HTTP/2. */ 26 public interface FrameReader extends Closeable { readConnectionPreface()27 void readConnectionPreface() throws IOException; nextFrame(Handler handler)28 boolean nextFrame(Handler handler) throws IOException; 29 30 interface Handler { data(boolean inFinished, int streamId, BufferedSource source, int length)31 void data(boolean inFinished, int streamId, BufferedSource source, int length) 32 throws IOException; 33 34 /** 35 * Create or update incoming headers, creating the corresponding streams 36 * if necessary. Frames that trigger this are SPDY SYN_STREAM, HEADERS, and 37 * SYN_REPLY, and HTTP/2 HEADERS and PUSH_PROMISE. 38 * 39 * @param outFinished true if the receiver should not send further frames. 40 * @param inFinished true if the sender will not send further frames. 41 * @param streamId the stream owning these headers. 42 * @param associatedStreamId the stream that triggered the sender to create 43 * this stream. 44 */ headers(boolean outFinished, boolean inFinished, int streamId, int associatedStreamId, List<Header> headerBlock, HeadersMode headersMode)45 void headers(boolean outFinished, boolean inFinished, int streamId, int associatedStreamId, 46 List<Header> headerBlock, HeadersMode headersMode); rstStream(int streamId, ErrorCode errorCode)47 void rstStream(int streamId, ErrorCode errorCode); settings(boolean clearPrevious, Settings settings)48 void settings(boolean clearPrevious, Settings settings); 49 50 /** HTTP/2 only. */ ackSettings()51 void ackSettings(); 52 53 /** 54 * Read a connection-level ping from the peer. {@code ack} indicates this 55 * is a reply. Payload parameters are different between SPDY/3 and HTTP/2. 56 * <p> 57 * In SPDY/3, only the first {@code payload1} parameter is set. If the 58 * reader is a client, it is an unsigned even number. Likewise, a server 59 * will receive an odd number. 60 * <p> 61 * In HTTP/2, both {@code payload1} and {@code payload2} parameters are 62 * set. The data is opaque binary, and there are no rules on the content. 63 */ ping(boolean ack, int payload1, int payload2)64 void ping(boolean ack, int payload1, int payload2); 65 66 /** 67 * The peer tells us to stop creating streams. It is safe to replay 68 * streams with {@code ID > lastGoodStreamId} on a new connection. In- 69 * flight streams with {@code ID <= lastGoodStreamId} can only be replayed 70 * on a new connection if they are idempotent. 71 * 72 * @param lastGoodStreamId the last stream ID the peer processed before 73 * sending this message. If {@code lastGoodStreamId} is zero, the peer 74 * processed no frames. 75 * @param errorCode reason for closing the connection. 76 * @param debugData only valid for HTTP/2; opaque debug data to send. 77 */ goAway(int lastGoodStreamId, ErrorCode errorCode, ByteString debugData)78 void goAway(int lastGoodStreamId, ErrorCode errorCode, ByteString debugData); 79 80 /** 81 * Notifies that an additional {@code windowSizeIncrement} bytes can be 82 * sent on {@code streamId}, or the connection if {@code streamId} is zero. 83 */ windowUpdate(int streamId, long windowSizeIncrement)84 void windowUpdate(int streamId, long windowSizeIncrement); 85 86 /** 87 * Called when reading a headers or priority frame. This may be used to 88 * change the stream's weight from the default (16) to a new value. 89 * 90 * @param streamId stream which has a priority change. 91 * @param streamDependency the stream ID this stream is dependent on. 92 * @param weight relative proportion of priority in [1..256]. 93 * @param exclusive inserts this stream ID as the sole child of 94 * {@code streamDependency}. 95 */ priority(int streamId, int streamDependency, int weight, boolean exclusive)96 void priority(int streamId, int streamDependency, int weight, boolean exclusive); 97 98 /** 99 * HTTP/2 only. Receive a push promise header block. 100 * <p> 101 * A push promise contains all the headers that pertain to a server-initiated 102 * request, and a {@code promisedStreamId} to which response frames will be 103 * delivered. Push promise frames are sent as a part of the response to 104 * {@code streamId}. 105 * 106 * @param streamId client-initiated stream ID. Must be an odd number. 107 * @param promisedStreamId server-initiated stream ID. Must be an even 108 * number. 109 * @param requestHeaders minimally includes {@code :method}, {@code :scheme}, 110 * {@code :authority}, and (@code :path}. 111 */ pushPromise(int streamId, int promisedStreamId, List<Header> requestHeaders)112 void pushPromise(int streamId, int promisedStreamId, List<Header> requestHeaders) 113 throws IOException; 114 115 /** 116 * HTTP/2 only. Expresses that resources for the connection or a client- 117 * initiated stream are available from a different network location or 118 * protocol configuration. 119 * 120 * <p>See <a href="http://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-01">alt-svc</a> 121 * 122 * @param streamId when a client-initiated stream ID (odd number), the 123 * origin of this alternate service is the origin of the stream. When 124 * zero, the origin is specified in the {@code origin} parameter. 125 * @param origin when present, the 126 * <a href="http://tools.ietf.org/html/rfc6454">origin</a> is typically 127 * represented as a combination of scheme, host and port. When empty, 128 * the origin is that of the {@code streamId}. 129 * @param protocol an ALPN protocol, such as {@code h2}. 130 * @param host an IP address or hostname. 131 * @param port the IP port associated with the service. 132 * @param maxAge time in seconds that this alternative is considered fresh. 133 */ alternateService(int streamId, String origin, ByteString protocol, String host, int port, long maxAge)134 void alternateService(int streamId, String origin, ByteString protocol, String host, int port, 135 long maxAge); 136 } 137 } 138