1/*
2 * The Qubes OS Project, http://www.qubes-os.org
3 *
4 * Copyright (C) 2010  Rafal Wojtczuk  <rafal@invisiblethingslab.com>
5 *
6 * This program is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU General Public License
8 * as published by the Free Software Foundation; either version 2
9 * of the License, or (at your option) any later version.
10 *
11 * This program 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
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
19 *
20 */
21
22// SPDX-License-Identifier: GPL-2.0-or-later
23
24#pragma once
25
26#include <stddef.h>
27
28typedef int EVTCHN;
29
30struct libvchan;
31typedef struct libvchan libvchan_t;
32
33/**
34* Set up a vchan, including granting pages
35* @return structure, or NULL in case of an error
36*/
37libvchan_t *libvchan_server_init(int domain, int port, size_t read_min, size_t write_min);
38
39/**
40* Connect to an existing vchan. Note: you can reconnect to an existing vchan
41* safely, however no locking is performed, so you must prevent multiple clients
42* from connecting to a single server.
43*/
44libvchan_t *libvchan_client_init(int domain, int port);
45
46
47/**
48* Waits for reads or writes to unblock, or for a close
49*/
50int libvchan_wait(libvchan_t *ctrl);
51
52/** Amount of data ready to read, in bytes */
53int libvchan_data_ready(libvchan_t *ctrl);
54
55/** Amount of data it is possible to send without blocking */
56int libvchan_buffer_space(libvchan_t *ctrl);
57
58/**
59* Packet-based receive: always reads exactly $size bytes.
60* @param ctrl The vchan control structure
61* @param data Buffer for data that was read
62* @param size Size of the buffer and amount of data to read
63* @return -1 on error, 0 if nonblocking and insufficient data is available, or $size
64*/
65int libvchan_recv(libvchan_t *ctrl, void *data, size_t size);
66
67
68/**
69* Packet-based send: send entire buffer if possible
70* @param ctrl The vchan control structure
71* @param data Buffer for data to send
72* @param size Size of the buffer and amount of data to send
73* @return -1 on error, 0 if nonblocking and insufficient space is available, or $size
74*/
75int libvchan_send(libvchan_t *ctrl, const void *data, size_t size);
76
77/**
78* Stream-based receive: reads as much data as possible.
79* @param ctrl The vchan control structure
80* @param data Buffer for data that was read
81* @param size Size of the buffer
82* @return -1 on error, otherwise the amount of data read (which may be zero if
83* the vchan is nonblocking)
84*/
85int libvchan_read(libvchan_t *ctrl, void *data, size_t size);
86
87
88/**
89* Stream-based send: send as much data as possible.
90* @param ctrl The vchan control structure
91* @param data Buffer for data to send
92* @param size Size of the buffer
93* @return -1 on error, otherwise the amount of data sent (which may be zero if
94* the vchan is nonblocking)
95*/
96int libvchan_write(libvchan_t *ctrl, const void *data, size_t size);
97
98/**
99* Query the state of the vchan shared page:
100* return 0 when one side has called libxenvchan_close() or crashed
101* return 1 when both sides are open
102* return 2 [server only] when no client has yet connected
103*/
104int libvchan_is_open(libvchan_t *ctrl);
105
106/// returns nonzero if the peer has closed connection
107int libvchan_is_eof(libvchan_t *ctrl);
108
109/**
110* Returns the event file descriptor for this vchan. When this FD is readable,
111* libvchan() will not block, and the state of the vchan has changed since
112* the last invocation of libvchan().
113*/
114int libvchan_fd_for_select(libvchan_t *ctrl);
115
116/**
117 * Notify the peer of closing.
118 */
119void libvchan_close(libvchan_t *ctrl);
120