To enhance the Add to home feature.

The other for the application developers who should implement the Add to home feature.

Required Header

#include <shortcut_manager.h>

Overview

It provides function of creating shortcut. Developers can use the "shortcut_add_to_home" API to create their shortcut to a home screen.

Related Features

This API is related with the following features:

http://tizen.org/feature/shortcut
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.

Functions
int	shortcut_add_to_home (const char name, shortcut_type type, const char uri, const char icon, int allow_duplicate, result_cb cb, void data)
	Adds a shortcut to home, asynchronously.
int	shortcut_add_to_home_widget (const char name, shortcut_widget_size_e size, const char widget_id, const char icon, double period, int allow_duplicate, result_cb cb, void data)
	Adds a widget to home, asynchronously.
int	shortcut_remove_from_home (const char name, result_cb cb, void user_data)
	Removes a shortcut from home, asynchronously.
int	shortcut_get_list (const char package_name, shortcut_list_cb list_cb, void data)
	Gets the preset list of shortcut template from the installed package, synchronously.
int	shortcut_set_request_cb (shortcut_request_cb request_cb, void *data)
	Sets a callback function to listen requests from applications.
void	shortcut_unset_request_cb (void)
	Unsets a callback for the shortcut request.
int	shortcut_set_remove_cb (shortcut_remove_cb remove_cb, void *data)
	Sets the callback function to listen the remove requests from applications.
void	shortcut_unset_remove_cb (void)
	Unsets a callback for the shortcut remove.
Typedefs
typedef enum _shortcut_type	shortcut_type
	Enumeration for shortcut types.
typedef enum shortcut_widget_size	shortcut_widget_size_e
	Enumeration for sizes of shortcut widget.
typedef int(*	result_cb )(int ret, void *user_data)
	Called to receive the result of shortcut_add_to_home().
typedef int(*	shortcut_list_cb )(const char package_name, const char icon, const char name, const char extra_key, const char extra_data, void user_data)
	Called to receive the result of shortcut_get_list().
typedef int(*	shortcut_request_cb )(const char package_name, const char name, int type, const char content_info, const char icon, int pid, double period, int allow_duplicate, void *user_data)
	Called to the add_to_home request.
typedef int(*	shortcut_remove_cb )(const char package_name, const char name, int sender_pid, void *user_data)
	Called to the shortcut_remove_from_home request.

Typedef Documentation

typedef int(* result_cb)(int ret, void *user_data)

Called to receive the result of shortcut_add_to_home().

Since :: 2.3

Parameters:

[in]	ret	The result value, it could be `0` if it succeeds to add a shortcut, otherwise it returns an errno
[in]	user_data	The callback data

Returns:: int 0 if there is no error, otherwise errno

See also:: shortcut_add_to_home()

typedef int(* shortcut_list_cb)(const char *package_name, const char *icon, const char *name, const char *extra_key, const char *extra_data, void *user_data)

Called to receive the result of shortcut_get_list().

Since :: 2.4

Parameters:

[in]	package_name	The name of package
[in]	icon	The absolute path of an icon file for this shortcut
[in]	name	The name of the created shortcut icon
[in]	extra_key	The user data. A property of shortcut element in manifest file
[in]	extra_data	The user data. A property of shortcut element in manifest file
[in]	user_data	The callback user data

Returns:: SHORTCUT_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop

See also:: shortcut_get_list()

typedef int(* shortcut_remove_cb)(const char *package_name, const char *name, int sender_pid, void *user_data)

Called to the shortcut_remove_from_home request.

Since :: 3.0

Parameters:

[in]	package_name	The name of package
[in]	name	The name of the created shortcut icon
[in]	sender_pid	The process ID of who request shortcut_remove_from_home
[in]	user_data	The user data passed from the callback register function

Returns:: The result of handling a shortcut remove request
This returns 0 if the remove_from_home request is handled successfully, otherwise it returns a proper errno.

See also:: shortcut_set_remove_cb()

typedef int(* shortcut_request_cb)(const char *package_name, const char *name, int type, const char *content_info, const char *icon, int pid, double period, int allow_duplicate, void *user_data)

Called to the add_to_home request.

The homescreen should define a callback as this type and implement the service code for adding a new application shortcut.

Since :: 2.4

Parameters:

[in]	package_name	The name of package
[in]	name	The name of the created shortcut icon
[in]	type	One of the three defined types
[in]	content_info	The specific information for creating a new shortcut
[in]	icon	The absolute path of an icon file for this shortcut
[in]	pid	The process ID of who request add_to_home
[in]	period	The Update period in seconds
[in]	allow_duplicate	`1` if the shortcut can be duplicated, otherwise a shourtcut should exist only once
[in]	user_data	The callback data

Returns:: The result of handling a shortcut creation request
This returns 0 if the add_to_home request is handled successfully, otherwise it returns a proper errno

See also:: shortcut_set_request_cb()

typedef enum _shortcut_type shortcut_type

Enumeration for shortcut types.

Basically, two types of shortcuts are defined. Every homescreen developer should support these types of shortcuts. Or return, a proper errno to figure out why the application failed to add a shortcut. LAUNCH_BY_APP is used for adding a package itself as a shortcut. LAUNCH_BY_URI is used for adding a shortcut for "uri" data.

Since :: 2.3

typedef enum shortcut_widget_size shortcut_widget_size_e

Enumeration for sizes of shortcut widget.

Since :: 2.4

Enumeration Type Documentation

enum _shortcut_type

Enumeration for shortcut types.

Basically, two types of shortcuts are defined. Every homescreen developer should support these types of shortcuts. Or return, a proper errno to figure out why the application failed to add a shortcut. LAUNCH_BY_APP is used for adding a package itself as a shortcut. LAUNCH_BY_URI is used for adding a shortcut for "uri" data.

Since :: 2.3

Enumerator:

LAUNCH_BY_APP	Launch the application itself
LAUNCH_BY_URI	Launch the application with the given data(URI)

enum shortcut_error_e

Enumeration for values of shortcut response types.

Since :: 2.3

Enumerator:

SHORTCUT_ERROR_NONE	Successful
SHORTCUT_ERROR_INVALID_PARAMETER	Invalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORY	Out of memory
SHORTCUT_ERROR_IO_ERROR	I/O Error
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported
SHORTCUT_ERROR_RESOURCE_BUSY	Device or resource busy
SHORTCUT_ERROR_NO_SPACE	There is no space to add a new shortcut
SHORTCUT_ERROR_EXIST	Shortcut is already added
SHORTCUT_ERROR_FAULT	Unrecoverable error
SHORTCUT_ERROR_NOT_EXIST	Not exist shortcut(Since: 3.0)
SHORTCUT_ERROR_COMM	Connection not established or communication problem

enum shortcut_widget_size

Enumeration for sizes of shortcut widget.

Since :: 2.4

Enumerator:

WIDGET_SIZE_DEFAULT	Type mask for the normal mode widget , don't use this value for specific size.
WIDGET_SIZE_1x1	1x1
WIDGET_SIZE_2x1	2x1
WIDGET_SIZE_2x2	2x2
WIDGET_SIZE_4x1	4x1
WIDGET_SIZE_4x2	4x2
WIDGET_SIZE_4x3	4x3
WIDGET_SIZE_4x4	4x4
WIDGET_SIZE_4x5	4x5
WIDGET_SIZE_4x6	4x6
WIDGET_SIZE_EASY_DEFAULT	Type mask for the easy mode widget, don't use this value for specific size.
WIDGET_SIZE_EASY_1x1	Easy mode 1x1
WIDGET_SIZE_EASY_3x1	Easy mode 3x2
WIDGET_SIZE_EASY_3x3	Easy mode 3x3

Function Documentation

int shortcut_add_to_home	(	const char *	name,
		shortcut_type	type,
		const char *	uri,
		const char *	icon,
		int	allow_duplicate,
		result_cb	cb,
		void *	data
	)

Adds a shortcut to home, asynchronously.

Since :: 2.3

Privilege Level:: public

Privilege:: http://tizen.org/privilege/shortcut

Remarks:: If a homescreen does not support this feature, you will get a proper error code.
Application must check the return value of this function.
Application must check the return status from the callback function.
Application should set the callback function to get the result of this request.

Parameters:

[in]	name	The name of the created shortcut icon
[in]	type	The type of shortcuts
[in]	uri	The specific information for delivering to the viewer for creating a shortcut
[in]	icon	The absolute path of an icon file
[in]	allow_duplicate	`1` if it accepts the duplicated shortcut, otherwise `0`
[in]	cb	The address of the callback function that is called when the result comes back from the viewer
[in]	data	The callback data that is used in the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

