Tizen Native API
Functions | Typedefs
Shortcut
Application Framework

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_get_list (const char *package_name, shortcut_list_cb list_cb, void *data)
 Gets the list of shortcut elements from the manifest file, synchronously.
int shortcut_set_request_cb (shortcut_request_cb request_cb, void *data)
 Registers a callback function to listen requests from applications.

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.

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.

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_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 

Successfully handled

SHORTCUT_ERROR_INVALID_PARAMETER 

Shortcut request is not valid, invalid parameter or invalid argument value

SHORTCUT_ERROR_OUT_OF_MEMORY 

Memory is not enough to handle a new request

SHORTCUT_ERROR_IO_ERROR 

Unable to access the file or DB. Check your resource files

SHORTCUT_ERROR_PERMISSION_DENIED 

Has no permission to add a shortcut

SHORTCUT_ERROR_NOT_SUPPORTED 

Not supported shortcut

SHORTCUT_ERROR_RESOURCE_BUSY 

Receiver is busy, try again later

SHORTCUT_ERROR_NO_SPACE 

There is no space to add a new shortcut

SHORTCUT_ERROR_EXIST 

Shortcut is already added

SHORTCUT_ERROR_FAULT 

Failed to add a shortcut. Unrecoverable error

SHORTCUT_ERROR_COMM 

Connection is not established. or there is a problem in the communication

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.

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.
Since :
2.3
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:
SHORTCUT_ERROR_NONE on success, other value on failure
Return values:
SHORTCUT_ERROR_NONESuccessful
SHORTCUT_ERROR_INVALID_PARAMETERInvalid 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_SPACENo space
SHORTCUT_ERROR_EXISTAlready exist
SHORTCUT_ERROR_FAULTUnrecoverable error
SHORTCUT_ERROR_COMMConnection failed
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.

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.
Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
Parameters:
[in]nameThe name of the created widget. Will be shown when the widget is not prepared.
[in]size_typeThe size of widget
[in]widget_idWidget id
[in]iconThe absolute path of an icon file. 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:
SHORTCUT_ERROR_NONE on success, other value on failure
Return values:
SHORTCUT_ERROR_FAULTUnrecoverable error
SHORTCUT_ERROR_INVALID_PARAMETERInvalid parameter or invalid argument value
SHORTCUT_ERROR_COMMConnection is not established or there is a problem in the communication
SHORTCUT_ERROR_OUT_OF_MEMORYMemory is not enough to handle a new request
SHORTCUT_ERROR_IO_ERRORUnable to access the file or DB Check your resource files
SHORTCUT_ERROR_PERMISSION_DENIEDHas no permission to add a widget
SHORTCUT_ERROR_NOT_SUPPORTEDWidget is 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_t
shortcut_widget_size_e
Example
 #include <stdio.h>
 #include <shortcut.h>

 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)
 {
    shortcut_add_to_home_widget("alter_name",
                    WIDGET_SIZE_1x1, "org.tizen.testwidget",
                    "/opt/media/Pictures/alter_icon.png", -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 list of shortcut elements from the manifest file, synchronously.

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.
Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/shortcut
Parameters:
[in]package_nameThe package name
[in]shortcut_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_FAULTUnrecoverable error
SHORTCUT_ERROR_IO_ERRORUnable to access the file or DB. Check your resource files
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_set_request_cb ( shortcut_request_cb  request_cb,
void *  data 
)

Registers a callback function to listen requests from applications.

Remarks:
Should be used in the homescreen.
Should check the return value of this function. Prospective Clients: Homescreen.
Since :
2.4
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:
SHORTCUT_ERROR_NONE on success, other value on failure
Return values:
SHORTCUT_ERROR_INVALID_PARAMETERShortcut request is not valid, invalid parameter or invalid argument value
SHORTCUT_ERROR_COMMConnection is not established or there is a problem in the communication
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