inspect_get_icon

get the icon corresponding to this operating system

This function returns an icon corresponding to the inspected operating system. The icon is returned as a buffer containing a PNG image ( re-encoded to PNG if necessary).

If it was not possible to get an icon this function returns a zero-length (non-NULL) buffer. *Callers must check for this case*.

Libguestfs will start by looking for a file called /etc/favicon.png or C:\etc\favicon.png and if it has the correct format, the contents of this file will be returned. You can disable favicons by passing the optional favicon boolean as false (default is true).

If finding the favicon fails, then we look in other places in the guest for a suitable icon.

If the optional highquality boolean is true then only high quality icons are returned, which means only icons of high resolution with an alpha channel. The default (false) is to return any icon we can, even if it is of substandard quality.

Notes:

* Unlike most other inspection API calls, the guest’s disks must be mounted up before you call this, since it needs to read information from the guest filesystem during the call.

* Security: The icon data comes from the untrusted guest, and should be treated with caution. PNG files have been known to contain exploits. Ensure that libpng (or other relevant libraries) are fully up to date before trying to process or display the icon.

* The PNG image returned can be any size. It might not be square. Libguestfs tries to return the largest, highest quality icon available. The application must scale the icon to the required size.

* Extracting icons from Windows guests requires the external wrestool program from the icoutils package, and several programs (bmptopnm, pnmtopng, pamcut) from the netpbm package. These must be installed separately.

* Operating system icons are usually trademarks. Seek legal advice before using trademarks in applications.

Parameters:

Returns: