WebSockex v0.1.1 WebSockex.Client behaviour

A client handles negotiating the connection, then sending frames, receiving frames, closing, and reconnecting that connection.

A simple client implementation would be:

defmodule WsClient do
  use WebSockex.Client

  def start_link(state) do
    WebSockex.Client.start_link(__MODULE__, state)
  end

  def handle_frame({:text, msg}, state) do
    IO.puts "Received a message: #{msg}"
    {:ok, state}
  end
end

Summary

Types

close_code()

An integer between 1000 and 4999 that specifies the reason for closing the connection

close_frame()

The frame sent when the negotiating a connection closure

close_reason()

The reason given and sent to the server when locally closing a connection

frame()

option()

options()

Functions

cast(client, message)

Asynchronously sends a message to a client that is handled by handle_cast/2

send_frame(pid, frame)

Queue a frame to be sent asynchronously

start_link(url, module, state, opts \\ [])

Starts a WebSockex.Client process linked to the current process

Callbacks

code_change(old_vsn, state, extra)

Invoked when a new version the module is loaded during runtime

handle_cast(msg, state)

Invoked to handle asynchronous cast/2 messages

handle_disconnect(close_reason, state)

Invoked when the WebSocket disconnects from the server

handle_frame(frame, state)

Invoked on the reception of a frame on the socket

handle_info(msg, state)

Invoked to handle all other non-WebSocket messages

handle_ping(arg0, state)

Invoked when the Websocket receives a ping frame

handle_pong(arg0, state)

Invoked when the Websocket receives a pong frame

init(args, arg1)

Invoked after connection is established

terminate(close_reason, state)

Invoked when the process is terminating

Types

close_code()

close_code() :: integer

An integer between 1000 and 4999 that specifies the reason for closing the connection.

close_frame()

close_frame() :: {close_code, message :: binary}

The frame sent when the negotiating a connection closure.

close_reason()

close_reason ::
  {:remote | :local, :normal} |
  {:remote | :local, :normal | close_code, close_frame} |
  {:error, term}

The reason given and sent to the server when locally closing a connection.

A :normal reason is the same as a 1000 reason.

frame()

frame ::
  {:ping | :ping, nil | message :: binary} |
  {:text | :binary, message :: binary}

option()

option() :: WebSockex.Conn.connection_option

options()

options() :: [option]

Functions

cast(client, message)

cast(pid, term) :: :ok

Asynchronously sends a message to a client that is handled by handle_cast/2.

send_frame(pid, frame)

send_frame(pid, frame) ::
  :ok |
  {:error, WebSockex.FrameEncodeError.t}

Queue a frame to be sent asynchronously.

start_link(url, module, state, opts \\ [])

start_link(String.t, module, term, options) ::
  {:ok, pid} |
  {:error, term}

Starts a WebSockex.Client process linked to the current process.

Options

:extra_headers - defines other headers to be send in the opening request.
:insecure - Determines whether to verify the peer in a SSL connection. SSL peer verification is currenctly broken and only works in certain cases in which the :cacerts are also provided. Sorry. Defaults to true.
:cacerts - The CA certifications for use in an secure connection when the :insecure option is false (has no effect when :insecure is true). These certifications need a list of decoded binaries. See the Erlang :public_key module for more information.

Callbacks

code_change(old_vsn, state, extra) (optional)

code_change(old_vsn :: term | {:down, term}, state :: term, extra :: term) ::
  {:ok, new_state :: term} |
  {:error, reason :: term}

Invoked when a new version the module is loaded during runtime.

handle_cast(msg, state)

handle_cast(msg :: term, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked to handle asynchronous cast/2 messages.

handle_disconnect(close_reason, state) (optional)

handle_disconnect(close_reason, state :: term) ::
  {:ok, state} |
  {:reconnect, state} when state: term

Invoked when the WebSocket disconnects from the server.

handle_frame(frame, state)

handle_frame(frame, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked on the reception of a frame on the socket.

The control frames have possible payloads, when they don’t have a payload then the frame will have nil as the payload. e.g. {:ping, nil}

handle_info(msg, state)

handle_info(msg :: term, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked to handle all other non-WebSocket messages.

handle_ping(arg0, state) (optional)

handle_ping(:ping | {:ping, binary}, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked when the Websocket receives a ping frame

handle_pong(arg0, state) (optional)

handle_pong(:pong | {:pong, binary}, state :: term) ::
  {:ok, new_state} |
  {:reply, frame, new_state} |
  {:close, new_state} |
  {:close, close_frame, new_state} when new_state: term

Invoked when the Websocket receives a pong frame.

init(args, arg1)

init(args :: any, WebSockex.Conn.t) :: {:ok, state :: term}

Invoked after connection is established.

terminate(close_reason, state) (optional)

terminate(close_reason, state :: term) :: any

Invoked when the process is terminating.