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