atomvm_gleam - v0.7.0-beta.0

atomvm_gleam/emscripten_websocket

Browser WebSocket NIF wrappers for AtomVM’s emscripten-only websocket module (avm_emscripten).

Emscripten / browser only. This is distinct from atomvm_gleam/websocket, which wraps the ESP-IDF atomvm_websocket_client port driver.

Upstream Erlang module is websocket (called via FFI); the Gleam path is emscripten_websocket to avoid clashing with the ESP client module.

Source: libs/avm_emscripten/src/websocket.erl. Docs: Module websocket.

Inbound owner messages

The controlling process receives these mailbox messages (from the NIF):

Check atomvm.platform() == Emscripten (or call is_supported) before using this module on mixed-target builds.

Types

Error

</>

Errors from the emscripten websocket NIF.

pub type Error {
  Failed
  NotSupported
  Badarg
  Timeout
  NotOwner
  SocketClosed
  Other(String)
}

Constructors 

  • Failed
  • NotSupported
  • Badarg
  • Timeout
  • NotOwner

    Caller is not the current controlling process.

  • SocketClosed

    Socket is already closed ({error, closed} upstream).

  • Other(String)

ReadyState

</>

Connection ready-state from ready_state.

pub type ReadyState {
  Connecting
  Open
  Closing
  Closed
}

Constructors 

  • Connecting
  • Open
  • Closing
  • Closed

Websocket

</>

Opaque browser WebSocket resource (websocket()).

pub type Websocket

Values

buffered_amount

</> 
pub fn buffered_amount(ws: Websocket) -> Result(Int, Error)

Bytes queued with send but not yet transmitted.

See websocket:buffered_amount/1.

close

</> 
pub fn close(ws: Websocket) -> Result(Nil, Error)

Close with status code 1000 (normal) and an empty reason.

See websocket:close/1.

close2

</> 
pub fn close2(
  ws: Websocket,
  status_code: Int,
) -> Result(Nil, Error)

Close with the given status code and an empty reason.

See websocket:close/2.

close3

</> 
pub fn close3(
  ws: Websocket,
  status_code: Int,
  reason: String,
) -> Result(Nil, Error)

Close with status code and reason string.

See websocket:close/3.

controlling_process

</> 
pub fn controlling_process(
  ws: Websocket,
  owner: process.Pid,
) -> Result(Nil, Error)

Transfer ownership to owner. Must be called by the current owner.

See websocket:controlling_process/2.

error_to_string

</> 
pub fn error_to_string(error: Error) -> String

Format an Error for logging.

extensions

</> 
pub fn extensions(ws: Websocket) -> Result(String, Error)

Extensions selected by the server, if any.

See websocket:extensions/1.

is_supported

</> 
pub fn is_supported() -> Bool

true if browser WebSockets are available in this environment.

See websocket:is_supported/0.

new

</> 
pub fn new(url: String) -> Result(Websocket, Error)

Open a WebSocket to url with default protocols and self() as owner.

Equivalent to new3 with [] protocols and the calling process.

See websocket:new/1.

new2

</> 
pub fn new2(
  url: String,
  protocols: List(String),
) -> Result(Websocket, Error)

Open a WebSocket to url negotiating protocols, with self() as owner.

See websocket:new/2.

new3

</> 
pub fn new3(
  url: String,
  protocols: List(String),
  owner: process.Pid,
) -> Result(Websocket, Error)

Open a WebSocket to url with protocols and explicit owner process.

See websocket:new/3.

protocol

</> 
pub fn protocol(ws: Websocket) -> Result(String, Error)

Subprotocol selected by the server, if any.

See websocket:protocol/1.

ready_state

</> 
pub fn ready_state(ws: Websocket) -> Result(ReadyState, Error)

Current connection ready-state.

See websocket:ready_state/1.

send_binary

</> 
pub fn send_binary(
  ws: Websocket,
  data: BitArray,
) -> Result(Nil, Error)

Send a binary frame.

See websocket:send_binary/2.

send_utf8

</> 
pub fn send_utf8(
  ws: Websocket,
  text: String,
) -> Result(Nil, Error)

Send a UTF-8 text frame.

See websocket:send_utf8/2.

url

</> 
pub fn url(ws: Websocket) -> Result(String, Error)

URL used to open the socket.

See websocket:url/1.

✨ Search Document