Module libvirt-common from libvirt

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

Table of Contents

Macros

#define LIBVIR_CHECK_VERSION
#define LIBVIR_VERSION_NUMBER
#define VIR_TYPED_PARAM_FIELD_LENGTH

Types

typedef enum virConnectCloseReason
typedef struct _virTypedParameter virTypedParameter
typedef enum virTypedParameterFlags
typedef virTypedParameter * virTypedParameterPtr
typedef enum virTypedParameterType

Functions

typedef virFreeCallback
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

Macros

LIBVIR_CHECK_VERSION

#define LIBVIR_CHECK_VERSION

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

LIBVIR_VERSION_NUMBER

#define LIBVIR_VERSION_NUMBER

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

VIR_TYPED_PARAM_FIELD_LENGTH

#define VIR_TYPED_PARAM_FIELD_LENGTH

Macro providing the field length of virTypedParameter name

Types

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
}

virTypedParameter

struct virTypedParameter {
char field[VIR_TYPED_PARAM_FIELD_LENGTH] field
parameter name
int type
parameter type, virTypedParameterType
union {
int i
type is INT
unsigned int ui
type is UINT
long long int l
type is LLONG
unsigned long long int ul
type is ULLONG
double d
type is DOUBLE
char b
type is BOOLEAN
char * s
type is STRING, may not be NULL
} value
parameter value
}

virTypedParameterFlags

enum virTypedParameterFlags {
VIR_TYPED_PARAM_STRING_OKAY = 4
1 << 0 is reserved for virDomainModificationImpact 1 << 1 is reserved for virDomainModificationImpact Older servers lacked the ability to handle string typed parameters. Attempts to set a string parameter with an older server will fail at the client, but attempts to retrieve parameters must not return strings from a new server to an older client, so this flag exists to identify newer clients to newer servers. This flag is automatically set when needed, so the user does not have to worry about it; however, manually setting the flag can be used to reject servers that cannot return typed strings, even if no strings would be returned.
}

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
}

Functions

virFreeCallback

typedef void	(*virFreeCallback		)	(void * opaque)

Type for a callback cleanup function to be paired with a callback. This function will be called as a final chance to clean up the @opaque registered with the primary callback, at the time when the primary callback is deregistered.

It is forbidden to call any other libvirt APIs from an implementation of this callback, since it can be invoked from a context which is not re-entrant safe. Failure to abide by this requirement may lead to application deadlocks or crashes.

opaque
opaque user data provided at registration

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.