cairo-dock-packages.h File Reference

Data Structures
struct	_CairoDockPackage
	Definition of a generic package. More...

Macros
#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
gboolean	cairo_dock_download_file (const gchar *cURL, const gchar *cLocalPath)
gchar *	cairo_dock_download_file_in_tmp (const gchar *cURL)
gchar *	cairo_dock_download_archive (const gchar *cURL, const gchar *cExtractTo)
GldiTask *	cairo_dock_download_file_async (const gchar *cURL, const gchar *cLocalPath, GFunc pCallback, gpointer data)
gchar *	cairo_dock_get_url_data_with_post (const gchar *cURL, gboolean bGetOutputHeaders, GError **erreur, const gchar *cFirstProperty,...)
GldiTask *	cairo_dock_get_url_data_async (const gchar *cURL, 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)
GldiTask *	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 download a file or make a request to a server.

To get the list of available packages, use cairo_dock_list_packages, or its asynchronous version cairo_dock_list_packages_async. To access a package, use cairo_dock_get_package_path.

Macro Definition 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 (NULL if failed). It's an array of chars, possibly containing nul chars. Free it after using.

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

gboolean cairo_dock_download_file	(	const gchar *	cURL,
		const gchar *	cLocalPath
	)

Download a distant file into a given location.

Parameters

cURL	adress of the file.
cLocalPath	a local path where to store the file.

Returns

TRUE on success, else FALSE..

gchar* cairo_dock_download_file_in_tmp

(

const gchar *

cURL

)

Download a distant file as a temporary file.

Parameters

cURL	adress of the file.

Returns

the local path of the file on success, else NULL. Free the string after using it.

gchar* cairo_dock_download_archive	(	const gchar *	cURL,
		const gchar *	cExtractTo
	)

Download an archive and extract it into a given folder.

Parameters

cURL	adress of the file.
cExtractTo	folder where to extract the archive (the archive is deleted then).

Returns

the local path of the file on success, else NULL. Free the string after using it.

GldiTask* cairo_dock_download_file_async	(	const gchar *	cURL,
		const gchar *	cLocalPath,
		GFunc	pCallback,
		gpointer	data
	)

Asynchronously download a distant file into a given location. 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

cURL	adress of the file.
cLocalPath	a local path where to store the file, or NULL for a temporary file.
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_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	the URL request
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 (NULL if failed). It's an array of chars, possibly containing nul chars. Free it after using.

GldiTask* cairo_dock_get_url_data_async	(	const gchar *	cURL,
		GFunc	pCallback,
		gpointer	data
	)

Asynchronously retrieve the content of a distant URL. 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

cURL	distant adress to get data from.
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.

GldiTask* 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.