1 /** 2 * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 3 * SPDX-License-Identifier: Apache-2.0. 4 */ 5 6 package software.amazon.awssdk.crt.http; 7 8 /** 9 * Interface that Native code knows how to call when handling Http Responses for HTTP/1.1 only. 10 * You can use HttpStreamBaseResponseHandler instead to adapt both HTTP/1.1 and HTTP/2 11 * 12 * Maps 1-1 to the Native Http API here: https://github.com/awslabs/aws-c-http/blob/master/include/aws/http/request_response.h 13 */ 14 public interface HttpStreamResponseHandler { 15 16 /** 17 * Called from Native when new Http Headers have been received. 18 * Note that this function may be called multiple times as HTTP headers are received. 19 * 20 * @param stream The HttpStream object 21 * @param responseStatusCode The HTTP Response Status Code 22 * @param blockType The HTTP header block type 23 * @param nextHeaders The headers received in the latest IO event. 24 */ onResponseHeaders(HttpStream stream, int responseStatusCode, int blockType, HttpHeader[] nextHeaders)25 void onResponseHeaders(HttpStream stream, int responseStatusCode, int blockType, HttpHeader[] nextHeaders); 26 27 /** 28 * Called from Native once all HTTP Headers are processed. Will not be called if there are no Http Headers in the 29 * response. Guaranteed to be called exactly once if there is at least 1 Header. 30 * 31 * @param stream The HttpStream object 32 * @param blockType The type of the header block, corresponds to {@link HttpHeaderBlock} 33 */ onResponseHeadersDone(HttpStream stream, int blockType)34 default void onResponseHeadersDone(HttpStream stream, int blockType) { 35 /* Optional Callback, do nothing by default */ 36 } 37 38 /** 39 * Called when new Response Body bytes have been received. Note that this function may be called multiple times over 40 * the lifetime of an HttpClientConnection as bytes are received. 41 * <p> 42 * Note that if {@link HttpClientConnectionManagerOptions#withManualWindowManagement} was set true, 43 * you must manage the flow-control window. 44 * The flow-control window shrinks as you receive body data via this callback. 45 * Whenever the flow-control window reaches zero, data will stop downloading. 46 * To keep data flowing, you must increment the window by returning a number 47 * from this method, or by calling {@link HttpStreamBase#incrementWindow}. 48 * 49 * @param stream The HTTP Stream the body was delivered to 50 * @param bodyBytesIn The HTTP Body Bytes received in the last IO Event. 51 * @return The number of bytes to increment the window by 52 * (calling {@link HttpStreamBase#incrementWindow} has the same effect). 53 * This value is ignored if "manual window management" is disabled. 54 * @see HttpClientConnectionManagerOptions#withManualWindowManagement 55 */ onResponseBody(HttpStream stream, byte[] bodyBytesIn)56 default int onResponseBody(HttpStream stream, byte[] bodyBytesIn) { 57 /* Optional Callback, ignore incoming response body by default unless user wants to capture it. */ 58 return bodyBytesIn.length; 59 } 60 61 /** 62 * Called right before stream is complete, whether successful or unsuccessful. 63 * @param stream The HTTP stream to which the metrics apply 64 * @param metrics The [HttpStreamMetrics] containing metrics for the given stream 65 */ onMetrics(HttpStream stream, HttpStreamMetrics metrics)66 default void onMetrics(HttpStream stream, HttpStreamMetrics metrics) { 67 /* Optional callback, nothing to do by default */ 68 } 69 70 /** 71 * Called from Native when the Response has completed. 72 * @param stream completed stream 73 * @param errorCode resultant errorCode for the response 74 */ onResponseComplete(HttpStream stream, int errorCode)75 void onResponseComplete(HttpStream stream, int errorCode); 76 } 77