com.undefinedlabs.scope.deps.okhttp3.WebSocket Maven / Gradle / Ivy

package com.undefinedlabs.scope.deps.okhttp3;

import com.undefinedlabs.scope.deps.okio.ByteString;

public interface WebSocket {
    /** Returns the original request that initiated this web socket. */
    Request request();

    /**
     * Returns the size in bytes of all messages enqueued to be transmitted to the server. This
     * doesn't include framing overhead. It also doesn't include any bytes buffered by the operating
     * system or network intermediaries. This method returns 0 if no messages are waiting
     * in the queue. If may return a nonzero value after the web socket has been canceled; this
     * indicates that enqueued messages were not transmitted.
     */
    long queueSize();

    /**
     * Attempts to enqueue {@code text} to be UTF-8 encoded and sent as a the data of a text (type
     * {@code 0x1}) message.
     *
     * This method returns true if the message was enqueued. Messages that would overflow the
     * outgoing message buffer will be rejected and trigger a {@linkplain #close graceful shutdown} of
     * this web socket. This method returns false in that case, and in any other case where this
     * web socket is closing, closed, or canceled.
     *
     * 
This method returns immediately.
     */
    boolean send(String text);

    /**
     * Attempts to enqueue {@code bytes} to be sent as a the data of a binary (type {@code 0x2})
     * message.
     *
     * 
This method returns true if the message was enqueued. Messages that would overflow the
     * outgoing message buffer will be rejected and trigger a {@linkplain #close graceful shutdown} of
     * this web socket. This method returns false in that case, and in any other case where this
     * web socket is closing, closed, or canceled.
     *
     * 
This method returns immediately.
     */
    boolean send(ByteString bytes);

    /**
     * Attempts to initiate a graceful shutdown of this web socket. Any already-enqueued messages will
     * be transmitted before the close message is sent but subsequent calls to {@link #send} will
     * return false and their messages will not be enqueued.
     *
     * This returns true if a graceful shutdown was initiated by this call. It returns false and if
     * a graceful shutdown was already underway or if the web socket is already closed or canceled.
     *
     * @param code Status code as defined by Section 7.4 of RFC 6455 or {@code 0}.
     * @param reason Reason for shutting down or {@code null}.
     */
    boolean close(int code, String reason);

    /**
     * Immediately and violently release resources held by this web socket, discarding any enqueued
     * messages. This does nothing if the web socket has already been closed or canceled.
     */
    void cancel();

    interface Factory {
        WebSocket newWebSocket(Request request, WebSocketListener listener);
    }
}