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

## 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 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 /* 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. */
    };

### 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
    };

### Function type virFreeCallback

    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.