1 /* 2 * Copyright (C) 2014 Square, Inc. 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 package com.squareup.okhttp.ws; 17 18 import com.squareup.okhttp.Response; 19 import com.squareup.okhttp.ResponseBody; 20 import java.io.IOException; 21 import okio.Buffer; 22 23 /** Listener for server-initiated messages on a connected {@link WebSocket}. */ 24 public interface WebSocketListener { 25 /** 26 * Called when the request has successfully been upgraded to a web socket. This method is called 27 * on the message reading thread to allow setting up any state before the 28 * {@linkplain #onMessage message}, {@linkplain #onPong pong}, and {@link #onClose close} 29 * callbacks start. 30 * <p> 31 * <b>Do not</b> use this callback to write to the web socket. Start a new thread or use 32 * another thread in your application. 33 */ onOpen(WebSocket webSocket, Response response)34 void onOpen(WebSocket webSocket, Response response); 35 36 /** 37 * Called when the transport or protocol layer of this web socket errors during communication. 38 * 39 * @param response Present when the failure is a direct result of the response (e.g., failed 40 * upgrade, non-101 response code, etc.). {@code null} otherwise. 41 */ onFailure(IOException e, Response response)42 void onFailure(IOException e, Response response); 43 44 /** 45 * Called when a server message is received. The {@code type} indicates whether the 46 * {@code payload} should be interpreted as UTF-8 text or binary data. 47 * 48 * <p>Implementations <strong>must</strong> call {@code source.close()} before returning. This 49 * indicates completion of parsing the message payload and will consume any remaining bytes in 50 * the message. 51 * 52 * <p>The {@linkplain ResponseBody#contentType() content type} of {@code message} will be either 53 * {@link WebSocket#TEXT} or {@link WebSocket#BINARY} which indicates the format of the message. 54 */ onMessage(ResponseBody message)55 void onMessage(ResponseBody message) throws IOException; 56 57 /** 58 * Called when a server pong is received. This is usually a result of calling {@link 59 * WebSocket#sendPing(Buffer)} but might also be unsolicited. 60 */ onPong(Buffer payload)61 void onPong(Buffer payload); 62 63 /** 64 * Called when the server sends a close message. This may have been initiated 65 * from a call to {@link WebSocket#close(int, String) close()} or as an unprompted 66 * message from the server. 67 * 68 * @param code The <a href="http://tools.ietf.org/html/rfc6455#section-7.4.1">RFC-compliant</a> 69 * status code. 70 * @param reason Reason for close or an empty string. 71 */ onClose(int code, String reason)72 void onClose(int code, String reason); 73 } 74