Phoenix.SocketClient.Channel behaviour (phoenix_socket_client v0.8.1)

View Source

A process for interacting with a Phoenix Channel.

Summary

Types

state()

The state of the channel.

Callbacks

handle_close(reason, state)

Callback invoked when the channel process is terminating.

handle_join_reply(status, payload, state)

Callback invoked when the server replies to a channel join request.

handle_message(event, payload, state)

Callback for handling incoming messages.

Functions

join(sup_pid, topic, params \\ %{}, timeout \\ 5000)

Join a channel topic through a socket with optional params

leave(pid)

Leave the channel topic and stop the channel

push(pid, event, payload, timeout \\ 5000)

Push a message to the server and wait for a a response or timeout

push_async(pid, event, payload)

Push a message to the server and do not wait for a response

stop(pid)

Stops the channel process.

Types

state()

@type state() :: %Phoenix.SocketClient.Channel.State{
  caller: term(),
  hooks: term(),
  join_ref: term(),
  join_start_time: term(),
  leave_start_time: term(),
  params: term(),
  pushes: term(),
  registry_name: term(),
  socket_pid: term(),
  sup_pid: term(),
  topic: term()
}

The state of the channel.

Callbacks

handle_close(reason, state)

(optional) 
@callback handle_close(reason :: term(), state :: state()) ::
  {:noreply, new_state :: state()}

Callback invoked when the channel process is terminating.

reason is the termination reason (e.g. :normal, :shutdown, or an error).

handle_join_reply(status, payload, state)

(optional) 
@callback handle_join_reply(status :: atom(), payload :: map(), state :: state()) ::
  {:noreply, new_state :: state()}

Callback invoked when the server replies to a channel join request.

status is :ok on successful join or :error on failure. payload contains the server's response payload.

handle_message(event, payload, state)

@callback handle_message(event :: String.t(), payload :: map(), state :: state()) ::
  {:noreply, new_state :: state()}

Callback for handling incoming messages.

Functions

join(sup_pid, topic, params \\ %{}, timeout \\ 5000)

@spec join(pid() | atom(), binary(), map(), non_neg_integer()) ::
  {:ok, any(), pid()}
  | {:error, :socket_not_connected}
  | {:error, :timeout}
  | {:error, {:already_joined, pid()}}
  | {:error, any()}

Join a channel topic through a socket with optional params

A socket can only join a topic once. If the socket you pass already has a channel connection for the supplied topic, you will receive an error {:error, {:already_joined, pid}} with the channel pid of the process joined to that topic through that socket. If you require to join the same topic with multiple processes, you will need to start a new socket process for each channel.

Calling join will link the caller to the channel process.

leave(pid)

@spec leave(pid()) :: :ok

Leave the channel topic and stop the channel

push(pid, event, payload, timeout \\ 5000)

@spec push(pid(), binary(), map(), non_neg_integer()) ::
  {:ok, any()} | {:error, any() | :timeout}

Push a message to the server and wait for a a response or timeout

The server must be configured to return {:reply, _, socket} otherwise, the call will timeout.

push_async(pid, event, payload)

@spec push_async(pid(), binary(), map()) :: :ok

Push a message to the server and do not wait for a response

stop(pid)

@spec stop(pid()) :: :ok

Stops the channel process.