Developer's API Reference guide

Functions

Total number of functions: 32. Functions supported are:

get_datetime()
set_logfile($filename, $maxsize)
translate_counter_type($type)
tokenize($string, $by)
free_tokens($t)
resource_change_counter($type, $conn, $mem, $inc)
get_feature_binary($name)
has_builtin($name)
set_error($msg)
set_vnc_location($msg)
set_error_if_unset($msg)
reset_error()
free_resource($type, $mem)
free_resources_on_connection($conn)
check_resource_allocation($conn, $type, $memp)
count_resources($type)
size_def_to_mbytes($arg)
is_local_connection($conn)
get_string_from_xpath($xml, $xpath, $val, $retVal)
get_array_from_xpath($xml, $xpath, $num)
dec_to_bin($decimal, $binary)
get_subnet_bits($ip)
get_next_free_numeric_value($res, $xpath)
connection_get_domain_type($conn, $arch)
connection_get_emulator($conn, $arch)
connection_get_arch($conn)
generate_uuid_any()
generate_uuid($conn)
get_disk_xml($size, $path, $driver, $dev, $disk_flags)
get_network_xml($mac, $network, $model)
installation_get_xml($step, $conn, $name, $memMB, $maxmemMB, $arch, $uuid, $vCpus, $iso_image, $disks, $numDisks, $networks, $numNetworks, $domain_flags)
streamSink($st, $bytes, $nbytes, $opaque)

get_datetime

get_datetime()

[Since version 0.4.2]

Function can be used to get date and time in the `YYYY-mm-dd HH:mm:ss` format, internally used for logging when debug logging is enabled using libvirt_set_logfile() API function..

Returns: : Date/time string in `YYYY-mm-dd HH:mm:ss` format

set_logfile

set_logfile($filename, $maxsize)

[Since version 0.4.2]

Function to set the log file. You can set log file to NULL to disable logging (default). Useful for debugging purposes..

@filename [string]: name of log file or NULL to disable
@maxsize [long]: integer value of maximum file size, file will be truncated after reaching max file size. Value is set in KiB.
Returns: : 0 on success, -errno otherwise

translate_counter_type

translate_counter_type($type)

[Since version 0.4.2]

Function to translate the counter type into the string format.

@type [int]: integer identifier of the counter type
Returns: : string interpretation of the counter type

tokenize

tokenize($string, $by)

[Since version 0.4.9]

Function to tokenize string into tokens by delimiter $by.

@string [string]: input string
@by [string]: string used as delimited
Returns: : tTokenizer structure

free_tokens

free_tokens($t)

[Since version 0.4.9]

Function to free tokens allocated by tokenize function.

@t [tTokenizer]: tokenizer structure previously allocated by tokenize function
Returns: : none

resource_change_counter

resource_change_counter($type, $conn, $mem, $inc)

[Since version 0.4.2]

Function to increment (inc = 1) / decrement (inc = 0) the resource pointers count including the memory location.

@type [int]: type of resource (INT_RESOURCE_x defines where x can be { CONNECTION | DOMAIN | NETWORK | NODEDEV | STORAGEPOOL | VOLUME | SNAPSHOT | STREAM })
@conn [virConnectPtr]: libvirt connection pointer associated with the resource, NULL for libvirt connection objects
@mem [pointer]: Pointer to memory location for the resource. Will be converted to appropriate uint for the arch.
@inc [int/bool]: Increment the counter (1 = add memory location) or decrement the counter (0 = remove memory location) from entries.
Returns: : 0 on success, -errno otherwise

get_feature_binary

get_feature_binary($name)

[Since version 0.4.1(-3)]

Function to get the existing feature binary for the specified feature, e.g. screenshot feature.

@name [string]: name of the feature to check against
Returns: : Existing and executable binary name or NULL value

has_builtin

has_builtin($name)

[Since version 0.4.5]

Function to get the information whether feature could be used as a built-in feature or not.

@name [string]: name of the feature to check against
Returns: : 1 if feature has a builtin fallback to be used or 0 otherwise

