Tizen Native API  3.0
Functions | Typedefs
Badge
Application Framework

Badge APIs.

Required Header

#include <badge.h>

Overview

It provides functions for creating and inserting and updating badge.

Functions

int badge_new (const char *writable_app_id) TIZEN_DEPRECATED_API
 Creates a badge for the application itself.
int badge_add (const char *badge_app_id)
 Creates a badge for the application specified by the badge_app_id.
int badge_remove (const char *app_id)
 Removes the badge for the designated application.
int badge_set_count (const char *app_id, unsigned int count)
 Sets badge count for the designated application.
int badge_get_count (const char *app_id, unsigned int *count)
 Gets badge count for the designated application.
int badge_set_display (const char *app_id, unsigned int is_display)
 Sets the display option for the designated application.
int badge_get_display (const char *app_id, unsigned int *is_display)
 Gets the display option for the designated application.
int badge_foreach (badge_foreach_cb callback, void *user_data)
 Retrieves all existing badges.
int badge_register_changed_cb (badge_change_cb callback, void *user_data)
 Registers a callback function to receive badge change event.
int badge_unregister_changed_cb (badge_change_cb callback)
 Unregisters a callback function to receive badge change event.

Typedefs

typedef bool(* badge_foreach_cb )(const char *app_id, unsigned int count, void *user_data)
 Callback function for getting result of badge_foreach.
typedef void(* badge_change_cb )(unsigned int action, const char *app_id, unsigned int count, void *user_data)
 Called when the badge information is changed.
typedef enum _badge_error_e badge_error_e
 Enumeration for Badge Error.

Typedef Documentation

typedef void(* badge_change_cb)(unsigned int action, const char *app_id, unsigned int count, void *user_data)

Called when the badge information is changed.

Since :
3.0
Parameters:
[in]actionThe type of the change. Refer badge_action
[in]app_idThe name of the application
[in]countThe count of the badge
[in]user_dataThe user data passed from the callback register function
Precondition:
badge_register_changed_cb() will invoke this callback.
See also:
badge_unregister_changed_cb()
typedef bool(* badge_foreach_cb)(const char *app_id, unsigned int count, void *user_data)

Callback function for getting result of badge_foreach.

Since :
3.0
Parameters:
[in]app_idThe id of the application
[in]countThe count of the badge
[in]user_dataThe user data passed from the badge_foreach function
Returns:
true to continue with the next iteration of the loop, false to break out of the loop
Precondition:
badge_foreach() will invoke this callback.
See also:
badge_foreach()

Enumeration Type Documentation

enum _badge_error_e

Enumeration for Badge Error.

Enumerator:
BADGE_ERROR_NONE 

Success

BADGE_ERROR_INVALID_PARAMETER 

Invalid parameter

BADGE_ERROR_OUT_OF_MEMORY 

Out of memory

BADGE_ERROR_PERMISSION_DENIED 

Permission denied

BADGE_ERROR_IO_ERROR 

Error from I/O

BADGE_ERROR_FROM_DB 

Error from DB

BADGE_ERROR_ALREADY_EXIST 

Already exist

BADGE_ERROR_FROM_DBUS 

Error from DBus

BADGE_ERROR_NOT_EXIST 

Not exist

BADGE_ERROR_SERVICE_NOT_READY 

Error service not ready

BADGE_ERROR_INVALID_PACKAGE 

The caller application is not signed with the certificate of the badge owner

enum badge_action

Enumeration for Badge Action.

Since :
3.0
Enumerator:
BADGE_ACTION_CREATE 

Badge created

BADGE_ACTION_REMOVE 

Badge removed

BADGE_ACTION_UPDATE 

Badge updated

BADGE_ACTION_CHANGED_DISPLAY 

The display option of the badge changed

BADGE_ACTION_SERVICE_READY 

The badge service is ready

Function Documentation

int badge_add ( const char *  badge_app_id)

Creates a badge for the application specified by the badge_app_id.

Remarks:
Creating and updating a badge of the other application is allowed only when both applications are signed with the same certificate.
Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]badge_app_idThe id of the application for which the badge will be created. This parameter can be null when creating a badge for itself.
Returns:
BADGE_ERROR_NONE If success, other value if failure
Return values:
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_INVALID_PACKAGEThe caller application is not signed with the certificate of the badge_app_id
See also:
badge_error_e
Sample code:
#include <badge.h>

