libvirt-php: Developer's API Reference guide
Description: libvirt, virtualization, virtualization API

# Developer's API Reference guide

### Functions

    Total number of functions: 32. Functions supported are:

    	set_logfile($filename, $maxsize)

    	translate_counter_type($type)

    	tokenize($string, $delim)

    	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)

    	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_node_string_from_xpath($xml, $xpath)

    	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($conn, $name, $memMB, $maxmemMB, $arch, $uuid, $vCpus, $iso_image, $disks, $numDisks, $networks, $numNetworks, $domain_flags)

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

    	free_resources_on_connection($conn)

### `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, $delim)

[Since version 0.4.9]

Function to tokenize string into tokens by delimiter $delim.

`@string [string]`: | input string
`@delim [string]`: | string used as delimiter
`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

### `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. Note that the result of @xpath is viewed as "string(@xpath)" which may not be what you want. See get_node_string_from_xpath()..

`@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_node_string_from_xpath`

    get_node_string_from_xpath($xml, $xpath)

[Since version 0.5.5]

Evaluate @xpath and convert retuned node to string. The difference to get_string_from_xpath() is that get_string_from_xpath() puts implicit string() around @xpath and get_node_string_from_xpath() evaluates @xpath as is and only then translates xml node into a C string..

`@xml [string]`: | input XML document
`@xpath [string]`: | xPath expression to find nodes in the XML document
`Returns`: | : stringified result of @xpath evaluation

### `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($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.

`@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

### `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