1 /* 2 * libvirt-stream.h 3 * Summary: APIs for management of streams 4 * Description: Provides APIs for the management of streams 5 * 6 * Copyright (C) 2006-2014 Red Hat, Inc. 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Lesser General Public 10 * License as published by the Free Software Foundation; either 11 * version 2.1 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Lesser General Public License for more details. 17 * 18 * You should have received a copy of the GNU Lesser General Public 19 * License along with this library. If not, see 20 * <http://www.gnu.org/licenses/>. 21 */ 22 23 #ifndef LIBVIRT_STREAM_H 24 # define LIBVIRT_STREAM_H 25 26 # ifndef __VIR_LIBVIRT_H_INCLUDES__ 27 # error "Don't include this file directly, only use libvirt/libvirt.h" 28 # endif 29 30 31 typedef enum { 32 VIR_STREAM_NONBLOCK = (1 << 0), 33 } virStreamFlags; 34 35 virStreamPtr virStreamNew(virConnectPtr conn, 36 unsigned int flags); 37 int virStreamRef(virStreamPtr st); 38 39 int virStreamSend(virStreamPtr st, 40 const char *data, 41 size_t nbytes); 42 43 int virStreamRecv(virStreamPtr st, 44 char *data, 45 size_t nbytes); 46 47 typedef enum { 48 VIR_STREAM_RECV_STOP_AT_HOLE = (1 << 0), 49 } virStreamRecvFlagsValues; 50 51 int virStreamRecvFlags(virStreamPtr st, 52 char *data, 53 size_t nbytes, 54 unsigned int flags); 55 56 int virStreamSendHole(virStreamPtr st, 57 long long length, 58 unsigned int flags); 59 60 int virStreamRecvHole(virStreamPtr, 61 long long *length, 62 unsigned int flags); 63 64 65 /** 66 * virStreamSourceFunc: 67 * 68 * @st: the stream object 69 * @data: preallocated array to be filled with data 70 * @nbytes: size of the data array 71 * @opaque: optional application provided data 72 * 73 * The virStreamSourceFunc callback is used together with 74 * the virStreamSendAll and virStreamSparseSendAll functions 75 * for libvirt to obtain the data that is to be sent. 76 * 77 * The callback will be invoked multiple times, 78 * fetching data in small chunks. The application 79 * should fill the 'data' array with up to 'nbytes' 80 * of data and then return the number actual number 81 * of bytes. The callback will continue to be 82 * invoked until it indicates the end of the source 83 * has been reached by returning 0. A return value 84 * of -1 at any time will abort the send operation. 85 * 86 * Please note that for more accurate error reporting the 87 * callback should set appropriate errno on failure. 88 * 89 * Returns the number of bytes filled, 0 upon end 90 * of file, or -1 upon error 91 */ 92 typedef int (*virStreamSourceFunc)(virStreamPtr st, 93 char *data, 94 size_t nbytes, 95 void *opaque); 96 97 int virStreamSendAll(virStreamPtr st, 98 virStreamSourceFunc handler, 99 void *opaque); 100 101 /** 102 * virStreamSourceHoleFunc: 103 * @st: the stream object 104 * @inData: are we in data section 105 * @length: how long is the section we are currently in 106 * @opaque: optional application provided data 107 * 108 * The virStreamSourceHoleFunc callback is used together with the 109 * virStreamSparseSendAll function for libvirt to obtain the 110 * length of section stream is currently in. 111 * 112 * Moreover, upon successful return, @length should be updated 113 * with how many bytes are left until the current section ends 114 * (either data section or hole section). Also the stream is 115 * currently in data section, @inData should be set to a non-zero 116 * value and vice versa. 117 * 118 * NB: there's an implicit hole at the end of each file. If 119 * that's the case, @inData and @length should be both set to 0. 120 * 121 * This function should not adjust the current position within 122 * the file. 123 * 124 * Please note that for more accurate error reporting the 125 * callback should set appropriate errno on failure. 126 * 127 * Returns 0 on success, 128 * -1 upon error 129 */ 130 typedef int (*virStreamSourceHoleFunc)(virStreamPtr st, 131 int *inData, 132 long long *length, 133 void *opaque); 134 135 /** 136 * virStreamSourceSkipFunc: 137 * @st: the stream object 138 * @length: stream hole size 139 * @opaque: optional application provided data 140 * 141 * This callback is used together with the virStreamSparseSendAll 142 * to skip holes in the underlying file as reported by 143 * virStreamSourceHoleFunc. 144 * 145 * The callback may be invoked multiple times as holes are found 146 * during processing a stream. The application should skip 147 * processing the hole in the stream source and then return. 148 * A return value of -1 at any time will abort the send operation. 149 * 150 * Please note that for more accurate error reporting the 151 * callback should set appropriate errno on failure. 152 * 153 * Returns 0 on success, 154 * -1 upon error. 155 */ 156 typedef int (*virStreamSourceSkipFunc)(virStreamPtr st, 157 long long length, 158 void *opaque); 159 160 int virStreamSparseSendAll(virStreamPtr st, 161 virStreamSourceFunc handler, 162 virStreamSourceHoleFunc holeHandler, 163 virStreamSourceSkipFunc skipHandler, 164 void *opaque); 165 166 /** 167 * virStreamSinkFunc: 168 * 169 * @st: the stream object 170 * @data: preallocated array to be filled with data 171 * @nbytes: size of the data array 172 * @opaque: optional application provided data 173 * 174 * The virStreamSinkFunc callback is used together with the 175 * virStreamRecvAll or virStreamSparseRecvAll functions for 176 * libvirt to provide the data that has been received. 177 * 178 * The callback will be invoked multiple times, 179 * providing data in small chunks. The application 180 * should consume up 'nbytes' from the 'data' array 181 * of data and then return the number actual number 182 * of bytes consumed. The callback will continue to be 183 * invoked until it indicates the end of the stream 184 * has been reached. A return value of -1 at any time 185 * will abort the receive operation 186 * 187 * Please note that for more accurate error reporting the 188 * callback should set appropriate errno on failure. 189 * 190 * Returns the number of bytes consumed or -1 upon 191 * error 192 */ 193 typedef int (*virStreamSinkFunc)(virStreamPtr st, 194 const char *data, 195 size_t nbytes, 196 void *opaque); 197 198 int virStreamRecvAll(virStreamPtr st, 199 virStreamSinkFunc handler, 200 void *opaque); 201 202 /** 203 * virStreamSinkHoleFunc: 204 * @st: the stream object 205 * @length: stream hole size 206 * @opaque: optional application provided data 207 * 208 * This callback is used together with the virStreamSparseRecvAll 209 * function for libvirt to provide the size of a hole that 210 * occurred in the stream. 211 * 212 * The callback may be invoked multiple times as holes are found 213 * during processing a stream. The application should create the 214 * hole in the stream target and then return. A return value of 215 * -1 at any time will abort the receive operation. 216 * 217 * Please note that for more accurate error reporting the 218 * callback should set appropriate errno on failure. 219 * 220 * Returns 0 on success, 221 * -1 upon error 222 */ 223 typedef int (*virStreamSinkHoleFunc)(virStreamPtr st, 224 long long length, 225 void *opaque); 226 227 int virStreamSparseRecvAll(virStreamPtr stream, 228 virStreamSinkFunc handler, 229 virStreamSinkHoleFunc holeHandler, 230 void *opaque); 231 232 typedef enum { 233 VIR_STREAM_EVENT_READABLE = (1 << 0), 234 VIR_STREAM_EVENT_WRITABLE = (1 << 1), 235 VIR_STREAM_EVENT_ERROR = (1 << 2), 236 VIR_STREAM_EVENT_HANGUP = (1 << 3), 237 } virStreamEventType; 238 239 240 /** 241 * virStreamEventCallback: 242 * 243 * @stream: stream on which the event occurred 244 * @events: bitset of events from virEventHandleType constants 245 * @opaque: user data registered with handle 246 * 247 * Callback for receiving stream events. The callback will 248 * be invoked once for each event which is pending. 249 */ 250 typedef void (*virStreamEventCallback)(virStreamPtr stream, int events, void *opaque); 251 252 int virStreamEventAddCallback(virStreamPtr stream, 253 int events, 254 virStreamEventCallback cb, 255 void *opaque, 256 virFreeCallback ff); 257 258 int virStreamEventUpdateCallback(virStreamPtr stream, 259 int events); 260 261 int virStreamEventRemoveCallback(virStreamPtr stream); 262 263 264 int virStreamFinish(virStreamPtr st); 265 int virStreamAbort(virStreamPtr st); 266 267 int virStreamFree(virStreamPtr st); 268 269 #endif /* LIBVIRT_STREAM_H */ 270