SHORTCUT_ERROR_NONE	Successful
SHORTCUT_ERROR_INVALID_PARAMETER	Invalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORY	Out of memory
SHORTCUT_ERROR_IO_ERROR	I/O Error
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported
SHORTCUT_ERROR_RESOURCE_BUSY	Device or resource busy
SHORTCUT_ERROR_NO_SPACE	There is no space to add a new shortcut
SHORTCUT_ERROR_EXIST	Shortcut is already exist
SHORTCUT_ERROR_FAULT	Unrecoverable error
SHORTCUT_ERROR_COMM	Connection not established or communication problem

Precondition:: You have to prepare the callback function.

Postcondition:: You have to check the return status from the callback function which is passed by the argument.

See also:: result_cb

Example

#include <stdio.h>
#include <shortcut_manager.h>
static int _result_cb(int ret, int pid, void *data)
{
    if (ret < 0)
        dlog_print("Failed to add a shortcut: %s\n", perror(ret));

    dlog_print("Processed by the %d\n", pid);
    return 0;
}

static int app_create(void *data)
{
    char* data_path = app_get_data_path();
    int path_len = strlen(data_path)+10;
    char * path = malloc(path_len);
    memset(path, 0, path_len);
    strncat(path, data_path, path_len);
    strncat(path, "Friend.jpg", path_len);

    shortcut_add_to_home("With friends", LAUNCH_BY_URI, "gallery:0000-0000", path, 0, _result_cb, NULL);
    free(path);

    return 0;
}

int shortcut_add_to_home_widget	(	const char *	name,
		shortcut_widget_size_e	size,
		const char *	widget_id,
		const char *	icon,
		double	period,
		int	allow_duplicate,
		result_cb	cb,
		void *	data
	)

Adds a widget to home, asynchronously.

Since :: 2.4

Privilege Level:: public

Privilege:: http://tizen.org/privilege/shortcut

Remarks:: If a homescreen does not support this feature, you will get a proper error code.
Application must check the return value of this function.
Application must check the return status from the callback function.
Application should set the callback function to get the result of this request.

Parameters:

[in]	name	The name of the created widget which will be shown when the widget is not prepared
[in]	size	The size of widget
[in]	widget_id	Widget ID
[in]	icon	The absolute path of an icon file which will be shown when the widget is not prepared
[in]	period	The Update period in seconds
[in]	allow_duplicate	`1` if it accepts the duplicated widget, otherwise `0`
[in]	cb	The address of the callback function that is called when the result comes back from the viewer
[in]	data	The callback data that is used in the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

SHORTCUT_ERROR_NONE	Successful
SHORTCUT_ERROR_INVALID_PARAMETER	Invalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORY	Out of memory
SHORTCUT_ERROR_IO_ERROR	I/O Error
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported
SHORTCUT_ERROR_FAULT	Unrecoverable error
SHORTCUT_ERROR_COMM	Connection not established or communication problem

Precondition:: You have to prepare the callback function.

Postcondition:: You have to check the return status from the callback function which is passed by the argument.

See also:: result_cb; shortcut_widget_size_e

Example

#include <stdio.h>
#include <shortcut.h>
#include <storage.h>

#define TIZEN_PATH_MAX 1024
static int _result_cb(int ret, int pid, void *data)
{
    if (ret < 0)
        dlog_print("Failed to add a widget: %s\n", perror(ret));

    dlog_print("Processed by the %d\n", pid);

    return 0;
}

static int app_create(void *data)
{
    char *image_root = NULL;
    char image_path[TIZEN_PATH_MAX] = {0,};

    storage_get_directory(STORAGE_TYPE_INTERNAL, STORAGE_DIRECTORY_IMAGES, &image_root);
    snprintf(image_path, TIZEN_PATH_MAX, "%s/alter_icon.png", image_root);

    shortcut_add_to_home_widget("alter_name", WIDGET_SIZE_1x1, "org.tizen.testwidget",
                    image_path, -1.0f, 0, _result_cb, NULL);

    return 0;
}

int shortcut_get_list	(	const char *	package_name,
		shortcut_list_cb	list_cb,
		void *	data
	)

Gets the preset list of shortcut template from the installed package, synchronously.

Since :: 2.4

Privilege Level:: public

Privilege:: http://tizen.org/privilege/shortcut

Remarks:: If a homescreen does not support this feature, you will get a proper error code.
Application must check the return value of this function.
Application must check the return status from the callback function.
Application should set the callback function to get the result of this request.

Parameters:

[in]	package_name	The package name
[in]	list_cb	The callback function to get the shortcut item information
[in]	data	The callback data that is used in the callback function

Returns:: The return type (int)

Return values:

@c	N Number of items (call count of the callback function)
SHORTCUT_ERROR_INVALID_PARAMETER	Invalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORY	Out of memory
SHORTCUT_ERROR_IO_ERROR	I/O Error
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied
SHORTCUT_ERROR_FAULT	Unrecoverable error
SHORTCUT_ERROR_COMM	Connection not established or communication problem
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: You have to prepare the callback function.

Postcondition:: You have to check the return status from the callback function which is passed by the argument.

int shortcut_remove_from_home	(	const char *	name,
		result_cb	cb,
		void *	user_data
	)

Removes a shortcut from home, asynchronously.

If the callback function registered for a widget, the shortcut deletion is possible.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/shortcut

Parameters:

[in]	name	The name of the created shortcut icon
[in]	cb	The address of the callback function that is called when the result comes back from the viewer
[in]	user_data	The callback data that is used in the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

SHORTCUT_ERROR_NONE	Successful
SHORTCUT_ERROR_INVALID_PARAMETER	Invalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORY	Out of memory
SHORTCUT_ERROR_IO_ERROR	I/O Error
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied
SHORTCUT_ERROR_COMM	Connection not established or communication problem
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: You have to prepare the callback function.

Postcondition:: You have to check the return status from the callback function which is passed by the argument.

See also:: result_cb

Example

#include <shortcut_manager.h>

int _result_cb(int ret, void *data)
{
    if (ret < 0)
        dlog_print("Failed to remove a shortcut: %d\n", ret);

    return 0;
}

{
    int result;

    result = shortcut_remove_from_home("shortcut_name", _result_cb, NULL);
    if (result != SHORTCUT_ERROR_NONE) {
        dlog_print("Failed to remove a shortcut: %d\n", result);
        return result;
    }
}

int shortcut_set_remove_cb	(	shortcut_remove_cb	remove_cb,
		void *	data
	)

Sets the callback function to listen the remove requests from applications.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/shortcut

Remarks:: Should be used in the homescreen.
Should check the return value of this function. Prospective Clients: Homescreen.

Parameters:

[in]	remove_cb	The callback function pointer that is invoked when remove_from_home is requested
[in]	data	The callback data to deliver to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

SHORTCUT_ERROR_NONE	Successful
SHORTCUT_ERROR_INVALID_PARAMETER	Invalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORY	Out of memory
SHORTCUT_ERROR_IO_ERROR	I/O Error
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied
SHORTCUT_ERROR_COMM	Connection not established or communication problem
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: You have to prepare a callback function.

Postcondition:: If a request is sent from the application, the registered callback will be invoked.

See also:: remove_cb_t; shortcut_error_e

int shortcut_set_request_cb	(	shortcut_request_cb	request_cb,
		void *	data
	)

Sets a callback function to listen requests from applications.

Since :: 2.4

Privilege Level:: public

Privilege:: http://tizen.org/privilege/shortcut

Remarks:: Should be used in the homescreen.
Should check the return value of this function. Prospective Clients: Homescreen.

Parameters:

[in]	request_cb	The callback function pointer that is invoked when add_to_home is requested
[in]	data	The callback data to deliver to the callback function

Returns:: 0 on success, otherwise a negative error value

Return values:

SHORTCUT_ERROR_NONE	Successful
SHORTCUT_ERROR_INVALID_PARAMETER	Invalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORY	Out of memory
SHORTCUT_ERROR_IO_ERROR	I/O Error
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied
SHORTCUT_ERROR_COMM	Connection not established or communication problem
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported

Precondition:: You have to prepare a callback function.

Postcondition:: If a request is sent from the application, the registered callback will be invoked.

See also:: request_cb_t; shortcut_error_e

void shortcut_unset_remove_cb ( void )

Unsets a callback for the shortcut remove.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/shortcut

Remarks:: The specific error code can be obtained using the gat_last_result() method. Error codes are described in Exception section.

Returns:: None

Exceptions:

SHORTCUT_ERROR_NONE	Successful
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied

See also:: shortcut_set_remove_cb; get_last_result()

void shortcut_unset_request_cb ( void )

Unsets a callback for the shortcut request.

Since :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/shortcut

Remarks:: The specific error code can be obtained using the gat_last_result() method. Error codes are described in Exception section.

Returns:: None

Exceptions:

SHORTCUT_ERROR_NONE	Successful
SHORTCUT_ERROR_NOT_SUPPORTED	Not supported
SHORTCUT_ERROR_PERMISSION_DENIED	Permission denied

See also:: shortcut_set_request_cb; get_last_result()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation