hildon-uri

hildon-uri

Synopsis

#define             HILDON_URI_ERROR
                    HildonURIAction;
enum                HildonURIActionType;
enum                HildonURIError;
GQuark              hildon_uri_error_quark              (void);
HildonURIAction*    hildon_uri_action_ref               (HildonURIAction *action);
void                hildon_uri_action_unref             (HildonURIAction *action);
HildonURIActionType hildon_uri_action_get_type          (HildonURIAction *action);
const gchar*        hildon_uri_action_get_name          (HildonURIAction *action);
const gchar*        hildon_uri_action_get_service       (HildonURIAction *action);
const gchar*        hildon_uri_action_get_method        (HildonURIAction *action);
const gchar*        hildon_uri_action_get_translation_domain
                                                        (HildonURIAction *action);
GSList*             hildon_uri_get_actions              (const gchar *scheme,
                                                         GError **error);
GSList*             hildon_uri_get_actions_by_uri       (const gchar *uri_str,
                                                         HildonURIActionType type,
                                                         GError **error);
void                hildon_uri_free_actions             (GSList *list);
gchar*              hildon_uri_get_scheme_from_uri      (const gchar *uri,
                                                         GError **error);
gboolean            hildon_uri_is_default_action        (HildonURIAction *action,
                                                         GError **error);
gboolean            hildon_uri_is_default_action_by_uri (const gchar *uri,
                                                         HildonURIAction *action,
                                                         GError **error);
HildonURIAction*    hildon_uri_get_default_action       (const gchar *scheme,
                                                         GError **error);
HildonURIAction*    hildon_uri_get_default_action_by_uri
                                                        (const gchar *uri,
                                                         GError **error);
gboolean            hildon_uri_set_default_action       (const gchar *scheme,
                                                         HildonURIAction *action,
                                                         GError **error);
gboolean            hildon_uri_set_default_action_by_uri
                                                        (const gchar *uri_str,
                                                         HildonURIAction *action,
                                                         GError **error);
gboolean            hildon_uri_open                     (const gchar *uri,
                                                         HildonURIAction *action,
                                                         GError **error);

Description

Details

HILDON_URI_ERROR

#define HILDON_URI_ERROR hildon_uri_error_quark()


HildonURIAction

typedef struct _HildonURIAction HildonURIAction;


enum HildonURIActionType

typedef enum {
	HILDON_URI_ACTION_NORMAL,
	HILDON_URI_ACTION_NEUTRAL,
	HILDON_URI_ACTION_FALLBACK,
} HildonURIActionType;

HILDON_URI_ACTION_NORMAL This is the default and it has no special meaning or value.
HILDON_URI_ACTION_NEUTRAL This type of action applies to ALL mime types, even if the mime type is unknown.
HILDON_URI_ACTION_FALLBACK This type of action is used exclusively when the mime type is unknown.

enum HildonURIError

typedef enum { 
	HILDON_URI_INVALID_URI,
	HILDON_URI_INVALID_ACTION,
	HILDON_URI_INVALID_SCHEME,
	HILDON_URI_NO_DEFAULT_ACTION,
	HILDON_URI_OPEN_FAILED,
	HILDON_URI_SAVE_FAILED,
	HILDON_URI_DBUS_FAILED,
	HILDON_URI_NO_ACTIONS
} HildonURIError;


hildon_uri_error_quark ()

GQuark              hildon_uri_error_quark              (void);

Returns :

hildon_uri_action_ref ()

HildonURIAction*    hildon_uri_action_ref               (HildonURIAction *action);

Increments the object's reference count.

Return: The original pointer action.

action : A HildonURIAction pointer.
Returns :

hildon_uri_action_unref ()

void                hildon_uri_action_unref             (HildonURIAction *action);

Decrements the object's reference count. If the count happens to be < 1 after the decrement, action is freed.

action : A HildonURIAction pointer.

hildon_uri_action_get_type ()

HildonURIActionType hildon_uri_action_get_type          (HildonURIAction *action);

This returns the type of the action.

Return: A HildonURIActionType associated with the action.

action : A HildonURIAction pointer.
Returns :

hildon_uri_action_get_name ()

const gchar*        hildon_uri_action_get_name          (HildonURIAction *action);

This returns the name associated with an action. The name is the detailed description of the action. For example, if you are presenting a list of actions for the user to choose what to do with a URI, the name is what represents this action.

Return: A const gchar pointer to the name associated with the action.

action : A HildonURIAction pointer.
Returns :

hildon_uri_action_get_service ()

const gchar*        hildon_uri_action_get_service       (HildonURIAction *action);

This returns the service associated with an action. The service is the D-Bus service that will be used when opening a URI.

Return: A const gchar pointer to the service associated with the action.

action : A HildonURIAction pointer.
Returns :

hildon_uri_action_get_method ()

const gchar*        hildon_uri_action_get_method        (HildonURIAction *action);

This returns the method associated with an action. The method is the D-Bus method that will be used when opening a URI.

Return: A const gchar pointer to the method associated with the action.

action : A HildonURIAction pointer.
Returns :

hildon_uri_action_get_translation_domain ()

const gchar*        hildon_uri_action_get_translation_domain
                                                        (HildonURIAction *action);

This returns the translation domain associated with an action.

Return: A const gchar pointer to the translation domain associated with the action.

action : A HildonURIAction pointer.
Returns :

hildon_uri_get_actions ()

GSList*             hildon_uri_get_actions              (const gchar *scheme,
                                                         GError **error);

