WebSocket

WebSocket: the main class in lwsock

Types

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

• 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

• 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 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& uri)

bind addresses that uri specify. this use getaddrinfo(3) for specified uri, then open sockets and bind addresses

• [in] uri: WebSocket URI
  uri ::= "ws://" host (":" port)? path ("?" query)?
  host ::= hostname | IPv4_dot_decimal | IPv6_colon_hex

  for example
  ws://aa.bb.cc.dd	aa.bb.cc.dd is a host name and a domain name. This pattern is that use each IPv4 and IPv6.
  ws://aa.bb.cc.dd:8080
  ws://10.20.30.40	This pattern is that use only IPv4.
  ws://10.20.30.40:8080
  ws://0.0.0.0	This pattern is that use IPv4 any address.
  ws://127.0.0.1	This pattern is that use only IPv4 loopback address.
  ws://2001::40	This pattern is that use only IPv6.
  ws://[2001::300:40]:8080
  ws://::0	This pattern is that use IPv6 any address.
  ws://::1	This pattern is that use only IPv6 loopback address.

• return: reference of *this

• exceptions: CRegexException, GetaddrinfoException, LwsockExrepss

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

bind address that uri specify. if you use hostname for uri and want to specify IPv4 or IPv6, you should use this method.

• [in] uri: WebSocket URI
• [in] af: AF_INET or AF_INET6 if you want to specify that use IPv4 or IPv6 then you set this param.
• return: reference of *this
• exceptions: CRegexException, GetaddrinfoException, LwsockExrepss

WebSocket& WebSocket::listen(int backlog)

listen(2) each binded sockfds.

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

WebSocket WebSocket::accept()

accept(2) socket

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

WebSocket WebSocket::accept(Sockaddr& remote)

accept(2) socket

• [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()

receive a opening handshake request message. blocking recevie

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

handshake_t WebSocket::recv_req(const Timespec& timeout)

receive a opening handshake request message with timeout. blocking recevie.
recv_req internally calls recv(2) multiple times. timeout is effective that times.

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

std::string WebSocket::send_res()

send an opening handshake response message.
send default headers. they are Host, Upgrade, Connection, Sec-WebSocket-Key and Sec-WebSocket-Accept.

• return: sent a message
• exceptions: SystemErrorException

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

send an opening handshake response message.
if you want to send that add other headers to default headers, then use this api.

• [in] otherheaders: other headers
• return: sent a message
• exceptions: SystemErrorException

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

send an opening handshake response message that is set completely manual.

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

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

connect to the WebSocket server

• [in] uri: WebSocket URI
  uri ::= "ws://" host (":" port)? path ("?" query)?
  host ::= hostname | IPv4_dot_decimal | IPv6_colon_hex

  for example
  ws://aa.bb.cc.dd	This pattern is that try IPv4 and IPv6.
  ws://aa.bb.cc.dd:8080
  ws://10.20.30.40	This pattern is that try only IPv4.
  ws://10.20.30.40:8080
  ws://127.0.0.1	This pattern is that try only IPv4 loopback address.
  ws://2001::40	This pattern is that try only IPv6.
  ws://[2001::300:40]:8080
  ws://::1	This pattern is that try only IPv6 loopback address.

• 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

• [in] uri: WebSocket URI
  uri ::= "ws://" host (":" port)? path ("?" query)?
  host ::= hostname | IPv4_dot_decimal | IPv6_colon_hex

  for example
  ws://aa.bb.cc.dd	This pattern is that try IPv4 and IPv6.
  ws://aa.bb.cc.dd:8080
  ws://10.20.30.40	This pattern is that try only IPv4.
  ws://10.20.30.40:8080
  ws://127.0.0.1	This pattern is that try only IPv4 loopback address.
  ws://2001::40	This pattern is that try only IPv6.
  ws://[2001::300:40]:8080
  ws://::1	This pattern is that try only IPv6 loopback address.

• [in] timeout: specify timeout. Timespec instance

• return: reference of *this

• exception: CRegexException, GetaddrinfoException, LwsockExrepss, SystemErrorException

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

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

• [in] uri: WebSocket URI.

  for example
  ws://aa.bb.cc.dd
  ws://aa.bb.cc.dd:8080

• [in] af: AF_INET or AF_INET6
  if you want to specify that use IPv4 or IPv6 then you set this param.

• [in] timeout: specify timeout. Timespec instance

• exception: CRegexException, GetaddrinfoException, LwsockExrepss, SystemErrorException

std::string WebSocket::send_req()

send an opening handshake request message.

• return: sent a message

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

send an opening handshake request message with other headers.

• [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.

• 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)

receive an opening handshake response message 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

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

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

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

receive a websocket text message from the remote

• return: pair
  • first: a received string message
  • second: status code when recieved a CLOSE

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

receive a websocket text message from the remote with timeout

• [in] timeout: specify timeout. Timespec instance
• return: pair
  • first: a received string message
  • second: status code when recieved a CLOSE

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 recieved a CLOSE

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

receive a websocket binary message from the remote with timeout

• [in] timeout: specify timeout. Timespec instance
• return: pair
  • first: a received binary message
  • second: status code when recieved a CLOSE

ssize_t WebSocket::send_ping()

send a PING frame

• return: sent data size. bytes

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

send a PING frame with a text app data.

• [in]: app_data: app data
• return: sent data size. bytes

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

send a PING frame with a binary app data.

• [in]: app_data: app data
• return: sent data size. bytes

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

send a PING frame with a binary app data.

• [in]: app_data: app data
• return: sent data size. bytes

ssize_t WebSocket::send_pong()

send a PONG frame

• return: sent data size. bytes

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

send a PONG frame with a text app data.

• [in]: app_data: app data
• return: sent data size. bytes

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

send a PONG frame with a binary app data.

• [in]: app_data: app data
• return: sent data size. bytes

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

send a PONG frame with a binary app data.

• [in]: app_data: app data
• return: sent data size. bytes

void WebSocket::send_close(const uint16_t status_code)

send CLOSE frame, then wait a response (maybe CLOSE frame) or wait closing socket from the remote

• [in] status_code: status code

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

send CLOSE frame. send CLOSE frame, then wait a response (maybe CLOSE frame) or wait closing socket from the remote.

• [in] status_code: status code
• [in] reason: reason string

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

send CLOSE frame with timeout. send CLOSE frame, then wait a response (maybe CLOSE frame) or wait closing socket from the remote.

• [in] status_code: status code
• [in] reason: 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: path (e.g. "/path/a/b/c")

std::string WebSocket::query()

get the request query parameters.

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

std::string WebSocket::origin()

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

• return: a value of Origin header.

int WebSocket::sfd_ref()

get the raw sockfd that connected or accepted. you must not close socket.

• return: raw sockfd

int WebSocket::sfd_mv()

get the raw sockfd that connected or accepted. you must close socket yourself.

• return: raw sockfd

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

get refernce binded sockfds

• 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 ostream for WebSocket logs.

• [in] lvl: Log::Level

Log::Level WebSocket::loglevel()

get WebSocekt log level

• return: Log::Level