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 :: 3.0

Parameters:

[in]	action	The type of the change. Refer badge_action
[in]	app_id	The name of the application
[in]	count	The count of the badge
[in]	user_data	The 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.1

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_id	The id of the application
[in]	count	The count of the badge
[in]	user_data	The 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.1

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

Since :: 3.0

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_id The 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_PARAMETER	Invalid parameter
BADGE_ERROR_OUT_OF_MEMORY	Out of memory
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_FROM_DB	Error from DB
BADGE_ERROR_ALREADY_EXIST	Already exist
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_INVALID_PACKAGE	The caller application is not signed with the certificate of the badge_app_id
BADGE_ERROR_NOT_SUPPORTED	Not 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 :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Parameters:

[in]	callback	The callback function
[in]	user_data	The user data to be passed to the callback function

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_OUT_OF_MEMORY	Out of memory
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_FROM_DB	Error form DB
BADGE_ERROR_NOT_EXIST	Not exist
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_NOT_SUPPORTED	Not 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.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Parameters:

[in]	app_id	The name of the designated application
[out]	count	The count of the badge

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_OUT_OF_MEMORY	Out of memory
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_FROM_DB	Error from DB
BADGE_ERROR_NOT_EXIST	Not exist
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_NOT_SUPPORTED	Not 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.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Parameters:

[in]	app_id	The name of the designated application
[out]	is_display	The display option (1 = display, 0 = not display)

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_OUT_OF_MEMORY	Out of memory
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_FROM_DB	Error from DB
BADGE_ERROR_NOT_EXIST	Not exist
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_NOT_SUPPORTED	Not 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 3.0Use badge_add instead.

Creates new badge to display.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Parameters:

[in] writable_app_id The id of application which is authorized to change the badge

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_NOT_SUPPORTED	Not 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 :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Remarks:: Should be used in the homescreen.
Prospective Clients : Homescreen.

Parameters:

[in]	callback	The callback function
[in]	user_data	The user data to be passed to the callback function

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_OUT_OF_MEMORY	Out of memory
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_NOT_SUPPORTED	Not 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.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Parameters:

[in] app_id The name of the designated application

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_OUT_OF_MEMORY	Out of memory
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_FROM_DB	Error from DB
BADGE_ERROR_NOT_EXIST	Not exist
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_NOT_SUPPORTED	Not 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.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Parameters:

[in]	app_id	The name of the designated application
[in]	count	The count of the badge

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_OUT_OF_MEMORY	Out of memory
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_FROM_DB	Error from DB
BADGE_ERROR_NOT_EXIST	Not exist
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_NOT_SUPPORTED	Not 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.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Parameters:

[in]	app_id	The name of the designated application
[in]	is_display	The display option (1 = display, 0 = not display)

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_OUT_OF_MEMORY	Out of memory
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_IO_ERROR	Error from I/O
BADGE_ERROR_FROM_DB	Error from DB
BADGE_ERROR_NOT_EXIST	Not exist
BADGE_ERROR_SERVICE_NOT_READY	Service is not ready
BADGE_ERROR_NOT_SUPPORTED	Not 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 :: 3.0

Privilege Level:: public

Privilege:: http://tizen.org/privilege/notification

Parameters:

[in] callback The callback function

Returns:: BADGE_ERROR_NONE if success, other value if failure

Return values:

BADGE_ERROR_NONE	Success
BADGE_ERROR_INVALID_PARAMETER	Invalid parameter
BADGE_ERROR_PERMISSION_DENIED	The application does not have the privilege to call this method
BADGE_ERROR_NOT_EXIST	Not exist
BADGE_ERROR_NOT_SUPPORTED	Not supported

See also:: badge_error_e; badge_register_changed_cb()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation