## IndicateServer

IndicateServer — The representation of the application on DBus.

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | indicate_server_add_indicator ()
gboolean | indicate_server_check_interest ()
guint | indicate_server_get_next_id ()
void | indicate_server_hide ()
IndicateServer * | indicate_server_ref_default ()
void | indicate_server_remove_indicator ()
void | indicate_server_set_default ()
void | indicate_server_set_desktop_file ()
void | indicate_server_set_type ()
void | indicate_server_show ()

## Properties

guint | count | Read / Write
gchar * | desktop | Read / Write
gchar * | icon-theme | Read / Write
gchar * | menu | Read
gchar * | path | Read / Write / Construct Only
gchar * | type | Read / Write

## Signals

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

## Types and Values

struct | IndicateServer
struct | IndicateServerClass

## Object Hierarchy

        GObject
        ╰── IndicateServer

## Includes

    #include <libindicate/server.h>

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

## Functions

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

[transfer full]

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

server | The IndicateServer to be shown |

## Types and Values

### struct IndicateServer

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

### struct IndicateServerClass

    struct IndicateServerClass {
    	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, guint timestamp);
    	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);
    	indicate_server_get_indicator_list_slot_t get_indicator_list;
    	gboolean (*get_indicator_property) (IndicateServer * server, guint id, gchar * property, GVariant ** value, GError **error);
    	indicate_server_get_indicator_property_group_slot_t get_indicator_property_group;
    	indicate_server_get_indicator_properties_slot_t get_indicator_properties;
    	gboolean (*show_indicator_to_user) (IndicateServer * server, guint id, guint timestamp, GError ** error);
    	gboolean (*indicator_displayed) (IndicateServer * server, const gchar * sender, guint id, gboolean displayed, GError ** error);
    	guint    (*get_next_id) (IndicateServer * server);
    	gboolean (*show_interest) (IndicateServer * server, const gchar * sender, IndicateInterests interest);
    	gboolean (*remove_interest) (IndicateServer * server, const gchar * sender, IndicateInterests interest);
    	gboolean (*check_interest) (IndicateServer * server, IndicateInterests interest);
    	gboolean (*max_indicators_set) (IndicateServer * server, const 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);
    };

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.

#### Members

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. |
indicate_server_get_indicator_list_slot_t `get_indicator_list`; | List all of the indicators that are visible. |
`get_indicator_property` () | Get a property from a particular indicator. |
indicate_server_get_indicator_property_group_slot_t `get_indicator_property_group`; | Get the values for a set of properties as an array of entries, returning an array as well. |
indicate_server_get_indicator_properties_slot_t `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 |

## Property Details

### The `“count”` property

      “count”                    guint

A number reprsenting the number of items in a server.

Flags: Read / Write

Default value: 0

### The `“desktop”` property

      “desktop”                  gchar *

The desktop file representing this server.

Flags: Read / Write

Default value: ""

### The `“icon-theme”` property

      “icon-theme”               gchar *

The Custom Icon Theme Name to use when displaying this Server.

Flags: Read / Write

Default value: ""

### The `“menu”` property

      “menu”                     gchar *

The DBus Object path to an object with a dbusmenu interface on it.

Flags: Read

Default value: ""

### The `“path”` property

      “path”                     gchar *

DBus path for the server object.

Flags: Read / Write / Construct Only

Default value: "/com/canonical/indicate"

### The `“type”` property

      “type”                     gchar *

The type of indicators that this server will provide.

Flags: Read / Write

Default value: ""

## Signal Details

### The `“indicator-delete”` signal

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

#### Parameters

indicateserver | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“indicator-modified”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“indicator-new”` signal

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

#### Parameters

indicateserver | the object which received the signal. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“interest-added”` signal

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

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

#### Parameters

arg0 | The IndicateServer object |
arg1 | The interest that was added from IndicateInterests |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“interest-removed”` signal

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

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

`note` This signal is also emitted after a timeout when the object is created with `arg1` set to INDICATOR_INTREST_NONE if no one has shown any interest in the server.

#### Parameters

arg0 | The IndicateServer object |
arg1 | The interest that was removed from IndicateInterests |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“max-indicators-changed”` signal

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

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

#### Parameters

arg0 | The IndicateServer object |
arg1 | The new max number of indicators |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“server-count-changed”` signal

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

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

#### Parameters

arg0 | The IndicateServer object |
arg1 | The count variable on the server changed. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“server-display”` signal

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

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.

#### Parameters

arg0 | The IndicateServer object |
arg1 | Timestamp of the show event |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“server-hide”` signal

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

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

#### Parameters

arg0 | The IndicateServer object |
arg1 | The type of the server |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“server-show”` signal

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

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.

#### Parameters

arg0 | The IndicateServer object |
arg1 | The type of the server |
user_data | user data set when the signal handler was connected. |

Flags: Run Last