Tizen Native API  5.0

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]retThe result value, it could be 0 if it succeeds to add a shortcut, otherwise it returns an errno
[in]user_dataThe 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_nameThe name of package
[in]iconThe absolute path of an icon file for this shortcut
[in]nameThe name of the created shortcut icon
[in]extra_keyThe user data. A property of shortcut element in manifest file
[in]extra_dataThe user data. A property of shortcut element in manifest file
[in]user_dataThe 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_nameThe name of package
[in]nameThe name of the created shortcut icon
[in]sender_pidThe process ID of who request shortcut_remove_from_home
[in]user_dataThe 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_nameThe name of package
[in]nameThe name of the created shortcut icon
[in]typeOne of the three defined types
[in]content_infoThe specific information for creating a new shortcut
[in]iconThe absolute path of an icon file for this shortcut
[in]pidThe process ID of who request add_to_home
[in]periodThe Update period in seconds
[in]allow_duplicate1 if the shortcut can be duplicated, otherwise a shourtcut should exist only once
[in]user_dataThe 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()

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

Enumeration for sizes of shortcut widget.

Since :
2.4

Enumeration Type Documentation

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)

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

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]nameThe name of the created shortcut icon
[in]typeThe type of shortcuts
[in]uriThe specific information for delivering to the viewer for creating a shortcut
[in]iconThe absolute path of an icon file
[in]allow_duplicate1 if it accepts the duplicated shortcut, otherwise 0
[in]cbThe address of the callback function that is called when the result comes back from the viewer
[in]dataThe callback data that is used in the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
SHORTCUT_ERROR_NONESuccessful
SHORTCUT_ERROR_INVALID_PARAMETERInvalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORYOut of memory
SHORTCUT_ERROR_IO_ERRORI/O Error
SHORTCUT_ERROR_PERMISSION_DENIEDPermission denied
SHORTCUT_ERROR_NOT_SUPPORTEDNot supported
SHORTCUT_ERROR_RESOURCE_BUSYDevice or resource busy
SHORTCUT_ERROR_NO_SPACEThere is no space to add a new shortcut
SHORTCUT_ERROR_EXISTShortcut is already exist
SHORTCUT_ERROR_FAULTUnrecoverable error
SHORTCUT_ERROR_COMMConnection 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]nameThe name of the created widget which will be shown when the widget is not prepared
[in]sizeThe size of widget
[in]widget_idWidget ID
[in]iconThe absolute path of an icon file which will be shown when the widget is not prepared
[in]periodThe Update period in seconds
[in]allow_duplicate1 if it accepts the duplicated widget, otherwise 0
[in]cbThe address of the callback function that is called when the result comes back from the viewer
[in]dataThe callback data that is used in the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
SHORTCUT_ERROR_NONESuccessful
SHORTCUT_ERROR_INVALID_PARAMETERInvalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORYOut of memory
SHORTCUT_ERROR_IO_ERRORI/O Error
SHORTCUT_ERROR_PERMISSION_DENIEDPermission denied
SHORTCUT_ERROR_NOT_SUPPORTEDNot supported
SHORTCUT_ERROR_FAULTUnrecoverable error
SHORTCUT_ERROR_COMMConnection 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_nameThe package name
[in]list_cbThe callback function to get the shortcut item information
[in]dataThe callback data that is used in the callback function
Returns:
The return type (int)
Return values:
@cN Number of items (call count of the callback function)
SHORTCUT_ERROR_INVALID_PARAMETERInvalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORYOut of memory
SHORTCUT_ERROR_IO_ERRORI/O Error
SHORTCUT_ERROR_PERMISSION_DENIEDPermission denied
SHORTCUT_ERROR_FAULTUnrecoverable error
SHORTCUT_ERROR_COMMConnection not established or communication problem
SHORTCUT_ERROR_NOT_SUPPORTEDNot 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]nameThe name of the created shortcut icon
[in]cbThe address of the callback function that is called when the result comes back from the viewer
[in]user_dataThe callback data that is used in the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
SHORTCUT_ERROR_NONESuccessful
SHORTCUT_ERROR_INVALID_PARAMETERInvalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORYOut of memory
SHORTCUT_ERROR_IO_ERRORI/O Error
SHORTCUT_ERROR_PERMISSION_DENIEDPermission denied
SHORTCUT_ERROR_COMMConnection not established or communication problem
SHORTCUT_ERROR_NOT_SUPPORTEDNot 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_cbThe callback function pointer that is invoked when remove_from_home is requested
[in]dataThe callback data to deliver to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
SHORTCUT_ERROR_NONESuccessful
SHORTCUT_ERROR_INVALID_PARAMETERInvalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORYOut of memory
SHORTCUT_ERROR_IO_ERRORI/O Error
SHORTCUT_ERROR_PERMISSION_DENIEDPermission denied
SHORTCUT_ERROR_COMMConnection not established or communication problem
SHORTCUT_ERROR_NOT_SUPPORTEDNot 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_cbThe callback function pointer that is invoked when add_to_home is requested
[in]dataThe callback data to deliver to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
SHORTCUT_ERROR_NONESuccessful
SHORTCUT_ERROR_INVALID_PARAMETERInvalid function parameter
SHORTCUT_ERROR_OUT_OF_MEMORYOut of memory
SHORTCUT_ERROR_IO_ERRORI/O Error
SHORTCUT_ERROR_PERMISSION_DENIEDPermission denied
SHORTCUT_ERROR_COMMConnection not established or communication problem
SHORTCUT_ERROR_NOT_SUPPORTEDNot 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_NONESuccessful
SHORTCUT_ERROR_NOT_SUPPORTEDNot supported
SHORTCUT_ERROR_PERMISSION_DENIEDPermission 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_NONESuccessful
SHORTCUT_ERROR_NOT_SUPPORTEDNot supported
SHORTCUT_ERROR_PERMISSION_DENIEDPermission denied
See also:
shortcut_set_request_cb
get_last_result()