libvirt-common

libvirt-common - common macros and enums for the libvirt and libvirt-admin library

Provides common macros and enums needed by both libvirt and libvirt-admin libraries

Author(s): Erik Skultety <eskultet@redhat.com> Copyright (C) 2015 Red Hat, Inc. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library. If not, see <http://www.gnu.org/licenses/>.

Synopsis

#define LIBVIR_CHECK_VERSION(major, minor, micro);
#define LIBVIR_VERSION_NUMBER;
#define VIR_TYPED_PARAM_FIELD_LENGTH;
typedef enum virConnectCloseReason;
typedef struct _virTypedParameter virTypedParameter;
typedef enum virTypedParameterFlags;
typedef virTypedParameter * virTypedParameterPtr;
typedef enum virTypedParameterType;
typedef void virFreeCallback			(void * opaque);
int	virTypedParamsAddBoolean	(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
int value); int virTypedParamsAddDouble (virTypedParameterPtr * params,
int * nparams,
int * maxparams,
const char * name,
double value); int virTypedParamsAddFromString (virTypedParameterPtr * params,
int * nparams,
int * maxparams,
const char * name,
int type,
const char * value); int virTypedParamsAddInt (virTypedParameterPtr * params,
int * nparams,
int * maxparams,
const char * name,
int value); int virTypedParamsAddLLong (virTypedParameterPtr * params,
int * nparams,
int * maxparams,
const char * name,
long long value); int virTypedParamsAddString (virTypedParameterPtr * params,
int * nparams,
int * maxparams,
const char * name,
const char * value); int virTypedParamsAddStringList (virTypedParameterPtr * params,
int * nparams,
int * maxparams,
const char * name,
const char ** values); int virTypedParamsAddUInt (virTypedParameterPtr * params,
int * nparams,
int * maxparams,
const char * name,
unsigned int value); int virTypedParamsAddULLong (virTypedParameterPtr * params,
int * nparams,
int * maxparams,
const char * name,
unsigned long long value); void virTypedParamsClear (virTypedParameterPtr params,
int nparams); void virTypedParamsFree (virTypedParameterPtr params,
int nparams); virTypedParameterPtr virTypedParamsGet (virTypedParameterPtr params,
int nparams,
const char * name); int virTypedParamsGetBoolean (virTypedParameterPtr params,
int nparams,
const char * name,
int * value); int virTypedParamsGetDouble (virTypedParameterPtr params,
int nparams,
const char * name,
double * value); int virTypedParamsGetInt (virTypedParameterPtr params,
int nparams,
const char * name,
int * value); int virTypedParamsGetLLong (virTypedParameterPtr params,
int nparams,
const char * name,
long long * value); int virTypedParamsGetString (virTypedParameterPtr params,
int nparams,
const char * name,
const char ** value); int virTypedParamsGetUInt (virTypedParameterPtr params,
int nparams,
const char * name,
unsigned int * value); int virTypedParamsGetULLong (virTypedParameterPtr params,
int nparams,
const char * name,
unsigned long long * value);

Description

Details

Macro LIBVIR_CHECK_VERSION

#define LIBVIR_CHECK_VERSION(major, minor, micro);

Macro for developers to easily check what version of the library their code is compiling against. e.g. #if LIBVIR_CHECK_VERSION(1,1,3) // some code that only works in 1.1.3 and newer #endif

major:major component of the version number
minor:minor component of the version number
micro:micro component of the version number

Macro LIBVIR_VERSION_NUMBER

#define LIBVIR_VERSION_NUMBER;

Macro providing the version of the library as version * 1,000,000 + minor * 1000 + micro


Macro VIR_TYPED_PARAM_FIELD_LENGTH

#define VIR_TYPED_PARAM_FIELD_LENGTH;

Macro providing the field length of virTypedParameter name


Enum virConnectCloseReason

