1e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller/* 2e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Copyright (C) 2014 Square, Inc. 3e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 4e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Licensed under the Apache License, Version 2.0 (the "License"); 5e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * you may not use this file except in compliance with the License. 6e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * You may obtain a copy of the License at 7e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 8e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * http://www.apache.org/licenses/LICENSE-2.0 9e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 10e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Unless required by applicable law or agreed to in writing, software 11e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * distributed under the License is distributed on an "AS IS" BASIS, 12e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * See the License for the specific language governing permissions and 14e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * limitations under the License. 15e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 16a2cab72aa5ff730ba2ae987b45398faafffeb505Neil Fullerpackage com.squareup.okhttp.ws; 17e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 186c251e20f00c7574b217bd4351ac81666f574380Tobias Thiererimport com.squareup.okhttp.MediaType; 196c251e20f00c7574b217bd4351ac81666f574380Tobias Thiererimport com.squareup.okhttp.RequestBody; 20e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fullerimport java.io.IOException; 21e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fullerimport okio.Buffer; 22e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 23e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller/** Blocking interface to connect and write to a web socket. */ 24e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fullerpublic interface WebSocket { 256c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer /** A {@link MediaType} indicating UTF-8 text frames should be used when sending the message. */ 266c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer MediaType TEXT = MediaType.parse("application/vnd.okhttp.websocket+text; charset=utf-8"); 276c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer /** A {@link MediaType} indicating binary frames should be used when sending the message. */ 286c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer MediaType BINARY = MediaType.parse("application/vnd.okhttp.websocket+binary"); 29e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 30e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** 316c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * Send a message payload to the server. 32e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 336c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * <p>The {@linkplain RequestBody#contentType() content type} of {@code message} should be either 346c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * {@link #TEXT} or {@link #BINARY}. 35e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 366c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * @throws IOException if unable to write the message. Clients must call {@link #close} when this 376c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * happens to ensure resources are cleaned up. 38e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @throws IllegalStateException if not connected, already closed, or another writer is active. 39e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 406c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer void sendMessage(RequestBody message) throws IOException; 41e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 42e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** 43e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Send a ping to the server with optional payload. 44e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 456c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * @throws IOException if unable to write the ping. Clients must call {@link #close} when this 466c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * happens to ensure resources are cleaned up. 47e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @throws IllegalStateException if already closed. 48e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 49e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller void sendPing(Buffer payload) throws IOException; 50e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller 51e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller /** 52e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * Send a close frame to the server. 53e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * <p> 54e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * The corresponding {@link WebSocketListener} will continue to get messages until its 55e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * {@link WebSocketListener#onClose onClose()} method is called. 56e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * <p> 57e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * It is an error to call this method before calling close on an active writer. Calling this 58e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * method more than once has no effect. 59e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * 606c251e20f00c7574b217bd4351ac81666f574380Tobias Thierer * @throws IOException if unable to write the close message. Resources will still be freed. 61e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller * @throws IllegalStateException if already closed. 62e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller */ 63e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller void close(int code, String reason) throws IOException; 64e78f117bcbd6b57d783737107f445ef75ecb474aNeil Fuller} 65