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.spdy; 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 { readConnectionHeader()27 void readConnectionHeader() throws IOException; nextFrame(Handler handler)28 boolean nextFrame(Handler handler) throws IOException; 29 30 public 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 * @param priority or -1 for no priority. For SPDY, priorities range from 0 45 * (highest) thru 7 (lowest). For HTTP/2, priorities range from 0 46 * (highest) thru 2^31-1 (lowest), defaulting to 2^30. 47 */ headers(boolean outFinished, boolean inFinished, int streamId, int associatedStreamId, int priority, List<Header> headerBlock, HeadersMode headersMode)48 void headers(boolean outFinished, boolean inFinished, int streamId, int associatedStreamId, 49 int priority, List<Header> headerBlock, HeadersMode headersMode); rstStream(int streamId, ErrorCode errorCode)50 void rstStream(int streamId, ErrorCode errorCode); settings(boolean clearPrevious, Settings settings)51 void settings(boolean clearPrevious, Settings settings); 52 53 /** HTTP/2 only. */ ackSettings()54 void ackSettings(); 55 56 /** 57 * Read a connection-level ping from the peer. {@code ack} indicates this 58 * is a reply. Payload parameters are different between SPDY/3 and HTTP/2. 59 * <p> 60 * In SPDY/3, only the first {@code payload1} parameter is set. If the 61 * reader is a client, it is an unsigned even number. Likewise, a server 62 * will receive an odd number. 63 * <p> 64 * In HTTP/2, both {@code payload1} and {@code payload2} parameters are 65 * set. The data is opaque binary, and there are no rules on the content. 66 */ ping(boolean ack, int payload1, int payload2)67 void ping(boolean ack, int payload1, int payload2); 68 69 /** 70 * The peer tells us to stop creating streams. It is safe to replay 71 * streams with {@code ID > lastGoodStreamId} on a new connection. In- 72 * flight streams with {@code ID <= lastGoodStreamId} can only be replayed 73 * on a new connection if they are idempotent. 74 * 75 * @param lastGoodStreamId the last stream ID the peer processed before 76 * sending this message. If {@code lastGoodStreamId} is zero, the peer 77 * processed no frames. 78 * @param errorCode reason for closing the connection. 79 * @param debugData only valid for http/2; opaque debug data to send. 80 */ goAway(int lastGoodStreamId, ErrorCode errorCode, ByteString debugData)81 void goAway(int lastGoodStreamId, ErrorCode errorCode, ByteString debugData); 82 83 /** 84 * Notifies that an additional {@code windowSizeIncrement} bytes can be 85 * sent on {@code streamId}, or the connection if {@code streamId} is zero. 86 */ windowUpdate(int streamId, long windowSizeIncrement)87 void windowUpdate(int streamId, long windowSizeIncrement); priority(int streamId, int priority)88 void priority(int streamId, int priority); 89 90 /** 91 * HTTP/2 only. Receive a push promise header block. 92 * <p> 93 * A push promise contains all the headers that pertain to a server-initiated 94 * request, and a {@code promisedStreamId} to which response frames will be 95 * delivered. Push promise frames are sent as a part of the response to 96 * {@code streamId}. The {@code promisedStreamId} has a priority of one 97 * greater than {@code streamId}. 98 * 99 * @param streamId client-initiated stream ID. Must be an odd number. 100 * @param promisedStreamId server-initiated stream ID. Must be an even 101 * number. 102 * @param requestHeaders minimally includes {@code :method}, {@code :scheme}, 103 * {@code :authority}, and (@code :path}. 104 */ pushPromise(int streamId, int promisedStreamId, List<Header> requestHeaders)105 void pushPromise(int streamId, int promisedStreamId, List<Header> requestHeaders) 106 throws IOException; 107 } 108 } 109