1/*
2 * libvirt-common.h
3 * Summary: common macros and enums for the libvirt and libvirt-admin library
4 * Description: Provides common macros and enums needed by both libvirt and
5 *              libvirt-admin libraries
6 *
7 * Copyright (C) 2015 Red Hat, Inc.
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Lesser General Public
11 * License as published by the Free Software Foundation; either
12 * version 2.1 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
17 * Lesser General Public License for more details.
18 *
19 * You should have received a copy of the GNU Lesser General Public
20 * License along with this library.  If not, see
21 * <http://www.gnu.org/licenses/>.
22 */
23
24#if !defined __VIR_LIBVIRT_H_INCLUDES__ && !defined __VIR_ADMIN_H_INCLUDES__
25# error "Don't include this file directly"
26#endif
27
28#ifndef __VIR_VIRCOMMON_H__
29# define __VIR_VIRCOMMON_H__
30
31# include <sys/types.h>
32
33# ifdef __cplusplus
34extern "C" {
35# endif
36
37# ifndef VIR_DEPRECATED
38  /* The feature is present in gcc-3.1 and newer.  */
39#  if __GNUC__ > 3 || (__GNUC__ == 3 && __GNUC_MINOR__ >= 1)
40#   define VIR_DEPRECATED __attribute__((__deprecated__))
41#  else
42#   define VIR_DEPRECATED /* nothing */
43#  endif
44# endif /* VIR_DEPRECATED */
45
46# ifdef WIN32
47#  ifdef LIBVIRT_STATIC
48#   define VIR_EXPORT_VAR extern
49#  else
50#   ifdef IN_LIBVIRT
51#    define VIR_EXPORT_VAR __declspec(dllexport) extern
52#   else
53#    define VIR_EXPORT_VAR __declspec(dllimport) extern
54#   endif
55#  endif
56# else
57#  define VIR_EXPORT_VAR extern
58# endif
59
60/* General note - in the header files, any linear enumeration which
61 * might be expanded in the future has an optional *_LAST value that
62 * gives the size of the enum at the time of compilation, if the user
63 * defines VIR_ENUM_SENTINELS.  Enumerations for bit values do not
64 * have a *_LAST value, but additional bits may be defined.  */
65
66/* library versioning */
67
68/**
69 * LIBVIR_VERSION_NUMBER:
70 *
71 * Macro providing the version of the library as
72 * version * 1,000,000 + minor * 1000 + micro
73 */
74
75# define LIBVIR_VERSION_NUMBER @LIBVIRT_VERSION_NUMBER@
76
77/**
78 * LIBVIR_CHECK_VERSION:
79 * @major: major component of the version number
80 * @minor: minor component of the version number
81 * @micro: micro component of the version number
82 *
83 * Macro for developers to easily check what version of the library
84 * their code is compiling against.
85 * e.g.
86 *   #if LIBVIR_CHECK_VERSION(1,1,3)
87 *     // some code that only works in 1.1.3 and newer
88 *   #endif
89 */
90# define LIBVIR_CHECK_VERSION(major, minor, micro) \
91    ((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)
92
93/*
94 * virFreeCallback:
95 * @opaque: opaque user data provided at registration
96 *
97 * Type for a callback cleanup function to be paired with a callback.  This
98 * function will be called as a final chance to clean up the @opaque
99 * registered with the primary callback, at the time when the primary
100 * callback is deregistered.
101 *
102 * It is forbidden to call any other libvirt APIs from an
103 * implementation of this callback, since it can be invoked
104 * from a context which is not re-entrant safe. Failure to
105 * abide by this requirement may lead to application deadlocks
106 * or crashes.
107 */
108typedef void (*virFreeCallback)(void *opaque);
109
110typedef enum {
111    VIR_CONNECT_CLOSE_REASON_ERROR     = 0, /* Misc I/O error */
112    VIR_CONNECT_CLOSE_REASON_EOF       = 1, /* End-of-file from server */
113    VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered */
114    VIR_CONNECT_CLOSE_REASON_CLIENT    = 3, /* Client requested it */
115
116# ifdef VIR_ENUM_SENTINELS
117    VIR_CONNECT_CLOSE_REASON_LAST
118# endif
119} virConnectCloseReason;
120
121/**
122 * virTypedParameterType:
123 *
124 * Express the type of a virTypedParameter
125 */
126typedef enum {
127    VIR_TYPED_PARAM_INT     = 1, /* integer case */
128    VIR_TYPED_PARAM_UINT    = 2, /* unsigned integer case */
129    VIR_TYPED_PARAM_LLONG   = 3, /* long long case */
130    VIR_TYPED_PARAM_ULLONG  = 4, /* unsigned long long case */
131    VIR_TYPED_PARAM_DOUBLE  = 5, /* double case */
132    VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case */
133    VIR_TYPED_PARAM_STRING  = 7, /* string case */
134
135# ifdef VIR_ENUM_SENTINELS
136    VIR_TYPED_PARAM_LAST
137# endif
138} virTypedParameterType;
139
140/**
141 * virTypedParameterFlags:
142 *
143 * Flags related to libvirt APIs that use virTypedParameter.
144 *
145 * These enums should not conflict with those of virDomainModificationImpact.
146 */
147typedef enum {
148    /* 1 << 0 is reserved for virDomainModificationImpact */
149    /* 1 << 1 is reserved for virDomainModificationImpact */
150
151    /* Older servers lacked the ability to handle string typed
152     * parameters.  Attempts to set a string parameter with an older
153     * server will fail at the client, but attempts to retrieve
154     * parameters must not return strings from a new server to an
155     * older client, so this flag exists to identify newer clients to
156     * newer servers.  This flag is automatically set when needed, so
157     * the user does not have to worry about it; however, manually
158     * setting the flag can be used to reject servers that cannot
159     * return typed strings, even if no strings would be returned.
160     */
161    VIR_TYPED_PARAM_STRING_OKAY = 1 << 2,
162
163} virTypedParameterFlags;
164
165/**
166 * VIR_TYPED_PARAM_FIELD_LENGTH:
167 *
168 * Macro providing the field length of virTypedParameter name
169 */
170# define VIR_TYPED_PARAM_FIELD_LENGTH 80
171
172/**
173 * virTypedParameter:
174 *
175 * A named parameter, including a type and value.
176 *
177 * The types virSchedParameter, virBlkioParameter, and
178 * virMemoryParameter are aliases of this type, for use when
179 * targeting libvirt earlier than 0.9.2.
180 */
181typedef struct _virTypedParameter virTypedParameter;
182
183struct _virTypedParameter {
184    char field[VIR_TYPED_PARAM_FIELD_LENGTH];  /* parameter name */
185    int type;   /* parameter type, virTypedParameterType */
186    union {
187        int i;                      /* type is INT */
188        unsigned int ui;            /* type is UINT */
189        long long int l;            /* type is LLONG */
190        unsigned long long int ul;  /* type is ULLONG */
191        double d;                   /* type is DOUBLE */
192        char b;                     /* type is BOOLEAN */
193        char *s;                    /* type is STRING, may not be NULL */
194    } value; /* parameter value */
195};
196
197/**
198 * virTypedParameterPtr:
199 *
200 * a pointer to a virTypedParameter structure.
201 */
202typedef virTypedParameter *virTypedParameterPtr;
203
204virTypedParameterPtr virTypedParamsGet(virTypedParameterPtr params,
205                                       int nparams,
206                                       const char *name);
207int virTypedParamsGetInt(virTypedParameterPtr params,
208                         int nparams,
209                         const char *name,
210                         int *value);
211int virTypedParamsGetUInt(virTypedParameterPtr params,
212                          int nparams,
213                          const char *name,
214                          unsigned int *value);
215int virTypedParamsGetLLong(virTypedParameterPtr params,
216                           int nparams,
217                           const char *name,
218                           long long *value);
219int virTypedParamsGetULLong(virTypedParameterPtr params,
220                            int nparams,
221                            const char *name,
222                            unsigned long long *value);
223int virTypedParamsGetDouble(virTypedParameterPtr params,
224                            int nparams,
225                            const char *name,
226                            double *value);
227int virTypedParamsGetBoolean(virTypedParameterPtr params,
228                             int nparams,
229                             const char *name,
230                             int *value);
231int virTypedParamsGetString(virTypedParameterPtr params,
232                            int nparams,
233                            const char *name,
234                            const char **value);
235
236int virTypedParamsAddInt(virTypedParameterPtr *params,
237                         int *nparams,
238                         int *maxparams,
239                         const char *name,
240                         int value);
241int virTypedParamsAddUInt(virTypedParameterPtr *params,
242                          int *nparams,
243                          int *maxparams,
244                          const char *name,
245                          unsigned int value);
246int virTypedParamsAddLLong(virTypedParameterPtr *params,
247                           int *nparams,
248                           int *maxparams,
249                           const char *name,
250                           long long value);
251int virTypedParamsAddULLong(virTypedParameterPtr *params,
252                            int *nparams,
253                            int *maxparams,
254                            const char *name,
255                            unsigned long long value);
256int virTypedParamsAddDouble(virTypedParameterPtr *params,
257                            int *nparams,
258                            int *maxparams,
259                            const char *name,
260                            double value);
261int virTypedParamsAddBoolean(virTypedParameterPtr *params,
262                             int *nparams,
263                             int *maxparams,
264                             const char *name,
265                             int value);
266int virTypedParamsAddString(virTypedParameterPtr *params,
267                            int *nparams,
268                            int *maxparams,
269                            const char *name,
270                            const char *value);
271int virTypedParamsAddStringList(virTypedParameterPtr *params,
272                                int *nparams,
273                                int *maxparams,
274                                const char *name,
275                                const char **values);
276int virTypedParamsAddFromString(virTypedParameterPtr *params,
277                                int *nparams,
278                                int *maxparams,
279                                const char *name,
280                                int type,
281                                const char *value);
282
283void virTypedParamsClear(virTypedParameterPtr params,
284                         int nparams);
285void virTypedParamsFree(virTypedParameterPtr params,
286                        int nparams);
287
288# ifdef __cplusplus
289}
290# endif
291
292#endif /* __VIR_VIRCOMMON_H__ */
293