IndicateServer

IndicateServer — The representation of the application on DBus.

Stability Level

Unstable, unless otherwise indicated

Synopsis


#include <libindicate/server.h>

                    IndicateServer;
                    IndicateServerClass;
void                indicate_server_add_indicator       (IndicateServer *server,
                                                         IndicateIndicator *indicator);
gboolean            indicate_server_check_interest      (IndicateServer *server,
                                                         IndicateInterests interest);
guint               indicate_server_get_next_id         (IndicateServer *server);
void                indicate_server_hide                (IndicateServer *server);
IndicateServer *    indicate_server_ref_default         (void);
void                indicate_server_remove_indicator    (IndicateServer *server,
                                                         IndicateIndicator *indicator);
void                indicate_server_set_default         (IndicateServer *server);
void                indicate_server_set_desktop_file    (IndicateServer *server,
                                                         const gchar *path);
void                indicate_server_set_type            (IndicateServer *server,
                                                         const gchar *type);
void                indicate_server_show                (IndicateServer *server);

Object Hierarchy

  GObject
   +----IndicateServer

Properties

  "count"                    guint                 : Read / Write
  "desktop"                  gchar*                : Read / Write
  "type"                     gchar*                : Read / Write

Signals

  "indicator-delete"                               : Run Last
  "indicator-modified"                             : Run Last
  "indicator-new"                                  : Run Last
  "interest-added"                                 : Run Last
  "interest-removed"                               : Run Last
  "max-indicators-changed"                         : Run Last
  "server-count-changed"                           : Run Last
  "server-display"                                 : Run Last
  "server-hide"                                    : Run Last
  "server-show"                                    : Run Last

Description

The server object is the object that provides the functions on to DBus for other applications to call. It does this by implementing the DBus indicator spec, but it also allows for subclassing so that subclasses don't have to worry about the DBus-isms as much as the functionality that they're trying to express.

For simple applications there is limited need to set anything more than the desktop file and the type of the server using indicate_server_set_desktop_file() and indicate_server_set_type(). Each of these function sets the respective value and expresses it in a way that other applications on the bus can read it.

More advanced applications might find the need to subclass the IndicateServer object and make their own. This is likely the case where applications have complex data stores that they don't want to turn into a large set of GObjects that can take up a significant amount of memory in the program.

In general, it is recommended that application authors go with the high memory path first, and then optimize by implementing their server on a second pass.

Details

IndicateServer

typedef struct _IndicateServer IndicateServer;

This is the object that represents the overall connection between this application and DBus. It acts as the proxy for incomming DBus calls and also sends the appropriate signals on DBus for events happening on other objects locally. It provides some settings that effection how the application as a whole is perceived by listeners of the indicator protocol.


IndicateServerClass

typedef struct {
	GObjectClass parent;

	/* Signals */
	void (* indicator_added) (IndicateServer * server, guint id);
	void (* indicator_removed) (IndicateServer * server, guint id);
	void (* indicator_modified) (IndicateServer * server, guint id, gchar * property);
	void (* server_show) (IndicateServer * server, gchar * type);
	void (* server_hide) (IndicateServer * server, gchar * type);
	void (* server_display) (IndicateServer * server);
	void (* interest_added) (IndicateServer * server, IndicateInterests interest);
	void (* interest_removed) (IndicateServer * server, IndicateInterests interest);
	void (* max_indicators_changed) (IndicateServer * server, gint max);
	void (* server_count_changed) (IndicateServer * server, guint count);

	/* Virtual Functions */
	gboolean (*get_indicator_count) (IndicateServer * server, guint * count, GError **error);
	gboolean (*get_indicator_list) (IndicateServer * server, GArray ** indicators, GError ** error);
	gboolean (*get_indicator_property) (IndicateServer * server, guint id, gchar * property, gchar ** value, GError **error);
	gboolean (*get_indicator_property_group) (IndicateServer * server, guint id, GPtrArray * properties, gchar *** value, GError **error);
	gboolean (*get_indicator_properties) (IndicateServer * server, guint id, gchar *** properties, GError **error);
	gboolean (*show_indicator_to_user) (IndicateServer * server, guint id, GError ** error);
	gboolean (*indicator_displayed) (IndicateServer * server, gchar * sender, guint id, gboolean displayed, GError ** error);
	guint    (*get_next_id) (IndicateServer * server);
	gboolean (*show_interest) (IndicateServer * server, gchar * sender, IndicateInterests interest);
	gboolean (*remove_interest) (IndicateServer * server, gchar * sender, IndicateInterests interest);
	gboolean (*check_interest) (IndicateServer * server, IndicateInterests interest);
	gboolean (*max_indicators_set) (IndicateServer * server, gchar * sender, gint max);
	gint     (*max_indicators_get) (IndicateServer * server);

	/* Reserver for future use */
	void (*indicate_server_reserved1)(void);
	void (*indicate_server_reserved2)(void);
	void (*indicate_server_reserved3)(void);
	void (*indicate_server_reserved4)(void);
} IndicateServerClass;

All of the functions and signals that make up the server class including those that are public API to the application and those that are public API to all of DBus. Subclasses may need to implement a large portion of these.

GObjectClass parent;

Parent Class

indicator_added ()

Slot for "indicator-added".

indicator_removed ()

Slot for "indicator-removed".

indicator_modified ()

Slot for "indicator-modified".

server_show ()

Slot for "server-show".

server_hide ()

Slot for "server-hide".

server_display ()

Slot for "server-display".

interest_added ()

Slot for "interest-added".

interest_removed ()

Slot for "interest-removed".

max_indicators_changed ()

Slot for "max-indicators-changed".

server_count_changed ()

Slot for "server-count-changed".

get_indicator_count ()

Returns the number of indicators that are visible on the bus. Hidden indicators should not be counted.

get_indicator_list ()

List all of the indicators that are visible.

get_indicator_property ()

Get a property from a particular indicator.

get_indicator_property_group ()

Get the values for a set of properties as an array of entries, returning an array as well.

get_indicator_properties ()

Get a list of all the properties that are on a particular indicator.

show_indicator_to_user ()

Respond to someone on the bus asking to show a particular indicator to the user.

indicator_displayed ()

An indicator has been visualized by the listener or it hasn't. This function tracks that.

get_next_id ()

Get the next unused indicator ID.

show_interest ()

React to someone signifying that they are interested in this server.

remove_interest ()

Someone on the bus is no longer interest in this server, remove it's interest.

check_interest ()

Check to see if anyone on the bus is interested in this server for a particular feature.

max_indicators_set ()

Set the maximum number of indicators that a given listener can display.

max_indicators_get ()

Gets the maximum number of indicators from all listeners that care about this server.

indicate_server_reserved1 ()

Reserved for future use

indicate_server_reserved2 ()

Reserved for future use

indicate_server_reserved3 ()

Reserved for future use

indicate_server_reserved4 ()

Reserved for future use

indicate_server_add_indicator ()

void                indicate_server_add_indicator       (IndicateServer *server,
                                                         IndicateIndicator *indicator);

This function adds an indicator indicator to the list that are watched by the server server. This means that signals that are emitted by the indicator will be picked up and passed via DBus onto listeners of the application.

server :

The IndicateServer to add the IndicateIndictor to.

indicator :

The IndicateIndicator to add.

indicate_server_check_interest ()

gboolean            indicate_server_check_interest      (IndicateServer *server,
                                                         IndicateInterests interest);

This function looks at all the interest that various listeners have specified that they have for this server and returns whether there is a listener that has the interest specified in interest.

server :

The IndicateServer being checked

interest :

Which interest type we're checking for

Returns :

TRUE if a listener as the interest otherwise FALSE

indicate_server_get_next_id ()

guint               indicate_server_get_next_id         (IndicateServer *server);

Returns the next available unused ID that an indicator can have.

server :

The IndicateServer the ID will be on

Returns :

A valid indicator ID.

indicate_server_hide ()

void                indicate_server_hide                (IndicateServer *server);

This function hides the server from DBus so that it does not get signals anymore. This causes the signal "server-hide" to be sent across the bus for all listeners. Also internally it will signal "interest-removed" for all the interests that were currently set for this server.

server :

The IndicateServer to hide.

indicate_server_ref_default ()

IndicateServer *    indicate_server_ref_default         (void);

This function will return a reference to the default IndicateServer reference if there is one, or it will create one if one had not previously been created. It is recommended that all applications use this function to create a IndicateServer as it ensure that there is only one per application.

Returns :

A reference to the default IndicateServer instance.

indicate_server_remove_indicator ()

void                indicate_server_remove_indicator    (IndicateServer *server,
                                                         IndicateIndicator *indicator);

Removes an indicator indicator from being watched by the server server so it's signals are no longer watched and set over DBus.

server :

The IndicateServer to remove the IndicateIndictor from.

indicator :

The IndicateIndicator to remove.

indicate_server_set_default ()

void                indicate_server_set_default         (IndicateServer *server);

This function is used to set the default IndicateServer that will be used when creating IndicateIndicators or for anyone else that calls indicate_server_ref_default(). Typically this is just an instance of IndicateServer but applications that create a subclass of IndicateServer should set this as well.

server :

The IndicateServer that should be used

indicate_server_set_desktop_file ()

void                indicate_server_set_desktop_file    (IndicateServer *server,
                                                         const gchar *path);

This is a convience function to set the "desktop" property of the server object. The property can also be set via traditional means, but this one is easier to read.

server :

The IndicateServer to set the type of

path :

The new desktop file representing the server

indicate_server_set_type ()

void                indicate_server_set_type            (IndicateServer *server,
                                                         const gchar *type);

This is a convience function to set the "type" property of the server object. The property can also be set via traditional means, but this one is easier to read.

server :

The IndicateServer to set the type of

type :

The new type of the server

indicate_server_show ()

void                indicate_server_show                (IndicateServer *server);

This function exports the object onto DBus and shows it to the world. This will be the start of it receiving external signals from DBus. It is likely that, if there are listeners running, there will several "interest-added" signals coming shortly after this function. This function emits the "server-added" signal across the bus.

server :

The IndicateServer to be shown

Property Details

The "count" property

  "count"                    guint                 : Read / Write

A number reprsenting the number of items in a server.

Default value: 0


The "desktop" property

  "desktop"                  gchar*                : Read / Write

The desktop file representing this server.

Default value: ""


The "type" property

  "type"                     gchar*                : Read / Write

The type of indicators that this server will provide.

Default value: ""

Signal Details

The "indicator-delete" signal

void                user_function                      (IndicateServer *indicateserver,
                                                        guint           arg1,
                                                        gpointer        user_data)           : Run Last

indicateserver :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "indicator-modified" signal

void                user_function                      (IndicateServer *arg0,
                                                        guint           arg1,
                                                        gchar          *arg2,
                                                        gpointer        user_data)      : Run Last

Emitted every time that a property on an indicator changes and it is visible to the world. This results in a signal on DBus.

arg0 :

The IndicateServer object

arg1 :

The IndicateIndicator ID number

arg2 :

The name of the property modified

user_data :

user data set when the signal handler was connected.

The "indicator-new" signal

void                user_function                      (IndicateServer *indicateserver,
                                                        guint           arg1,
                                                        gpointer        user_data)           : Run Last

indicateserver :

the object which received the signal.

arg1 :

user_data :

user data set when the signal handler was connected.

The "interest-added" signal

void                user_function                      (IndicateServer *arg0,
                                                        guint           arg1,
                                                        gpointer        user_data)      : Run Last

Emitted when a listener signals that they are interested in this server for a particular reason. This signal is emitted by DBus.

arg0 :

The IndicateServer object

arg1 :

The interest that was added from IndicateInterests

user_data :

user data set when the signal handler was connected.

The "interest-removed" signal

void                user_function                      (IndicateServer *arg0,
                                                        guint           arg1,
                                                        gpointer        user_data)      : Run Last

Emitted when a listener signals that they are no longer interested in this server for a particular reason. This signal is emitted by DBus.

arg0 :

The IndicateServer object

arg1 :

The interest that was removed from IndicateInterests

user_data :

user data set when the signal handler was connected.

The "max-indicators-changed" signal

void                user_function                      (IndicateServer *arg0,
                                                        gint            arg1,
                                                        gpointer        user_data)      : Run Last

Emitted when a listener either specifies their max number to be higher, or at all. The default is -1 or infinite.

arg0 :

The IndicateServer object

arg1 :

The new max number of indicators

user_data :

user data set when the signal handler was connected.

The "server-count-changed" signal

void                user_function                      (IndicateServer *arg0,
                                                        guint           arg1,
                                                        gpointer        user_data)      : Run Last

Emitted when the count property of the server changes to a new value.

arg0 :

The IndicateServer object

arg1 :

The count variable on the server changed.

user_data :

user data set when the signal handler was connected.

The "server-display" signal

void                user_function                      (IndicateServer *arg0,
                                                        gpointer        user_data)      : Run Last

Emitted when a listener signals that the server itself should be displayed. This signal is caused by a user clicking on the application item in the Messaging Menu. This signal is emitted by DBus.

arg0 :

The IndicateServer object

user_data :

user data set when the signal handler was connected.

The "server-hide" signal

void                user_function                      (IndicateServer *arg0,
                                                        gchar          *arg1,
                                                        gpointer        user_data)      : Run Last

Emitted when a server removes itself from DBus. This results in a signal on DBus.

arg0 :

The IndicateServer object

arg1 :

The type of the server

user_data :

user data set when the signal handler was connected.

The "server-show" signal

void                user_function                      (IndicateServer *arg0,
                                                        gchar          *arg1,
                                                        gpointer        user_data)      : Run Last

Emitted when a server comes onto DBus by being shown. This is typically when listeners start reacting to the application's indicators. This results in a signal on DBus.

arg0 :

The IndicateServer object

arg1 :

The type of the server

user_data :

user data set when the signal handler was connected.