Tizen Native API  3.0
Functions | Typedefs
Shortcut
Application Framework

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.

Functions

int shortcut_add_to_home (const char *name, shortcut_type type, const char *uri, const char *icon, int allow_duplicate, result_cb_t result_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_t result_cb, void *data)
 Adds a widget to home, asynchronously.
int shortcut_remove_from_home (const char *name, result_cb_t result_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)
 Registers a callback function to listen requests from applications.
void shortcut_unset_request_cb (void)
 Unregisters a callback for the shortcut request.
int shortcut_set_remove_cb (shortcut_remove_cb remove_cb, void *data)
 Registers the callback function to listen the remove requests from applications.
void shortcut_unset_remove_cb (void)
 Unregisters 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_t )(int ret, void *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 *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_t)(int ret, void *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]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 *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]allow_duplicate1 if the shortcut can be duplicated, otherwise a shourtcut should exist only once
[in]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()
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 

Use these 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_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_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_t  result_cb,
void *  data 
)

Adds a shortcut to home, asynchronously.

Since :
2.3
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.
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
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]result_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_t
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_t  result_cb,
void *  data 
)

Adds a widget to home, asynchronously.

Since :
2.4
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.
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
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]result_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_t
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
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.
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
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
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_t  result_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]result_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
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_t
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 
)

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

Remarks:
Should be used in the homescreen.
Should check the return value of this function. Prospective Clients: Homescreen.
Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
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
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 
)

Registers a callback function to listen requests from applications.

Since :
2.4
Remarks:
Should be used in the homescreen.
Should check the return value of this function. Prospective Clients: Homescreen.
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
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
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  )

Unregisters a callback for the shortcut remove.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
See also:
shortcut_set_remove_cb
void shortcut_unset_request_cb ( void  )

Unregisters a callback for the shortcut request.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
See also:
shortcut_set_request_cb