xref: /openbmc/qemu/include/io/channel-websock.h (revision 8680d6e3)
1 /*
2  * QEMU I/O channels driver websockets
3  *
4  * Copyright (c) 2015 Red Hat, Inc.
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18  *
19  */
20 
21 #ifndef QIO_CHANNEL_WEBSOCK_H
22 #define QIO_CHANNEL_WEBSOCK_H
23 
24 #include "io/channel.h"
25 #include "qemu/buffer.h"
26 #include "io/task.h"
27 #include "qom/object.h"
28 
29 #define TYPE_QIO_CHANNEL_WEBSOCK "qio-channel-websock"
30 OBJECT_DECLARE_SIMPLE_TYPE(QIOChannelWebsock, QIO_CHANNEL_WEBSOCK)
31 
32 typedef union QIOChannelWebsockMask QIOChannelWebsockMask;
33 
34 union QIOChannelWebsockMask {
35     char c[4];
36     uint32_t u;
37 };
38 
39 /**
40  * QIOChannelWebsock
41  *
42  * The QIOChannelWebsock class provides a channel wrapper which
43  * can transparently run the HTTP websockets protocol. This is
44  * usually used over a TCP socket, but there is actually no
45  * technical restriction on which type of master channel is
46  * used as the transport.
47  *
48  * This channel object is currently only capable of running as
49  * a websocket server and is a pretty crude implementation
50  * of it, not supporting the full websockets protocol feature
51  * set. It is sufficient to use with a simple websockets
52  * client for encapsulating VNC for noVNC in-browser client.
53  */
54 
55 struct QIOChannelWebsock {
56     QIOChannel parent;
57     QIOChannel *master;
58     Buffer encinput;
59     Buffer encoutput;
60     Buffer rawinput;
61     size_t payload_remain;
62     size_t pong_remain;
63     QIOChannelWebsockMask mask;
64     guint io_tag;
65     Error *io_err;
66     gboolean io_eof;
67     uint8_t opcode;
68 };
69 
70 /**
71  * qio_channel_websock_new_server:
72  * @master: the underlying channel object
73  *
74  * Create a new websockets channel that runs the server
75  * side of the protocol.
76  *
77  * After creating the channel, it is mandatory to call
78  * the qio_channel_websock_handshake() method before attempting
79  * todo any I/O on the channel.
80  *
81  * Once the handshake has completed, all I/O should be done
82  * via the new websocket channel object and not the original
83  * master channel
84  *
85  * Returns: the new websockets channel object
86  */
87 QIOChannelWebsock *
88 qio_channel_websock_new_server(QIOChannel *master);
89 
90 /**
91  * qio_channel_websock_handshake:
92  * @ioc: the websocket channel object
93  * @func: the callback to invoke when completed
94  * @opaque: opaque data to pass to @func
95  * @destroy: optional callback to free @opaque
96  *
97  * Perform the websocket handshake. This method
98  * will return immediately and the handshake will
99  * continue in the background, provided the main
100  * loop is running. When the handshake is complete,
101  * or fails, the @func callback will be invoked.
102  */
103 void qio_channel_websock_handshake(QIOChannelWebsock *ioc,
104                                    QIOTaskFunc func,
105                                    gpointer opaque,
106                                    GDestroyNotify destroy);
107 
108 #endif /* QIO_CHANNEL_WEBSOCK_H */
109