scheme :
error :
Returns :

hildon_uri_get_actions_by_uri ()

GSList*             hildon_uri_get_actions_by_uri       (const gchar *uri_str,
                                                         HildonURIActionType type,
                                                         GError **error);

uri_str :
type :
error :
Returns :

hildon_uri_free_actions ()

void                hildon_uri_free_actions             (GSList *list);

The GSlist is freed and all data members in the list are freed too.

list : A GSList pointer.

hildon_uri_get_scheme_from_uri ()

gchar*              hildon_uri_get_scheme_from_uri      (const gchar *uri,
                                                         GError **error);

This returns the scheme part of uri. An example of a scheme would be "http", "callto", "mailto", etc.

If NULL is returned and error is non-NULL, it will hold the error that occurred while trying to obtain the scheme.

Return: A newly allocated gchar pointer which must be freed with g_free().

uri : A const gchar pointer to a URI.
error : The address of a pointer to a GError structure. This is optional and can be NULL.
Returns :

hildon_uri_is_default_action ()

gboolean            hildon_uri_is_default_action        (HildonURIAction *action,
                                                         GError **error);

action :
error :
Returns :

hildon_uri_is_default_action_by_uri ()

gboolean            hildon_uri_is_default_action_by_uri (const gchar *uri,
                                                         HildonURIAction *action,
                                                         GError **error);

uri :
action :
error :
Returns :

hildon_uri_get_default_action ()

HildonURIAction*    hildon_uri_get_default_action       (const gchar *scheme,
                                                         GError **error);

This returns the HildonURIAction which is the default for a scheme. The scheme can be obtained from a URI by calling hildon_uri_get_scheme_from_uri().

If NULL is returned and error is NULL then there is no default HildonURIAction for scheme. If NULL is returned and error is non-NULL, it will hold the error that occurred while trying to obtain the default action.

Return: The default HildonURIAction for scheme.

scheme : A string which represents a scheme.
error : The address of a pointer to a GError structure. This is optional and can be NULL.
Returns :

hildon_uri_get_default_action_by_uri ()

HildonURIAction*    hildon_uri_get_default_action_by_uri
                                                        (const gchar *uri,
                                                         GError **error);

Deprecated: Use @hildon_uri_get_default_action_by_uri() instead.

This returns the HildonURIAction which is the default for a uri. This function works similarly to @hildon_uri_get_default_action() with the difference being that the mime type of the uri is used to look up the action. The reason for this being that default actions now are effective with scheme and mime type instead of JUST the scheme as before.

If NULL is returned and error is NULL then there is no default HildonURIAction for scheme. If NULL is returned and error is non-NULL, it will hold the error that occurred while trying to obtain the default action.

Return: The default HildonURIAction for scheme.

uri :
error : The address of a pointer to a GError structure. This is optional and can be NULL.
Returns :

hildon_uri_set_default_action ()

gboolean            hildon_uri_set_default_action       (const gchar *scheme,
                                                         HildonURIAction *action,
                                                         GError **error);

Deprecated: Use @hildon_uri_set_default_action_by_uri() instead.

Sets the default action which should be used with a scheme when hildon_uri_open() is called. The scheme can be obtained from a URI by calling hildon_uri_get_scheme_from_uri().

If action is NULL, the default action is unset. It is important to note that ONLY the user's default actions are unset NOT the system default actions. The user's default actions are in $home/.local/share/applications/defaults.list (the system default actions are in $prefix/share/applications/defaults.list). This means that if you remove a user's default action, the system default will be used instead if there is one.

If FALSE is returned and error is non-NULL, it will hold the error that occurred while trying to set the default action.

Return: TRUE if it was successfully set or FALSE.

scheme : A string which represents a scheme.
action : A HildonURIAction pointer.
error : The address of a pointer to a GError structure. This is optional and can be NULL.
Returns :

hildon_uri_set_default_action_by_uri ()

gboolean            hildon_uri_set_default_action_by_uri
                                                        (const gchar *uri_str,
                                                         HildonURIAction *action,
                                                         GError **error);

Sets the default action which should be used with a uri when hildon_uri_open() is called. The action is saved by the uri scheme and mime type.

If action is NULL, the default action is unset. It is important to note that ONLY the user's default actions are unset NOT the system default actions. The user's default actions are in $home/.local/share/applications/defaults.list (the system default actions are in $prefix/share/applications/defaults.list). This means that if you remove a user's default action, the system default will be used instead if there is one.

If FALSE is returned and error is non-NULL, it will hold the error that occurred while trying to set the default action.

Return: TRUE if it was successfully set or FALSE.

uri_str :
action : A HildonURIAction pointer.
error : The address of a pointer to a GError structure. This is optional and can be NULL.
Returns :

hildon_uri_open ()

gboolean            hildon_uri_open                     (const gchar *uri,
                                                         HildonURIAction *action,
                                                         GError **error);

This will open the uri with the application associated with action. Using the details in action, a DBus signal is sent to the application to open uri.

If action is NULL then the default action will be tried. If the default action is NULL, the first available action in the desktop file is used instead.

If FALSE is returned and error is non-NULL, it will hold the error that occurred while trying to open uri.

Return: TRUE if successfull or FALSE.

uri : A string which represents a URI.
action : A HildonURIAction pointer. This is optional and NULL can be specified to use the default action instead.
error : The address of a pointer to a GError structure. This is optional and can be NULL.
Returns :