set_error

set_error($msg)

[Since version 0.4.1(-1)]

This private function is used to set the error string to the library. This string can be obtained by libvirt_get_last_error() from the PHP application..

@msg [string]: error message string
Returns: : None

set_vnc_location

set_vnc_location($msg)

[Since version 0.4.5]

This private function is used to set the VNC location for the newly started installation.

@msg [string]: vnc location string
Returns: : None

set_error_if_unset

set_error_if_unset($msg)

[Since version 0.4.2]

Function to set the error only if no other error is set yet.

@msg [string]: error message string
Returns: : None

reset_error

reset_error()

[Since version 0.4.2]

Function to reset the error string set by set_error(). Same as set_error(NULL)..

Returns: : None

free_resource

free_resource($type, $mem)

[Since version 0.4.2]

Function is used to free the the internal libvirt-php resource identified by it's type and memory location.

@type [int]: type of the resource to be freed, INT_RESOURCE_x where x can be { CONNECTION | DOMAIN | NETWORK | NODEDEV | STORAGEPOOL | VOLUME | SNAPSHOT }
@mem [uint]: memory location of the resource to be freed
Returns: : None

free_resources_on_connection

free_resources_on_connection($conn)

[Since version 0.4.2]

Function is used to free all the resources assigned to the connection identified by conn.

@conn [virConnectPtr]: libvirt connection pointer
Returns: : None

check_resource_allocation

check_resource_allocation($conn, $type, $memp)

[Since version 0.4.2]

Function is used to check whether the resource identified by type and memory is allocated for connection conn or not.

@conn [virConnectPtr]: libvirt connection pointer
@type [int]: type of the counter to be checked, please see free_resource() API for possible values
@memp [pointer]: pointer to the memory
Returns: : 1 if resource is allocated, 0 otherwise

count_resources

count_resources($type)

[Since version 0.4.2]

Function counts the internal resources of module instance.

@type [int]: integer interpretation of the type, see free_resource() API function for possible values
Returns: : number of resources already used

size_def_to_mbytes

size_def_to_mbytes($arg)

[Since version 0.4.5]

Function is used to translate the string size representation to the number of MBytes, used e.g. for domain installation.

@arg [string]: input string to be converted
Returns: : number of megabytes extracted from the input string

is_local_connection

is_local_connection($conn)

[Since version 0.4.5]

Function is used to check whether the connection is the connection to the local hypervisor or to remote hypervisor.

@conn [virConnectPtr]: libvirt connection pointer
Returns: : 1 (TRUE) for local connection, 0 (FALSE) for remote connection

get_string_from_xpath

get_string_from_xpath($xml, $xpath, $val, $retVal)

[Since version 0.4.1(-1)]

Function is used to get the XML xPath expression from the XML document. This can be added to val array if not NULL..

@xml [string]: input XML document
@xpath [string]: xPath expression to find nodes in the XML document
@val [array]: Zend array resource to put data to
@retVal [int]: return value of the parsing
Returns: : string containing data of last match found

get_array_from_xpath

get_array_from_xpath($xml, $xpath, $num)

[Since version 0.4.9]

Function is used to get all XPath elements from XML and return in array (character pointer).

@xml [string]: input XML document
@xpath [string]: xPath expression to find nodes in the XML document
@num [int *]: number of elements
Returns: : pointer to char ** if successful or NULL for error

dec_to_bin

dec_to_bin($decimal, $binary)

[Since version 0.4.1(-1)]

Function dec_to_bin() converts the unsigned long long decimal (used e.g. for IPv4 address) to it's binary representation.

@decimal [int]: decimal value to be converted to binary interpretation
@binary [string]: output binary string with the binary interpretation
Returns: : None

get_subnet_bits

get_subnet_bits($ip)

[Since version 0.4.1(-1)]

Function is used to get number of bits used by subnet determined by IP. Useful to get the CIDR IPv4 address representation.

