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