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

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