cairo-dock-packages.h File Reference

Data Structures
struct	_CairoDockPackage
	Definition of a generic package. More...
Defines
#define	cairo_dock_get_url_data(cURL, erreur)
Typedefs
typedef void(*	CairoDockGetPackagesFunc )(GHashTable *pPackagesTable, gpointer data)
	Prototype of the function called when the list of packages is available. Use g_hash_table_ref if you want to keep the table outside of this function.
Enumerations
enum	CairoDockPackageType {   CAIRO_DOCK_LOCAL_PACKAGE,   CAIRO_DOCK_USER_PACKAGE,   CAIRO_DOCK_DISTANT_PACKAGE,   CAIRO_DOCK_NEW_PACKAGE,   CAIRO_DOCK_UPDATED_PACKAGE,   CAIRO_DOCK_ANY_PACKAGE }
	Types of packagess. More...
Functions
gchar *	cairo_dock_download_file (const gchar *cServerAdress, const gchar *cDistantFilePath, const gchar *cDistantFileName, const gchar *cExtractTo, GError **erreur)
CairoDockTask *	cairo_dock_download_file_async (const gchar *cServerAdress, const gchar *cDistantFilePath, const gchar *cDistantFileName, const gchar *cExtractTo, GFunc pCallback, gpointer data)
gchar *	cairo_dock_get_distant_file_content (const gchar *cServerAdress, const gchar *cDistantFilePath, const gchar *cDistantFileName, GError **erreur)
gchar *	cairo_dock_get_url_data_with_post (const gchar *cURL, gboolean bGetOutputHeaders, GError **erreur, const gchar *cFirstProperty,...)
CairoDockTask *	cairo_dock_get_distant_file_content_async (const gchar *cServerAdress, const gchar *cDistantFilePath, const gchar *cDistantFileName, GFunc pCallback, gpointer data)
void	cairo_dock_free_package (CairoDockPackage *pPackage)
GHashTable *	cairo_dock_list_packages (const gchar *cSharePackagesDir, const gchar *cUserPackagesDir, const gchar *cDistantPackagesDir, GHashTable *pTable)
CairoDockTask *	cairo_dock_list_packages_async (const gchar *cSharePackagesDir, const gchar *cUserPackagesDir, const gchar *cDistantPackagesDir, CairoDockGetPackagesFunc pCallback, gpointer data, GHashTable *pTable)
gchar *	cairo_dock_get_package_path (const gchar *cPackageName, const gchar *cSharePackagesDir, const gchar *cUserPackagesDir, const gchar *cDistantPackagesDir, CairoDockPackageType iGivenType)

---

Detailed Description

This class provides a convenient way to deal with packages. A Package is a tarball (tar.gz) of a folder, located on a distant server, that can be installed locally. Packages are listed on the server in a file named "list.conf". It's a group-key file starting with "#!CD" on the first line; each package is described in its own group. Packages are stored on the server in a folder that has the same name, and contains the tarball, a "readme" file, and a "preview" file.

The class offers a high level of abstraction that allows to manipulate packages without having to care their location, version, etc. It also provides convenient utility functions to get remote data.

To get the list of available packages, use cairo_dock_list_packages, or its asynchronous version cairo_dock_list_packages_async. To get the path of a package, use cairo_dock_get_package_path; it will look for the the best

---

Define Documentation

#define cairo_dock_get_url_data	(		cURL,
			erreur
	)

Retrieve the data of a distant URL.

Parameters:

cURL	distant adress to get data from.
erreur	an error.

Returns:

the data. Free the string after using it.

---

Enumeration Type Documentation

enum CairoDockPackageType

Types of packagess.

Enumerator:

CAIRO_DOCK_LOCAL_PACKAGE	package installed as root on the machine (in a sub-folder /usr).
CAIRO_DOCK_USER_PACKAGE	package located in the user's home
CAIRO_DOCK_DISTANT_PACKAGE	package present on the server
CAIRO_DOCK_NEW_PACKAGE	package newly present on the server (for less than 1 month)
CAIRO_DOCK_UPDATED_PACKAGE	package present locally but with a more recent version on the server, or distant package that has been updated in the past month.
CAIRO_DOCK_ANY_PACKAGE	joker (the search path function will search locally first, and on the server then).

---

Function Documentation

gchar* cairo_dock_download_file	(	const gchar *	cServerAdress,
		const gchar *	cDistantFilePath,
		const gchar *	cDistantFileName,
		const gchar *	cExtractTo,
		GError **	erreur
	)

Download a distant file into a given folder, possibly extracting it.

Parameters:

cServerAdress	adress of the server.
cDistantFilePath	path of the file on the server.
cDistantFileName	name of the file.
cExtractTo	a local path where to extract the file, if this one is a .tar.gz/.tar.bz2/.tgz archive, or NULL.
erreur	an error.

Returns:

the local path of the downloaded file. If it was an archive, the path of the extracted file. Free the string after using it.

CairoDockTask* cairo_dock_download_file_async	(	const gchar *	cServerAdress,
		const gchar *	cDistantFilePath,
		const gchar *	cDistantFileName,
		const gchar *	cExtractTo,
		GFunc	pCallback,
		gpointer	data
	)

Asynchronously download a distant file into a given folder, possibly extracting it. This function is non-blocking, you'll get a CairoTask that you can discard at any time, and you'll get the path of the downloaded file as the first argument of the callback (the second being the data you passed to this function).

Parameters:

cServerAdress	adress of the server.
cDistantFilePath	path of the file on the server.
cDistantFileName	name of the file.
cExtractTo	a local path where to extract the file, if this one is a .tar.gz/.tar.bz2/.tgz archive, or NULL.
pCallback	function called when the download is finished. It takes the path of the downloaded file (it belongs to the task so don't free it) and the data you've set here.
data	data to be passed to the callback.

Returns:

the Task that is doing the job. Keep it and use cairo_dock_discard_task whenever you want to discard the download (for instance if the user cancels it), or cairo_dock_free_task inside your callback.

gchar* cairo_dock_get_distant_file_content	(	const gchar *	cServerAdress,
		const gchar *	cDistantFilePath,
		const gchar *	cDistantFileName,
		GError **	erreur
	)

Retrieve the content of a distant text file.

Parameters:

cServerAdress	adress of the server.
cDistantFilePath	path of the file on the server.
cDistantFileName	name of the file.
erreur	an error.

Returns:

the content of the file. Free the string after using it.

gchar* cairo_dock_get_url_data_with_post	(	const gchar *	cURL,
		gboolean	bGetOutputHeaders,
		GError **	erreur,
		const gchar *	cFirstProperty,
			...
	)

Retrieve the response of a POST request to a server.

Parameters:

cURL	URL of the server
bGetOutputHeaders	whether to retrieve the page's header.
erreur	an error.
cFirstProperty	first property of the POST data.
...	tuples of property and data to insert in POST data; the POST data will be formed with a=urlencode(b)&c=urlencode(d)&... End it with NULL.

Returns:

the data. Free the string after using it.

CairoDockTask* cairo_dock_get_distant_file_content_async	(	const gchar *	cServerAdress,
		const gchar *	cDistantFilePath,
		const gchar *	cDistantFileName,
		GFunc	pCallback,
		gpointer	data
	)

Asynchronously retrieve the content of a distant text file. This function is non-blocking, you'll get a CairoTask that you can discard at any time, and you'll get the content of the downloaded file as the first argument of the callback (the second being the data you passed to this function).

Parameters:

cServerAdress	adress of the server.
cDistantFilePath	path of the file on the server.
cDistantFileName	name of the file.
pCallback	function called when the download is finished. It takes the content of the downloaded file (it belongs to the task so don't free it) and the data you've set here.
data	data to be passed to the callback.

Returns:

the Task that is doing the job. Keep it and use cairo_dock_discard_task whenever you want to discard the download (for instance if the user cancels it), or cairo_dock_free_task inside your callback.

void cairo_dock_free_package

(

CairoDockPackage *

pPackage

)

Destroy a package and free all its allocated memory.

Parameters:

pPackage

the package.

GHashTable* cairo_dock_list_packages	(	const gchar *	cSharePackagesDir,
		const gchar *	cUserPackagesDir,
		const gchar *	cDistantPackagesDir,
		GHashTable *	pTable
	)

Get a list of packages from differente sources.

Parameters:

cSharePackagesDir	path of a local folder containg packages or NULL.
cUserPackagesDir	path of a user folder containg packages or NULL.
cDistantPackagesDir	path of a distant folder containg packages or NULL.
pTable	a table of packages previously retrieved, or NULL.

Returns:

a hash table of (name, _CairoDockPackage). Free it with g_hash_table_destroy when you're done with it.

CairoDockTask* cairo_dock_list_packages_async	(	const gchar *	cSharePackagesDir,
		const gchar *	cUserPackagesDir,
		const gchar *	cDistantPackagesDir,
		CairoDockGetPackagesFunc	pCallback,
		gpointer	data,
		GHashTable *	pTable
	)

Asynchronously get a list of packages from differente sources. This function is non-blocking, you'll get a CairoTask that you can discard at any time, and you'll get a hash-table of the packages as the first argument of the callback (the second being the data you passed to this function).

Parameters:

cSharePackagesDir	path of a local folder containg packages or NULL.
cUserPackagesDir	path of a user folder containg packages or NULL.
cDistantPackagesDir	path of a distant folder containg packages or NULL.
pCallback	function called when the listing is finished. It takes the hash-table of the found packages (it belongs to the task so don't free it) and the data you've set here.
data	data to be passed to the callback.
pTable	a table of packages previously retrieved, or NULL.

Returns:

the Task that is doing the job. Keep it and use cairo_dock_discard_task whenever you want to discard the download (for instance if the user cancels it), or cairo_dock_free_task inside your callback.

gchar* cairo_dock_get_package_path	(	const gchar *	cPackageName,
		const gchar *	cSharePackagesDir,
		const gchar *	cUserPackagesDir,
		const gchar *	cDistantPackagesDir,
		CairoDockPackageType	iGivenType
	)

Look for a package with a given name into differente sources. If the package is found on the server and is not present on the disk, or is not up to date, then it is downloaded and the local path is returned.

Parameters:

cPackageName	name of the package.
cSharePackagesDir	path of a local folder containing packages or NULL.
cUserPackagesDir	path of a user folder containing packages or NULL.
cDistantPackagesDir	path of a distant folder containg packages or NULL.
iGivenType	type of package, or CAIRO_DOCK_ANY_PACKAGE if any type of package should be considered.

Returns:

a newly allocated string containing the complete local path of the package. If the package is distant, it is downloaded and extracted into this folder.