• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# lws minimal dbus ws proxy
2
3This is an application which presents a DBUS server on one side, and a
4websocket client proxy on the other.
5
6You connect to it over DBUS, send a Connect method on its interface giving
7a URI and a ws subprotocol name.
8
9It replies with a string "Connecting" if all is well.
10
11Connection progress (including close) is then provided using type 7 messages
12sent back to the dbus client.
13
14Payload from the ws connection is provided using type 6 messages sent back to
15the dbus client.
16
17## build
18
19Using libdbus requires additional non-default include paths setting, same as
20is necessary for lws build described in ./lib/roles/dbus/README.md
21
22CMake can guess one path and the library name usually, see the README above
23for details of how to override for custom libdbus and cross build.
24
25Fedora example:
26```
27$ cmake .. -DLWS_DBUS_INCLUDE2="/usr/lib64/dbus-1.0/include"
28$ make
29```
30
31Ubuntu example:
32```
33$ cmake .. -DLWS_DBUS_INCLUDE2="/usr/lib/x86_64-linux-gnu/dbus-1.0/include"
34$ make
35```
36
37## Configuration
38
39The dbus-ws-proxy server tries to register its actual bus name with the SYSTEM
40bus in DBUS.  If it fails, eg because of insufficient permissions on the user,
41then it continues without that and starts its own daemon normally.
42
43The main dbus daemon must be told how to accept these registrations if that's
44what you want.  A config file is provided that tells dbus to allow the
45well-known busname for this daemon to be registered, but only by root.
46
47```
48$ sudo cp org.libwebsockets.wsclientproxy.conf /etc/dbus-1/system.d
49$ sudo systemctl restart dbus
50```
51
52## usage
53
54Run the dbus-ws-proxy server, then start lws-minimal-dbus-ws-proxy-testclient in
55another terminal.
56
57This test app sends a random line drawing message to the mirror example on
58https://libwebsockets.org/testserver every couple of seconds, and displays
59any received messages (such as its own sends mirrored back, or anything
60drawn in the canvas in a browser).
61
62```
63 $ sudo ./lws-minimal-dbus-ws-proxy-testclient
64[2018/10/07 10:05:29:2084] USER: LWS minimal DBUS ws proxy testclient
65[2018/10/07 10:05:29:2345] NOTICE: Creating Vhost 'default' port 0, 1 protocols, IPv6 off
66[2018/10/07 10:05:29:2424] USER: create_dbus_client_conn: connecting to 'unix:abstract=org.libwebsockets.wsclientproxy'
67[2018/10/07 10:05:29:2997] NOTICE: state_transition: 0x5679720: from state 0 -> 1
68[2018/10/07 10:05:29:2999] NOTICE: create_dbus_client_conn: created OK
69[2018/10/07 10:05:29:3232] USER: remote_method_call: requesting proxy connection wss://libwebsockets.org/ lws-mirror-protocol
70[2018/10/07 10:05:29:3450] NOTICE: state_transition: 0x5679720: from state 1 -> 2
71[2018/10/07 10:05:29:5972] USER: pending_call_notify: received 'Connecting'
72[2018/10/07 10:05:31:3387] NOTICE: state_transition: 0x5679720: from state 2 -> 3
73[2018/10/07 10:05:33:6672] USER: filter: Received 'd #B0DC51 115 177 166 283;'
74[2018/10/07 10:05:35:9723] USER: filter: Received 'd #E87CCD 9 192 106 235;'
75[2018/10/07 10:05:38:2784] USER: filter: Received 'd #E2A9E3 379 290 427 62;'
76[2018/10/07 10:05:39:5833] USER: filter: Received 'd #B127F8 52 126 60 226;'
77[2018/10/07 10:05:41:8908] USER: filter: Received 'd #0E0F76 429 267 8 11;'
78...
79```
80
81## ws proxy DBUS details
82
83### Fixed details
84
85Item|Value
86---|---
87Address|unix:abstract=org.libwebsockets.wsclientproxy
88Interface|org.libwebsockets.wsclientproxy
89Bus Name|org.libwebsockets.wsclientproxy
90Object path|/org/libwebsockets/wsclientproxy
91
92### Interface Methods
93
94Method|Arguments|Returns
95---|---|---
96Connect|s: ws URI, s: ws subprotocol name|"Bad Uri", "Connecting" or "Failed"
97Send|s: payload|Empty message if no problem, or error message
98
99When Connecting, the actual connection happens asynchronously if the initial
100connection attempt doesn't fail immediately.  If it's continuing in the
101background, the reply will have been "Connecting".
102
103### Signals
104
105Signal Name|Argument|Meaning
106---|---|---
107Receive|s: payload|Received data from the ws link
108Status|s: status|See table below
109
110Status String|Meaning
111---|---
112"ws client connection error"|The ws connection attempt ended with a fatal error
113"ws client connection established"|The ws connection attempt succeeded
114"ws client connection closed"|The ws connection has closed
115
116