blob: ab15577d38487aa6657a286d75637e311419ecef [file] [log] [blame]
Daniel P. Berrange559607e2015-02-27 16:19:33 +00001/*
2 * QEMU I/O channels sockets driver
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
Chetan Pantc8198bd2020-10-14 13:40:33 +00009 * version 2.1 of the License, or (at your option) any later version.
Daniel P. Berrange559607e2015-02-27 16:19:33 +000010 *
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
Markus Armbruster2a6a4072016-06-29 13:47:03 +020021#ifndef QIO_CHANNEL_SOCKET_H
22#define QIO_CHANNEL_SOCKET_H
Daniel P. Berrange559607e2015-02-27 16:19:33 +000023
24#include "io/channel.h"
25#include "io/task.h"
26#include "qemu/sockets.h"
Eduardo Habkostdb1015e2020-09-03 16:43:22 -040027#include "qom/object.h"
Daniel P. Berrange559607e2015-02-27 16:19:33 +000028
29#define TYPE_QIO_CHANNEL_SOCKET "qio-channel-socket"
Eduardo Habkost80633962020-09-16 14:25:19 -040030OBJECT_DECLARE_SIMPLE_TYPE(QIOChannelSocket, QIO_CHANNEL_SOCKET)
Daniel P. Berrange559607e2015-02-27 16:19:33 +000031
Daniel P. Berrange559607e2015-02-27 16:19:33 +000032
33/**
34 * QIOChannelSocket:
35 *
36 * The QIOChannelSocket class provides a channel implementation
37 * that can transport data over a UNIX socket or TCP socket.
38 * Beyond the core channel API, it also provides functionality
39 * for accepting client connections, tuning some socket
40 * parameters and getting socket address strings.
41 */
42
43struct QIOChannelSocket {
44 QIOChannel parent;
45 int fd;
46 struct sockaddr_storage localAddr;
47 socklen_t localAddrLen;
48 struct sockaddr_storage remoteAddr;
49 socklen_t remoteAddrLen;
Leonardo Bras2bc58ff2022-05-13 03:28:32 -030050 ssize_t zero_copy_queued;
51 ssize_t zero_copy_sent;
Daniel P. Berrange559607e2015-02-27 16:19:33 +000052};
53
54
55/**
56 * qio_channel_socket_new:
57 *
58 * Create a channel for performing I/O on a socket
59 * connection, that is initially closed. After
60 * creating the socket, it must be setup as a client
61 * connection or server.
62 *
63 * Returns: the socket channel object
64 */
65QIOChannelSocket *
66qio_channel_socket_new(void);
67
68/**
69 * qio_channel_socket_new_fd:
70 * @fd: the socket file descriptor
Daniel P. Berrange821791b2016-01-13 12:22:33 +000071 * @errp: pointer to a NULL-initialized error object
Daniel P. Berrange559607e2015-02-27 16:19:33 +000072 *
73 * Create a channel for performing I/O on the socket
74 * connection represented by the file descriptor @fd.
75 *
76 * Returns: the socket channel object, or NULL on error
77 */
78QIOChannelSocket *
79qio_channel_socket_new_fd(int fd,
80 Error **errp);
81
82
83/**
84 * qio_channel_socket_connect_sync:
85 * @ioc: the socket channel object
86 * @addr: the address to connect to
Daniel P. Berrange821791b2016-01-13 12:22:33 +000087 * @errp: pointer to a NULL-initialized error object
Daniel P. Berrange559607e2015-02-27 16:19:33 +000088 *
89 * Attempt to connect to the address @addr. This method
90 * will run in the foreground so the caller will not regain
91 * execution control until the connection is established or
92 * an error occurs.
93 */
94int qio_channel_socket_connect_sync(QIOChannelSocket *ioc,
Markus Armbrusterbd269eb2017-04-26 09:36:41 +020095 SocketAddress *addr,
Daniel P. Berrange559607e2015-02-27 16:19:33 +000096 Error **errp);
97
98/**
99 * qio_channel_socket_connect_async:
100 * @ioc: the socket channel object
101 * @addr: the address to connect to
102 * @callback: the function to invoke on completion
103 * @opaque: user data to pass to @callback
104 * @destroy: the function to free @opaque
Peter Xu8005fdd2018-03-05 14:43:23 +0800105 * @context: the context to run the async task. If %NULL, the default
106 * context will be used.
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000107 *
108 * Attempt to connect to the address @addr. This method
109 * will run in the background so the caller will regain
110 * execution control immediately. The function @callback
Daniel P. Berrangefe81e932016-02-03 13:47:36 +0000111 * will be invoked on completion or failure. The @addr
112 * parameter will be copied, so may be freed as soon
113 * as this function returns without waiting for completion.
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000114 */
115void qio_channel_socket_connect_async(QIOChannelSocket *ioc,
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200116 SocketAddress *addr,
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000117 QIOTaskFunc callback,
118 gpointer opaque,
Peter Xu8005fdd2018-03-05 14:43:23 +0800119 GDestroyNotify destroy,
120 GMainContext *context);
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000121
122
123/**
124 * qio_channel_socket_listen_sync:
125 * @ioc: the socket channel object
126 * @addr: the address to listen to
Michael Tokarevd02d06f2023-08-23 09:53:15 +0300127 * @num: the expected amount of connections
Daniel P. Berrange821791b2016-01-13 12:22:33 +0000128 * @errp: pointer to a NULL-initialized error object
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000129 *
130 * Attempt to listen to the address @addr. This method
131 * will run in the foreground so the caller will not regain
132 * execution control until the connection is established or
133 * an error occurs.
134 */
135int qio_channel_socket_listen_sync(QIOChannelSocket *ioc,
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200136 SocketAddress *addr,
Juan Quintela4e2d8bf2019-08-19 15:29:58 +0200137 int num,
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000138 Error **errp);
139
140/**
141 * qio_channel_socket_listen_async:
142 * @ioc: the socket channel object
143 * @addr: the address to listen to
Michael Tokarevd02d06f2023-08-23 09:53:15 +0300144 * @num: the expected amount of connections
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000145 * @callback: the function to invoke on completion
146 * @opaque: user data to pass to @callback
147 * @destroy: the function to free @opaque
Peter Xu8005fdd2018-03-05 14:43:23 +0800148 * @context: the context to run the async task. If %NULL, the default
149 * context will be used.
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000150 *
151 * Attempt to listen to the address @addr. This method
152 * will run in the background so the caller will regain
153 * execution control immediately. The function @callback
Daniel P. Berrangefe81e932016-02-03 13:47:36 +0000154 * will be invoked on completion or failure. The @addr
155 * parameter will be copied, so may be freed as soon
156 * as this function returns without waiting for completion.
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000157 */
158void qio_channel_socket_listen_async(QIOChannelSocket *ioc,
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200159 SocketAddress *addr,
Juan Quintela7959e292019-08-20 09:40:39 +0200160 int num,
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000161 QIOTaskFunc callback,
162 gpointer opaque,
Peter Xu8005fdd2018-03-05 14:43:23 +0800163 GDestroyNotify destroy,
164 GMainContext *context);
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000165
166
167/**
168 * qio_channel_socket_dgram_sync:
169 * @ioc: the socket channel object
170 * @localAddr: the address to local bind address
171 * @remoteAddr: the address to remote peer address
Daniel P. Berrange821791b2016-01-13 12:22:33 +0000172 * @errp: pointer to a NULL-initialized error object
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000173 *
174 * Attempt to initialize a datagram socket bound to
175 * @localAddr and communicating with peer @remoteAddr.
176 * This method will run in the foreground so the caller
177 * will not regain execution control until the socket
178 * is established or an error occurs.
179 */
180int qio_channel_socket_dgram_sync(QIOChannelSocket *ioc,
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200181 SocketAddress *localAddr,
182 SocketAddress *remoteAddr,
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000183 Error **errp);
184
185/**
186 * qio_channel_socket_dgram_async:
187 * @ioc: the socket channel object
188 * @localAddr: the address to local bind address
189 * @remoteAddr: the address to remote peer address
190 * @callback: the function to invoke on completion
191 * @opaque: user data to pass to @callback
192 * @destroy: the function to free @opaque
Peter Xu8005fdd2018-03-05 14:43:23 +0800193 * @context: the context to run the async task. If %NULL, the default
194 * context will be used.
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000195 *
196 * Attempt to initialize a datagram socket bound to
197 * @localAddr and communicating with peer @remoteAddr.
198 * This method will run in the background so the caller
199 * will regain execution control immediately. The function
200 * @callback will be invoked on completion or failure.
Daniel P. Berrangefe81e932016-02-03 13:47:36 +0000201 * The @localAddr and @remoteAddr parameters will be copied,
202 * so may be freed as soon as this function returns without
203 * waiting for completion.
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000204 */
205void qio_channel_socket_dgram_async(QIOChannelSocket *ioc,
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200206 SocketAddress *localAddr,
207 SocketAddress *remoteAddr,
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000208 QIOTaskFunc callback,
209 gpointer opaque,
Peter Xu8005fdd2018-03-05 14:43:23 +0800210 GDestroyNotify destroy,
211 GMainContext *context);
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000212
213
214/**
215 * qio_channel_socket_get_local_address:
216 * @ioc: the socket channel object
Daniel P. Berrange821791b2016-01-13 12:22:33 +0000217 * @errp: pointer to a NULL-initialized error object
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000218 *
219 * Get the string representation of the local socket
220 * address. A pointer to the allocated address information
221 * struct will be returned, which the caller is required to
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200222 * release with a call qapi_free_SocketAddress() when no
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000223 * longer required.
224 *
225 * Returns: 0 on success, -1 on error
226 */
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200227SocketAddress *
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000228qio_channel_socket_get_local_address(QIOChannelSocket *ioc,
229 Error **errp);
230
231/**
232 * qio_channel_socket_get_remote_address:
233 * @ioc: the socket channel object
Daniel P. Berrange821791b2016-01-13 12:22:33 +0000234 * @errp: pointer to a NULL-initialized error object
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000235 *
236 * Get the string representation of the local socket
237 * address. A pointer to the allocated address information
238 * struct will be returned, which the caller is required to
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200239 * release with a call qapi_free_SocketAddress() when no
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000240 * longer required.
241 *
242 * Returns: the socket address struct, or NULL on error
243 */
Markus Armbrusterbd269eb2017-04-26 09:36:41 +0200244SocketAddress *
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000245qio_channel_socket_get_remote_address(QIOChannelSocket *ioc,
246 Error **errp);
247
248
249/**
250 * qio_channel_socket_accept:
251 * @ioc: the socket channel object
Daniel P. Berrange821791b2016-01-13 12:22:33 +0000252 * @errp: pointer to a NULL-initialized error object
Daniel P. Berrange559607e2015-02-27 16:19:33 +0000253 *
254 * If the socket represents a server, then this accepts
255 * a new client connection. The returned channel will
256 * represent the connected client socket.
257 *
258 * Returns: the new client channel, or NULL on error
259 */
260QIOChannelSocket *
261qio_channel_socket_accept(QIOChannelSocket *ioc,
262 Error **errp);
263
264
Markus Armbruster2a6a4072016-06-29 13:47:03 +0200265#endif /* QIO_CHANNEL_SOCKET_H */