Tizen Native API  5.0
Functions | Typedefs
Badge
Application Framework

Badge APIs.

Required Header

#include <badge.h>

Overview

It provides functions for creating and inserting and updating badge.

Related Features

This API is related with the following features:

  • http://tizen.org/feature/badge
    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 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 :
2.4
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 enum _badge_error_e badge_error_e

Enumeration for Badge Error.

Since :
2.3
typedef bool(* badge_foreach_cb)(const char *app_id, unsigned int count, void *user_data)

Callback function for getting result of badge_foreach.

Since :
2.4
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.

Since :
2.3
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_NOT_SUPPORTED 

Not supported (Since 4.0)

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 :
2.4
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.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Remarks:
Creating and updating a badge of the other application is allowed only when both applications are signed with the same certificate.
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_OUT_OF_MEMORYOut of memory
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_FROM_DBError from DB
BADGE_ERROR_ALREADY_EXISTAlready exist
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
BADGE_ERROR_NOT_SUPPORTEDNot supported
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 :
2.4
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_OUT_OF_MEMORYOut of memory
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_FROM_DBError form DB
BADGE_ERROR_NOT_EXISTNot exist
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_NOT_SUPPORTEDNot supported
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
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_OUT_OF_MEMORYOut of memory
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_FROM_DBError from DB
BADGE_ERROR_NOT_EXISTNot exist
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_NOT_SUPPORTEDNot supported
See also:
badge_error_e
badge_add()
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
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_OUT_OF_MEMORYOut of memory
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_FROM_DBError from DB
BADGE_ERROR_NOT_EXISTNot exist
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_NOT_SUPPORTEDNot supported
See also:
badge_error_e
badge_add()
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 2.4Use badge_add instead.

Creates new badge to display.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
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
BADGE_ERROR_NOT_SUPPORTEDNot supported
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.

Since :
2.4
Privilege Level:
public
Privilege:
http://tizen.org/privilege/notification
Remarks:
Should be used in the homescreen.
Prospective Clients : Homescreen.
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_IO_ERRORError from I/O
BADGE_ERROR_OUT_OF_MEMORYOut of memory
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_NOT_SUPPORTEDNot supported
See also:
badge_error_e
badge_add()
badge_remove()
badge_set_count()
int badge_remove ( const char *  app_id)

Removes the badge for the designated application.

Since :
2.3
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_OUT_OF_MEMORYOut of memory
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_FROM_DBError from DB
BADGE_ERROR_NOT_EXISTNot exist
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_NOT_SUPPORTEDNot supported
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
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_OUT_OF_MEMORYOut of memory
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_FROM_DBError from DB
BADGE_ERROR_NOT_EXISTNot exist
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_NOT_SUPPORTEDNot supported
See also:
badge_error_e
badge_add()
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
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_OUT_OF_MEMORYOut of memory
BADGE_ERROR_PERMISSION_DENIEDThe application does not have the privilege to call this method
BADGE_ERROR_IO_ERRORError from I/O
BADGE_ERROR_FROM_DBError from DB
BADGE_ERROR_NOT_EXISTNot exist
BADGE_ERROR_SERVICE_NOT_READYService is not ready
BADGE_ERROR_NOT_SUPPORTEDNot supported
See also:
badge_error_e
badge_add()
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 :
2.4
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
BADGE_ERROR_NOT_SUPPORTEDNot supported
See also:
badge_error_e
badge_register_changed_cb()