@ip [string]: IP address to calculate subnet bits from
Returns: : number of bits used by subnet mask

get_next_free_numeric_value

get_next_free_numeric_value($res, $xpath)

[Since version 0.4.2]

Function is used to get the next free slot to be used for adding new NIC device or others.

@res [virDomainPtr]: standard libvirt domain pointer identified by virDomainPtr
@xpath [string]: xPath expression of items to get the next free value of
Returns: : next free numeric value

connection_get_domain_type

connection_get_domain_type($conn, $arch)

[Since version 0.4.5]

Function is required for functions that get the emulator for specific libvirt connection.

@conn [virConnectPtr]: libvirt connection pointer of connection to get emulator for
@arch [string]: optional architecture string, can be NULL to get default
Returns: : path to the emulator

connection_get_emulator

connection_get_emulator($conn, $arch)

[Since version 0.4.5]

Function is required for functions that get the emulator for specific libvirt connection.

@conn [virConnectPtr]: libvirt connection pointer of connection to get emulator for
@arch [string]: optional architecture string, can be NULL to get default
Returns: : path to the emulator

connection_get_arch

connection_get_arch($conn)

[Since version 0.4.5]

Function is required for functions that get the architecture for specific libvirt connection.

@conn [virConnectPtr]: libvirt connection pointer of connection to get architecture for
Returns: : path to the emulator

generate_uuid_any

generate_uuid_any()

[Since version 0.4.5]

Function is used to generate a new random UUID string.

Returns: : a new random UUID string

generate_uuid

generate_uuid($conn)

[Since version 0.4.5]

Function is used to generate a new unused UUID string.

@conn [virConnectPtr]: libvirt connection pointer
Returns: : a new unused random UUID string

get_disk_xml

get_disk_xml($size, $path, $driver, $dev, $disk_flags)

[Since version 0.4.5]

Function is used to format single disk XML.

@size [unsigned long long]: size of disk for generating a new one (can be -1 not to generate even if it doesn't exist)
@path [string]: path to the storage on the host system
@driver [string]: driver to be used to access the disk
@dev [string]: device to be presented to the guest
@disk_flags [int]: disk type, VIR_DOMAIN_DISK_FILE or VIR_DOMAIN_DISK_BLOCK
Returns: : XML output for the disk

get_network_xml

get_network_xml($mac, $network, $model)

[Since version 0.4.5]

Function is used to format single network interface XML.

@mac [string]: MAC address of the new interface
@network [string]: network name
@model [string]: optional model name
Returns: : XML output for the network interface

installation_get_xml

installation_get_xml($step, $conn, $name, $memMB, $maxmemMB, $arch, $uuid, $vCpus, $iso_image, $disks, $numDisks, $networks, $numNetworks, $domain_flags)

[Since version 0.4.5]

Function is used to generate the installation XML description to install a new domain.

@step [int]: number of step for XML output (1 or 2)
@conn [virConnectPtr]: libvirt connection pointer
@name [string]: name of the new virtual machine
@memMB [int]: memory in Megabytes
@maxmemMB [int]: maximum memory in Megabytes
@arch [string]: architecture to be used for the new domain, may be NULL to use the hypervisor default
@uuid [string]: UUID to be used or NULL to generate a new one
@vCpus [int]: number of virtual CPUs for the domain
@iso_image [string]: ISO image for the installation
@disks [tVMDisk]: disk structure with all the disks defined
@numDisks [int]: number of disks in the disk structure
@networks [tVMNetwork]: network structure with all the networks defined
@numNetworks [int]: number of networks in the network structure
@domain_flags [int]: flags for the domain installation
Returns: : full XML output for installation

streamSink

streamSink($st, $bytes, $nbytes, $opaque)

[Since version 0.4.5]

Function to write stream to file, borrowed from libvirt.

@st [virStreamPtr]: stream pointer
@bytes [void *]: buffer array
@nbytes [int]: size of buffer
@opaque [void *]: used for file descriptor
Returns: : write() error code as it's calling write