https://github.com/d-a-v/libnowebsocket
native stream sockets between C and HTML5
https://github.com/d-a-v/libnowebsocket
c library posix-compatible websocket
Last synced: over 1 year ago
JSON representation
native stream sockets between C and HTML5
- Host: GitHub
- URL: https://github.com/d-a-v/libnowebsocket
- Owner: d-a-v
- Created: 2018-08-02T09:07:44.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2019-06-04T23:15:56.000Z (about 7 years ago)
- Last Synced: 2025-01-25T07:10:30.570Z (over 1 year ago)
- Topics: c, library, posix-compatible, websocket
- Language: C
- Homepage:
- Size: 294 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Name
nowsread, nowswrite, nowsclose — read, write, close a regular stream
socket when peer is a websocket.
PROLOG
This manual page will never be part of the POSIX Programmer’s Manual.
nowsread, nowswrite and nowsclose are designed to be similar to posix
read, write and close. Their purpose is to provide native sockets to
HTML5 web browsers. This is not yet allowed by standards, but the
other way around is not forbidden. These functions mimic posix’s
read, write and close and transparently emulate the websocket
protocol.
These functions allow their users to communicate with HTML5-enabled
web browsers using legacy knowledge and habits gained through years
of experience on network programming with TCP stream sockets and
POSIX API as a reference.
SYNOPSYS
#include
ssize_t nowsread (int sock, void* data, size_t len);
ssize_t nowswrite (int sock, const void* data, size_t len);
int nowsclose (int sock);
int nows_simulate_client (int sock);
DESCRIPTION
nowsread(3) is very similar to read(3POSIX) in its arguments,
behavior, return value, in blocking or non blocking mode, when sock
is a STREAMS socket in byte-stream mode (message-nondiscard and
message-discard modes are yet unconsidered). Same goes to nowswrite
(3) regarding write(3POSIX). The websocket protocol includes a
handshake process which sadly breaks symmetry between peers. As
generally HTML5 browsers act as websocket clients, nowsread(3) and
nowswrite(3) act by default as websocket server (even if the socket
sock is a SOCK_STREAM client). A call to nows_simulate_client(3)
prior to nowsread(3) and nowswrite(3) will switch this behavior.
Nothing beeing perfect, here is a list of specific differences or
relevant notices:
- blocking mode
read(3POSIX) blocks the caller until exactly len bytes are
received. Similarly nowsread(3) blocks the caller until at least
one byte is received, but due to the nature of the websocket
protocol, this does not guarantee that exactly len bytes are
received. The returned value indicates the amount of received
bytes in the data buffer. nowswrite(3) has however the same
behavior as write(3POSIX).
- non-blocking mode
Any value (greater than 0) given to len will follow read/write
(3POSIX) behavior.
- websocket specifics or restrictions
Underlying ping-pong facility is not implemented yet. Only text
buffers are sent or received. This is subject for improvements.
nowsclose(3) is similar to close(3POSIX).
nows_simulate_client(3) sets this side of the stream to act as a
websocket client.
RETURN VALUE
Please refer to read(3POSIX), write(3POSIX). To summarize, 0 always
indicates EOF, -1 an error and in that case errno is set. errno can
be set to EAGAIN even when in blocking mode. However in blocking mode
EAGAIN is never continuously returned and cannot induce an active
loop. Otherwise the returned value indicates the number of bytes sent
or received.
now_simulate_client(3) returns 0 on success, -1 on error and in that
case errno is set.
ERRORS
They are the same as with read(3POSIX), write(3POSIX) and close
(3POSIX). Additionnaly,
ENOMEM
can be returned in case of memory shortage.
EAGAIN
can be returned by nowsread(3) or nowswrite(3) in blocking mode
(however never continuously thus not inducing an active loop).
This is subject for improvements.
LICENSE
GPLv2 (due to sha1 embedded library - subject for changes)
AUTHOR
CNRS
https://redmine.laas.fr/projects/libnowebsocket