Skip to content

WebSocket

Jump to bottom
hfuj13 edited this page Sep 10, 2022 · 71 revisions

WebSocket: the main class in lwsock

Types

Mode

enum class Mode { NONE = -1, CLIENT = 0, SERVER }

headers_t

using headers_t = std::vector<std::pair<std::string, std::string>>
Type representing each header after the 2nd line of the opening handshake.
std::vector has the following structure std::pair as its values.

  • first: Header name
  • second: Value

handshake_t

using handshake_t = std::pair<std::string, headers_t>
Opening handshake type

  • first: 1st line. i.e. the request line or the status line. it does not include "\r\n"
  • second: headers_t

Methods

WebSocket::WebSocket()

Default constructor

WebSocket::WebSocket(WebSocket&& ws) noexcept

Move constructor

WebSocket::WebSocket(Mode mode)

Constructor that is the Mode specify

  • [in] mode: Specify WebSocket::Mode

WebSocket::~WebSocket

Destructor

WebSocket& WebSocket::operator=(WebSocket&& rhs) noexcept

  • return: Reference of *this

WebSocket& WebSocket::bind(const std::string& ws_addr_port)

This API will bind(2) with the specified address and port.
This API use getaddrinfo(3). And then sockets(2) and bind(2).

  • [in] ws_addr_port: WebSocket address and port
  • return: Reference of *this
  • exceptions: CRegexException, GetaddrinfoException, LwsockExrepss

WebSocket& WebSocket::bind(const std::string& ws_addr_port, int af)

lwsock::WebSocket::bind() with the address family.
If you want to explicitly specify IPv4 or IPv6 while using hostname, you should use this API.

  • [in] ws_addr_port: WebSocket address and port
  • [in] af: AF_INET or AF_INET6
  • return: Reference of *this
  • exceptions: CRegexException, GetaddrinfoException, LwsockExrepss

WebSocket& WebSocket::listen(int backlog)

This API listen(2) for each sock fds that is binded. You use it in server mode.

  • [in] backlog: listen(2)'s backlog
  • return: Reference of *this
  • exceptions: SystemErrorException

WebSocket WebSocket::accept()

This API accept(2) a socket. You use it in server mode.
This is a blocking API.

  • return: A new WebSocket instance
  • exceptions: LwsockException, SystemErrorException

WebSocket WebSocket::accept(Sockaddr& remote)

This API accept(2) a socket. You use it in server mode.
This is a blocking API.
This API stores the Sockaddr information of the connecting client side in remote.

  • [out] remote: This is set in with the address of the peer socket
  • return: A new WebSocket instance
  • exceptions: LwsockException, SystemErrorException

handshake_t WebSocket::recv_req()

This API receive a opening handshake request message.
This is a blocking API.
It calls recv(2) multiple times internally until it receives all the header parts.

  • return: Received handshake message parameters
  • exceptions: CRegexException, LwsockExrepss, SystemErrorException

handshake_t WebSocket::recv_req(const Timespec& timeout)

This API is recv_req() with timeout.
This is a blocking API.
This API will exit blocking and throw an exception (SystemErrorException) after the specified time has elapsed.
The timeout is checked each time for each recv(2).
For example, if a timeout of 6000 msec is specified, recv(2) is called with a timeout of 6000 msec each time.

  • [in] timeout: Specify timeout. Timespec instance
  • return: Received handshake message parameters
  • exceptions: CRegexException, LwsockExrepss, SystemErrorException

std::string WebSocket::send_res()

This API sends an opening handshake response message with default headers.
Default Headers are Upgrade, Connection and Sec-WebSocket-Accept.

  • return: Sent messages
  • exceptions: SystemErrorException

std::string WebSocket::send_res(const headers_t& otherheaders)

Use this API when you want to send other headers in addition to the default header.

  • [in] otherheaders: Other headers
  • return: Sent messages
  • exceptions: SystemErrorException

std::string WebSocket::send_res_manually(const handshake_t& handshake)

Use this API when you want to construct the Opening Handshake response message completely manually.

  • [in] handshake: Handshake message parameters
  • return: Sent messages
  • exceptions: SystemErrorException

WebSocket& WebSocket::connect(const std::string& uri)

Connect to the WebSocket server.
This is a blocking API.

  • [in] uri: WebSocket URI
  • return: Reference of *this
  • exception: CRegexException, GetaddrinfoException, LwsockExrepss, SystemErrorException

WebSocket& WebSocket::connect(const std::string& uri, const Timespec& timeout)

Connect to the server with timeout.

WebSocket& WebSocket::connect(const std::string& uri, int af, const Timespec& timeout)

Connect to the server with timeout.
If you use hostname for uri and want to specify IPv4 or IPv6, you use this method.

std::string WebSocket::send_req()

Send a default headers opening handshake request message.
Default headers are Host, Upgrade, Connection, Sec-WebSocket-Key and Sec-WebSocket-Accept.

  • return: Sent a message

std::string WebSocket::send_req(const headers_t& otherheaders)

Use this API when sending other headers in addition to the default headers in the opening handshake request message.

  • [in] otherheaders: Other headers
  • return: Sent a message

std::string WebSocket::send_req_manually(const handshake_t& handshake)

Send an opening handshake request message that is set completely manual.

  • [in] handshake: handshake message parameters
  • return: sent a message

std::pair<handshake_t, int32_t> WebSocket::recv_res()

Receive an opening handshake response message.
This is a blocking API.

  • return: pair
    • first: received handshake message parameters
    • second: status code of the 1st line