{
    int err = BADGE_ERROR_NONE;

    err = badge_add("org.tizen.email");
    if (err != BADGE_ERROR_NONE)
        return;
}
int badge_foreach ( badge_foreach_cb  callback,
void *  user_data 
)

Retrieves all existing badges.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]callbackThe callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_FROM_DBError form DB
BADGE_ERROR_OUT_OF_MEMORYOut of memory
BADGE_ERROR_NOT_EXISTNot exist
See also:
badge_error_e
badge_foreach_cb()
int badge_get_count ( const char *  app_id,
unsigned int *  count 
)

Gets badge count for the designated application.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]app_idThe name of the designated application
[out]countThe count of the badge
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_FROM_DBError from DB
BADGE_ERROR_ALREADY_EXISTAlready exist
BADGE_ERROR_OUT_OF_MEMORYOut of memory
See also:
badge_error_e
badge_new()
badge_set_count()
Sample code:
#include <badge.h>

{
    int err = BADGE_ERROR_NONE;
    int count = 0;

    err = badge_get_count(app_id, &count);
    if (err != BADGE_ERROR_NONE)
        return;

}
int badge_get_display ( const char *  app_id,
unsigned int *  is_display 
)

Gets the display option for the designated application.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]app_idThe name of the designated application
[out]is_displayThe display option (1 = display, 0 = not display)
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_FROM_DBError from DB
BADGE_ERROR_NOT_EXISTNot exist
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_OUT_OF_MEMORYOut of memory
See also:
badge_error_e
badge_new()
badge_set_count()
Sample code:
#include <badge.h>

{
    int is_display = 0;
    int err = BADGE_ERROR_NONE;

    err = badge_get_display(app_id, &is_display);
    if (err != BADGE_ERROR_NONE)
        return;
}
int badge_new ( const char *  writable_app_id)

Creates a badge for the application itself.

Deprecated:
Deprecated since 3.0Use badge_add instead.
Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification

Creates new badge to display.

Parameters:
[in]writable_app_idThe id of application which is authorized to change the badge
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_SERVICE_NOT_READYService is not ready
See also:
badge_error_e
Sample code:
#include <badge.h>

{
    int err = BADGE_ERROR_NONE;

    err = badge_new(app_id);
    if (err != BADGE_ERROR_NONE)
        return;

}
int badge_register_changed_cb ( badge_change_cb  callback,
void *  user_data 
)

Registers a callback function to receive badge change event.

Remarks:
Should be used in the homescreen.
Prospective Clients : Homescreen.
Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]callbackThe callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_OUT_OF_MEMORYOut of memory
See also:
badge_error_e
badge_new()
badge_remove()
badge_set_count()
int badge_remove ( const char *  app_id)

Removes the badge for the designated application.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]app_idThe name of the designated application
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_SERVICE_NOT_READYService is not ready
See also:
badge_error_e
Sample code:
#include <badge.h>

{
    int err = BADGE_ERROR_NONE;

    err = badge_remove(app_id);
    if (err != BADGE_ERROR_NONE)
        return;

}
int badge_set_count ( const char *  app_id,
unsigned int  count 
)

Sets badge count for the designated application.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]app_idThe name of the designated application
[in]countThe count of the badge
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_SERVICE_NOT_READYService is not ready
See also:
badge_error_e
badge_new()
Sample code:
#include <badge.h>

{
    int err = BADGE_ERROR_NONE;

    err = badge_set_count(app_id, 1);
    if (err != BADGE_ERROR_NONE)
        return;

}
int badge_set_display ( const char *  app_id,
unsigned int  is_display 
)

Sets the display option for the designated application.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]app_idThe name of the designated application
[in]is_displayThe display option (1 = display, 0 = not display)
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_SERVICE_NOT_READYService is not ready
See also:
badge_error_e
badge_new()
Sample code:
#include <badge.h>

{
    int err = BADGE_ERROR_NONE;

    err = badge_set_display(app_id, 1);
    if (err != BADGE_ERROR_NONE)
        return;

}
int badge_unregister_changed_cb ( badge_change_cb  callback)

Unregisters a callback function to receive badge change event.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Parameters:
[in]callbackThe callback function
Returns:
BADGE_ERROR_NONE if success, other value if failure
Return values:
BADGE_ERROR_NONESuccess
BADGE_ERROR_INVALID_PARAMETERInvalid parameter
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_NOT_EXISTNot exist
See also:
badge_error_e
badge_register_changed_cb()