enum virConnectCloseReason {
    VIR_CONNECT_CLOSE_REASON_ERROR = 0 /* Misc I/O error */
    VIR_CONNECT_CLOSE_REASON_EOF = 1 /* End-of-file from server */
    VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2 /* Keepalive timer triggered */
    VIR_CONNECT_CLOSE_REASON_CLIENT = 3 /* Client requested it */
    VIR_CONNECT_CLOSE_REASON_LAST = 4
};


Structure virTypedParameter

struct _virTypedParameter {
    char field[VIR_TYPED_PARAM_FIELD_LENGTH]	field	: parameter name
    int	type	: parameter type, virTypedParameterType
    union	value	: parameter value
} virTypedParameter;


Enum virTypedParameterFlags

enum virTypedParameterFlags {
    VIR_TYPED_PARAM_STRING_OKAY = 4
};


Typedef virTypedParameterPtr

virTypedParameter * virTypedParameterPtr;

a pointer to a virTypedParameter structure.


Enum virTypedParameterType

enum virTypedParameterType {
    VIR_TYPED_PARAM_INT = 1 /* integer case */
    VIR_TYPED_PARAM_UINT = 2 /* unsigned integer case */
    VIR_TYPED_PARAM_LLONG = 3 /* long long case */
    VIR_TYPED_PARAM_ULLONG = 4 /* unsigned long long case */
    VIR_TYPED_PARAM_DOUBLE = 5 /* double case */
    VIR_TYPED_PARAM_BOOLEAN = 6 /* boolean(character) case */
    VIR_TYPED_PARAM_STRING = 7 /* string case */
    VIR_TYPED_PARAM_LAST = 8
};



virTypedParamsAddBoolean ()

int	virTypedParamsAddBoolean	(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
int value)

Adds new parameter called @name with boolean type and sets its value to @value. If @params array points to NULL or to a space that is not large enough to accommodate the new parameter (@maxparams < @nparams + 1), the function allocates more space for it and updates @maxparams. On success, @nparams is incremented by one. The function fails with VIR_ERR_INVALID_ARG error if the parameter already exists in @params.

params:pointer to the array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to find
value:the value to store into the new parameter
Returns:0 on success, -1 on error.

virTypedParamsAddDouble ()

int	virTypedParamsAddDouble		(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
double value)

Adds new parameter called @name with double type and sets its value to @value. If @params array points to NULL or to a space that is not large enough to accommodate the new parameter (@maxparams < @nparams + 1), the function allocates more space for it and updates @maxparams. On success, @nparams is incremented by one. The function fails with VIR_ERR_INVALID_ARG error if the parameter already exists in @params.

params:pointer to the array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to find
value:the value to store into the new parameter
Returns:0 on success, -1 on error.

virTypedParamsAddFromString ()

int	virTypedParamsAddFromString	(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
int type,
const char * value)

Adds new parameter called @name with the requested @type and parses its value from the @value string. If the requested type is string, the function creates its own copy of the @value string, which needs to be freed using virTypedParamsFree or virTypedParamsClear. If @params array points to NULL or to a space that is not large enough to accommodate the new parameter (@maxparams < @nparams + 1), the function allocates more space for it and updates @maxparams. On success, @nparams is incremented by one. The function fails with VIR_ERR_INVALID_ARG error if the parameter already exists in @params.

params:pointer to the array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to find
type:type of the parameter
value:the value to store into the new parameter encoded as a string
Returns:0 on success, -1 on error.

virTypedParamsAddInt ()

int	virTypedParamsAddInt		(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
int value)

Adds new parameter called @name with int type and sets its value to @value. If @params array points to NULL or to a space that is not large enough to accommodate the new parameter (@maxparams < @nparams + 1), the function allocates more space for it and updates @maxparams. On success, @nparams is incremented by one. The function fails with VIR_ERR_INVALID_ARG error if the parameter already exists in @params.

params:pointer to the array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to find
value:the value to store into the new parameter
Returns:0 on success, -1 on error.

virTypedParamsAddLLong ()

int	virTypedParamsAddLLong		(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
long long value)

Adds new parameter called @name with long long int type and sets its value to @value. If @params array points to NULL or to a space that is not large enough to accommodate the new parameter (@maxparams < @nparams + 1), the function allocates more space for it and updates @maxparams. On success, @nparams is incremented by one. The function fails with VIR_ERR_INVALID_ARG error if the parameter already exists in @params.

params:pointer to the array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to find
value:the value to store into the new parameter
Returns:0 on success, -1 on error.

virTypedParamsAddString ()

int	virTypedParamsAddString		(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
const char * value)

Adds new parameter called @name with char * type and sets its value to @value. The function creates its own copy of @value string, which needs to be freed using virTypedParamsFree or virTypedParamsClear. If @params array points to NULL or to a space that is not large enough to accommodate the new parameter (@maxparams < @nparams + 1), the function allocates more space for it and updates @maxparams. On success, @nparams is incremented by one. The function fails with VIR_ERR_INVALID_ARG error if the parameter already exists in @params.

params:pointer to the array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to find
value:the value to store into the new parameter
Returns:0 on success, -1 on error.

virTypedParamsAddStringList ()

int	virTypedParamsAddStringList	(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
const char ** values)

Packs NULL-terminated list of strings @values into @params under the key @name.

params:array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to store values to
values:the values to store into the new parameters
Returns:0 on success, -1 on error.

virTypedParamsAddUInt ()

int	virTypedParamsAddUInt		(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
unsigned int value)

Adds new parameter called @name with unsigned int type and sets its value to @value. If @params array points to NULL or to a space that is not large enough to accommodate the new parameter (@maxparams < @nparams + 1), the function allocates more space for it and updates @maxparams. On success, @nparams is incremented by one. The function fails with VIR_ERR_INVALID_ARG error if the parameter already exists in @params.

params:pointer to the array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to find
value:the value to store into the new parameter
Returns:0 on success, -1 on error.

virTypedParamsAddULLong ()

int	virTypedParamsAddULLong		(virTypedParameterPtr * params, 
int * nparams,
int * maxparams,
const char * name,
unsigned long long value)

Adds new parameter called @name with unsigned long long type and sets its value to @value. If @params array points to NULL or to a space that is not large enough to accommodate the new parameter (@maxparams < @nparams + 1), the function allocates more space for it and updates @maxparams. On success, @nparams is incremented by one. The function fails with VIR_ERR_INVALID_ARG error if the parameter already exists in @params.

params:pointer to the array of typed parameters
nparams:number of parameters in the @params array
maxparams:maximum number of parameters that can be stored in @params array without allocating more memory
name:name of the parameter to find
value:the value to store into the new parameter
Returns:0 on success, -1 on error.

virTypedParamsClear ()

void	virTypedParamsClear		(virTypedParameterPtr params, 
int nparams)

Frees all memory used by string parameters. The memory occupied by @params is not freed; use virTypedParamsFree if you want it to be freed too.

params:the array of typed parameters
nparams:number of parameters in the @params array

virTypedParamsFree ()

void	virTypedParamsFree		(virTypedParameterPtr params, 
int nparams)

Frees all memory used by string parameters and the memory occupied by @params.

params:the array of typed parameters
nparams:number of parameters in the @params array

virTypedParamsGet ()

virTypedParameterPtr	virTypedParamsGet	(virTypedParameterPtr params, 
int nparams,
const char * name)

Finds typed parameter called @name.

params:array of typed parameters
nparams:number of parameters in the @params array
name:name of the parameter to find
Returns:pointer to the parameter or NULL if it does not exist in @params. This function does not raise an error, even when returning NULL.

virTypedParamsGetBoolean ()

int	virTypedParamsGetBoolean	(virTypedParameterPtr params, 
int nparams,
const char * name,
int * value)

Finds typed parameter called @name and store its boolean value in @value. The function fails with VIR_ERR_INVALID_ARG error if the parameter does not have the expected type. By passing NULL as @value, the function may be used to check presence and type of the parameter.

params:array of typed parameters
nparams:number of parameters in the @params array
name:name of the parameter to find
value:where to store the parameter's value
Returns:1 on success, 0 when the parameter does not exist in @params, or -1 on error.

virTypedParamsGetDouble ()

int	virTypedParamsGetDouble		(virTypedParameterPtr params, 
int nparams,
const char * name,
double * value)

Finds typed parameter called @name and store its double value in @value. The function fails with VIR_ERR_INVALID_ARG error if the parameter does not have the expected type. By passing NULL as @value, the function may be used to check presence and type of the parameter.

params:array of typed parameters
nparams:number of parameters in the @params array
name:name of the parameter to find
value:where to store the parameter's value
Returns:1 on success, 0 when the parameter does not exist in @params, or -1 on error.

virTypedParamsGetInt ()

int	virTypedParamsGetInt		(virTypedParameterPtr params, 
int nparams,
const char * name,
int * value)

Finds typed parameter called @name and store its int value in @value. The function fails with VIR_ERR_INVALID_ARG error if the parameter does not have the expected type. By passing NULL as @value, the function may be used to check presence and type of the parameter.

params:array of typed parameters
nparams:number of parameters in the @params array
name:name of the parameter to find
value:where to store the parameter's value
Returns:1 on success, 0 when the parameter does not exist in @params, or -1 on error.

virTypedParamsGetLLong ()

int	virTypedParamsGetLLong		(virTypedParameterPtr params, 
int nparams,
const char * name,
long long * value)

Finds typed parameter called @name and store its long long int value in @value. The function fails with VIR_ERR_INVALID_ARG error if the parameter does not have the expected type. By passing NULL as @value, the function may be used to check presence and type of the parameter.

params:array of typed parameters
nparams:number of parameters in the @params array
name:name of the parameter to find
value:where to store the parameter's value
Returns:1 on success, 0 when the parameter does not exist in @params, or -1 on error.

virTypedParamsGetString ()

int	virTypedParamsGetString		(virTypedParameterPtr params, 
int nparams,
const char * name,
const char ** value)

Finds typed parameter called @name and store its char * value in @value. The function does not create a copy of the string and the caller must not free the string @value points to. The function fails with VIR_ERR_INVALID_ARG error if the parameter does not have the expected type. By passing NULL as @value, the function may be used to check presence and type of the parameter.

params:array of typed parameters
nparams:number of parameters in the @params array
name:name of the parameter to find
value:where to store the parameter's value
Returns:1 on success, 0 when the parameter does not exist in @params, or -1 on error.

virTypedParamsGetUInt ()

int	virTypedParamsGetUInt		(virTypedParameterPtr params, 
int nparams,
const char * name,
unsigned int * value)

Finds typed parameter called @name and store its unsigned int value in @value. The function fails with VIR_ERR_INVALID_ARG error if the parameter does not have the expected type. By passing NULL as @value, the function may be used to check presence and type of the parameter.

params:array of typed parameters
nparams:number of parameters in the @params array
name:name of the parameter to find
value:where to store the parameter's value
Returns:1 on success, 0 when the parameter does not exist in @params, or -1 on error.

virTypedParamsGetULLong ()

int	virTypedParamsGetULLong		(virTypedParameterPtr params, 
int nparams,
const char * name,
unsigned long long * value)

Finds typed parameter called @name and store its unsigned long long int value in @value. The function fails with VIR_ERR_INVALID_ARG error if the parameter does not have the expected type. By passing NULL as @value, the function may be used to check presence and type of the parameter.

params:array of typed parameters
nparams:number of parameters in the @params array
name:name of the parameter to find
value:where to store the parameter's value
Returns:1 on success, 0 when the parameter does not exist in @params, or -1 on error.