1/*
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
9 * version 2 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_SOCKET_H
22#define QIO_CHANNEL_SOCKET_H
23
24#include "io/channel.h"
25#include "io/task.h"
26#include "qemu/sockets.h"
27
28#define TYPE_QIO_CHANNEL_SOCKET "qio-channel-socket"
29#define QIO_CHANNEL_SOCKET(obj) \
30 OBJECT_CHECK(QIOChannelSocket, (obj), TYPE_QIO_CHANNEL_SOCKET)
31
32typedef struct QIOChannelSocket QIOChannelSocket;
33
34/**
35 * QIOChannelSocket:
36 *
37 * The QIOChannelSocket class provides a channel implementation
38 * that can transport data over a UNIX socket or TCP socket.
39 * Beyond the core channel API, it also provides functionality
40 * for accepting client connections, tuning some socket
41 * parameters and getting socket address strings.
42 */
43
44struct QIOChannelSocket {
45 QIOChannel parent;
46 int fd;
47 struct sockaddr_storage localAddr;
48 socklen_t localAddrLen;
49 struct sockaddr_storage remoteAddr;
50 socklen_t remoteAddrLen;
51};
52
53
54/**
55 * qio_channel_socket_new:
56 *
57 * Create a channel for performing I/O on a socket
58 * connection, that is initially closed. After
59 * creating the socket, it must be setup as a client
60 * connection or server.
61 *
62 * Returns: the socket channel object
63 */
64QIOChannelSocket *
65qio_channel_socket_new(void);
66
67/**
68 * qio_channel_socket_new_fd:
69 * @fd: the socket file descriptor
70 * @errp: pointer to a NULL-initialized error object
71 *
72 * Create a channel for performing I/O on the socket
73 * connection represented by the file descriptor @fd.
74 *
75 * Returns: the socket channel object, or NULL on error
76 */
77QIOChannelSocket *
78qio_channel_socket_new_fd(int fd,
79 Error **errp);
80
81
82/**
83 * qio_channel_socket_connect_sync:
84 * @ioc: the socket channel object
85 * @addr: the address to connect to
86 * @errp: pointer to a NULL-initialized error object
87 *
88 * Attempt to connect to the address @addr. This method
89 * will run in the foreground so the caller will not regain
90 * execution control until the connection is established or
91 * an error occurs.
92 */
93int qio_channel_socket_connect_sync(QIOChannelSocket *ioc,
94 SocketAddress *addr,
95 Error **errp);
96
97/**
98 * qio_channel_socket_connect_async:
99 * @ioc: the socket channel object
100 * @addr: the address to connect to
101 * @callback: the function to invoke on completion
102 * @opaque: user data to pass to @callback
103 * @destroy: the function to free @opaque
104 * @context: the context to run the async task. If %NULL, the default
105 * context will be used.
106 *
107 * Attempt to connect to the address @addr. This method
108 * will run in the background so the caller will regain
109 * execution control immediately. The function @callback
110 * will be invoked on completion or failure. The @addr
111 * parameter will be copied, so may be freed as soon
112 * as this function returns without waiting for completion.
113 */
114void qio_channel_socket_connect_async(QIOChannelSocket *ioc,
115 SocketAddress *addr,
116 QIOTaskFunc callback,
117 gpointer opaque,
118 GDestroyNotify destroy,
119 GMainContext *context);
120
121
122/**
123 * qio_channel_socket_listen_sync:
124 * @ioc: the socket channel object
125 * @addr: the address to listen to
126 * @num: the expected ammount of connections
127 * @errp: pointer to a NULL-initialized error object
128 *
129 * Attempt to listen to the address @addr. This method
130 * will run in the foreground so the caller will not regain
131 * execution control until the connection is established or
132 * an error occurs.
133 */
134int qio_channel_socket_listen_sync(QIOChannelSocket *ioc,
135 SocketAddress *addr,
136 int num,
137 Error **errp);
138
139/**
140 * qio_channel_socket_listen_async:
141 * @ioc: the socket channel object
142 * @addr: the address to listen to
143 * @num: the expected ammount of connections
144 * @callback: the function to invoke on completion
145 * @opaque: user data to pass to @callback
146 * @destroy: the function to free @opaque
147 * @context: the context to run the async task. If %NULL, the default
148 * context will be used.
149 *
150 * Attempt to listen to the address @addr. This method
151 * will run in the background so the caller will regain
152 * execution control immediately. The function @callback
153 * will be invoked on completion or failure. The @addr
154 * parameter will be copied, so may be freed as soon
155 * as this function returns without waiting for completion.
156 */
157void qio_channel_socket_listen_async(QIOChannelSocket *ioc,
158 SocketAddress *addr,
159 int num,
160 QIOTaskFunc callback,
161 gpointer opaque,
162 GDestroyNotify destroy,
163 GMainContext *context);
164
165
166/**
167 * qio_channel_socket_dgram_sync:
168 * @ioc: the socket channel object
169 * @localAddr: the address to local bind address
170 * @remoteAddr: the address to remote peer address
171 * @errp: pointer to a NULL-initialized error object
172 *
173 * Attempt to initialize a datagram socket bound to
174 * @localAddr and communicating with peer @remoteAddr.
175 * This method will run in the foreground so the caller
176 * will not regain execution control until the socket
177 * is established or an error occurs.
178 */
179int qio_channel_socket_dgram_sync(QIOChannelSocket *ioc,
180 SocketAddress *localAddr,
181 SocketAddress *remoteAddr,
182 Error **errp);
183
184/**
185 * qio_channel_socket_dgram_async:
186 * @ioc: the socket channel object
187 * @localAddr: the address to local bind address
188 * @remoteAddr: the address to remote peer address
189 * @callback: the function to invoke on completion
190 * @opaque: user data to pass to @callback
191 * @destroy: the function to free @opaque
192 * @context: the context to run the async task. If %NULL, the default
193 * context will be used.
194 *
195 * Attempt to initialize a datagram socket bound to
196 * @localAddr and communicating with peer @remoteAddr.
197 * This method will run in the background so the caller
198 * will regain execution control immediately. The function
199 * @callback will be invoked on completion or failure.
200 * The @localAddr and @remoteAddr parameters will be copied,
201 * so may be freed as soon as this function returns without
202 * waiting for completion.
203 */
204void qio_channel_socket_dgram_async(QIOChannelSocket *ioc,
205 SocketAddress *localAddr,
206 SocketAddress *remoteAddr,
207 QIOTaskFunc callback,
208 gpointer opaque,
209 GDestroyNotify destroy,
210 GMainContext *context);
211
212
213/**
214 * qio_channel_socket_get_local_address:
215 * @ioc: the socket channel object
216 * @errp: pointer to a NULL-initialized error object
217 *
218 * Get the string representation of the local socket
219 * address. A pointer to the allocated address information
220 * struct will be returned, which the caller is required to
221 * release with a call qapi_free_SocketAddress() when no
222 * longer required.
223 *
224 * Returns: 0 on success, -1 on error
225 */
226SocketAddress *
227qio_channel_socket_get_local_address(QIOChannelSocket *ioc,
228 Error **errp);
229
230/**
231 * qio_channel_socket_get_remote_address:
232 * @ioc: the socket channel object
233 * @errp: pointer to a NULL-initialized error object
234 *
235 * Get the string representation of the local socket
236 * address. A pointer to the allocated address information
237 * struct will be returned, which the caller is required to
238 * release with a call qapi_free_SocketAddress() when no
239 * longer required.
240 *
241 * Returns: the socket address struct, or NULL on error
242 */
243SocketAddress *
244qio_channel_socket_get_remote_address(QIOChannelSocket *ioc,
245 Error **errp);
246
247
248/**
249 * qio_channel_socket_accept:
250 * @ioc: the socket channel object
251 * @errp: pointer to a NULL-initialized error object
252 *
253 * If the socket represents a server, then this accepts
254 * a new client connection. The returned channel will
255 * represent the connected client socket.
256 *
257 * Returns: the new client channel, or NULL on error
258 */
259QIOChannelSocket *
260qio_channel_socket_accept(QIOChannelSocket *ioc,
261 Error **errp);
262
263
264#endif /* QIO_CHANNEL_SOCKET_H */
265