std::pair<handshake_t, int32_t> WebSocket::recv_res(const Timespec& timeout)

This API is recv_res() with timeout.

  • [in] timeout: Specify timeout. Timespec instance
  • return: pair
    • first: Received handshake message parameters
    • second: Status code of the 1st line

ssize_t WebSocket::send_msg_txt(const std::string& payload_data)

Send a websocket text message to the remote

  • [in] payload_data: WebSocket payload data
  • return: Sent data size. Bytes unit

ssize_t WebSocket::send_msg_bin(const std::vector<uint8_t>& payload_data)

Send a websocket binary message to the remote

  • [in] payload_data: WebSocket payload data
  • return: Sent data size. Bytes unit

template<size_t N> ssize_t WebSocket::send_msg_bin(const std::array<uint8_t, N>& payload_data)

Send a websocket binary message to the remote

  • [in] payload_data: WebSocket payload data
  • return: sent data size. Bytes unit

std::pair<std::string, int32_t> WebSocket::recv_msg_txt()

Receive a websocket text message from the remote.
This is a blocking API.

  • return: pair
    • first: A received string message
    • second: Status code when a CLOSE frame (opcode is 0x8) is received

std::pair<std::string, int32_t> WebSocket::recv_msg_txt(const Timespec& timeout)

This API is recv_msg_txt() with timeout.

  • [in] timeout: Specify timeout. Timespec instance
  • return: pair
    • first: A received string message
    • second: Status code when a Close control frame (opcode is 0x8) is received

std::pair<std::vector<uint8_t>, int32_t> WebSocket::recv_msg_bin()

Receive a WebSocket binary message from the remote.

  • return: pair
    • first: A received binary message
    • second: Status code when a Close control frame (opcode is 0x8) is received

std::pair<std::vector<uint8_t>, int32_t> WebSocket::recv_msg_bin(const Timespec& timeout)

This API is recv_msg_bin() with timeout.

  • [in] timeout: specify timeout. Timespec instance
  • return: pair
    • first: A received binary message
    • second: Status code when a Close control frame (opcode is 0x8) is received

ssize_t WebSocket::send_ping()

Send a PING frame

  • return: Sent data size. Bytes unit

ssize_t WebSocket::send_ping(const std::string& app_data)

Send a Ping control frame with a text App data.

  • [in]: app_data: An App data
  • return: Sent data size. Bytes unit

ssize_t WebSocket::send_ping(const std::vector<uint8_t>& app_data)

Send a Ping control frame with a binary App data.

  • [in]: app_data: An App data
  • return: Sent data size. Bytes unit

template<size_t N> ssize_t WebSocket::send_ping(const std::array<uint8_t, N>& app_data)

Send a Ping control frame with a binary App data.

  • [in]: app_data: An App data
  • return: Sent data size. Bytes unit

ssize_t WebSocket::send_pong()

Send a Pong control frame

  • return: Sent data size. Bytes unit

ssize_t WebSocket::send_pong(const std::string& app_data)

Send a Pong control frame with a text App data.

  • [in]: app_data: An App data
  • return: Sent data size. Bytes unit

ssize_t WebSocket::send_pong(const std::vector<uint8_t>& app_data)

Send a Pong control frame with a binary App data.

  • [in]: app_data: An App data
  • return: Sent data size. Bytes unit

template<size_t N> ssize_t WebSocket::send_pong(const std::array<uint8_t, N>& app_data)

Send a Ping control frame with a binary App data.

  • [in]: app_data: An App data
  • return: Sent data size. Bytes unit

void WebSocket::send_close(const uint16_t status_code)

Send Close control frame, then wait a response (maybe Close control frame) or wait closing socket from the remote.
This is a blocking API.

  • [in] status_code: Status code

void WebSocket::send_close(const uint16_t status_code, const std::string& reason)

This API is send_close() with a reason string

  • [in] status_code: Status code
  • [in] reason: A reason string

void WebSocket::send_close(const uint16_t status_code, const std::string& reason, const Timespec& timeout)

This API is send_close() with a reason string and timeout

  • [in] status_code: Status code
  • [in] reason: A reason string
  • [in] timeout: Specify timeout. Timespec instance

Sockaddr WebSocket::remote()

Get Sockaddr about the remote

  • return: Sockaddr instance

std::string WebSocket::path()

Get the request path.

  • return: The request path (e.g. "/path/a/b/c")

std::string WebSocket::query()

Get the request query.

  • return: The request query (e.g. "?aa=123&bb=xyz")

std::string WebSocket::origin()

Get the Origin header's value in the request headers, if the client is a web browser.

  • return: A value of Origin header.

int WebSocket::sfd_ref()

Get the raw socket fd that connected or accepted. You must not close(2) this socket fd directly.

  • return: the raw socket fd

int WebSocket::sfd_mv()

Get the raw socket fd that connected or accepted. You must close(2) this socket fd yourself.

  • return: the raw socket fd

const std::vector& WebSocket::bind_sfds()

Get refernce binded socket fds

  • return: reference of binded sockfds

WebSocket& WebSocket::ostream4log(std::ostream& ost)

Set ostream for lwsock::WebSocket logs.

  • [in] ost: ostream reference.

WebSocket& WebSocket::loglevel(Log::Level lvl)

Set the log level for lwsock::WebSocket logs.

  • [in] lvl: Log::Level

Log::Level WebSocket::loglevel()

Get the lwsock::WebSocekt log level

  • return: Log::Level
Clone this wiki locally