diff options
author | José Alburquerque <jaalburqu@svn.gnome.org> | 2010-07-30 01:31:58 -0400 |
---|---|---|
committer | José Alburquerque <jaalburqu@svn.gnome.org> | 2010-07-30 01:31:58 -0400 |
commit | af16899e5ee0d555b6636ec94a887d7da44f6dc1 (patch) | |
tree | 8ea02801bf43dcbe28ad2aa36025f8747f3f7c40 /gio/src/dbusownname.hg | |
parent | 43d45475398cd9c0ef651d2c746ce539214a691b (diff) | |
download | glibmm-af16899e5ee0d555b6636ec94a887d7da44f6dc1.tar.gz |
Add Gio::DBus::[own|unown]_name().
* gio/src/dbusconnection.hg: Wrap the BusType enum and add class docs.
* gio/src/dbusownname.{ccg,hg}: Add new source files that implement
the own_name() and unown_name() functions. The functions are defined
in a Gio::DBus namesapce.
* gio/src/filelist.am: Mention the hg source file so that the sources
are built.
Diffstat (limited to 'gio/src/dbusownname.hg')
-rw-r--r-- | gio/src/dbusownname.hg | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/gio/src/dbusownname.hg b/gio/src/dbusownname.hg new file mode 100644 index 00000000..c00209f5 --- /dev/null +++ b/gio/src/dbusownname.hg @@ -0,0 +1,123 @@ +// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*- + +/* Copyright (C) 2010 The giomm Development Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free + * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + */ + +#include <giomm/dbusconnection.h> + +_DEFS(giomm,gio) + +namespace Gio +{ + +namespace DBus +{ + +_WRAP_ENUM(BusNameOwnerFlags, GBusNameOwnerFlags) + +/** For example, + * void on_bus_acquired(const Glib::RefPtr<Gio::DBusConnection>& connection, + * const Glib::ustring& name); + * @newin{2,26} + */ +typedef sigc::slot<void, const Glib::RefPtr<Gio::DBusConnection>&, Glib::ustring> SlotBusAcquired; + +/** For example, + * void on_name_acquired(const Glib::RefPtr<Gio::DBusConnection>& connection, + * const Glib::ustring& name); + */ +typedef sigc::slot<void, const Glib::RefPtr<Gio::DBusConnection>&, Glib::ustring> SlotNameAcquired; + +/** For example, + * void on_name_lost(const Glib::RefPtr<Gio::DBusConnection>& connection, + * const Glib::ustring& name); + */ +typedef sigc::slot<void, const Glib::RefPtr<Gio::DBusConnection>&, Glib::ustring> SlotNameLost; + +//TODO: Add example from C API in class docs. +/** Starts acquiring @a name on the bus specified by @a bus_type and calls @a + * name_acquired_slot and name_@a lost_slot when the name is acquired + * respectively lost. Slots will be invoked in the thread-default main + * loop of the thread you are calling this function from. + * + * You are guaranteed that one of the @a name_acquired_slot and @a + * name_lost_slot slots will be invoked after calling this function - there + * are three possible cases: + * + * - @a name_lost_slot with a NULL connection (if a connection to the bus + * can't be made). + * - @a bus_acquired_slot then @a name_lost_slot (if the name can't be + * obtained) + * - @a bus_acquired_slot then @a name_acquired_slot (if the name was + * obtained). + * + * When you are done owning the name, just call unown_name() with the owner id + * this function returns. + * + * If the name is acquired or lost (for example another application could + * acquire the name if you allow replacement or the application currently + * owning the name exits), the slots are also invoked. If the + * DBusConnection that is used for attempting to own the name closes, then + * @a name_lost_slot is invoked since it is no longer possible for other + * processes to access the process. + * + * You cannot use own_name() several times for the same name (unless + * interleaved with calls to unown_name()) - only the first call will work. + * + * Another guarantee is that invocations of name_@a acquired_slot and + * @a name_lost_slot are guaranteed to alternate; that is, if + * @a name_acquired_slot is invoked then you are guaranteed that the next + * time one of the slots is invoked, it will be @a name_lost_slot. The + * reverse is also true. + * + * If you plan on exporting objects (using e.g. + * Gio::DbusConnection::register_object()), note that it is generally too late + * to export the objects in @a name_acquired_slot. Instead, you can do this + * in @a bus_acquired_slot since you are guaranteed that this will run + * before name is requested from the bus. + * + * This behavior makes it very simple to write applications that wants to own + * names and export objects. + * + * @param bus_type The type of bus to own a name on. + * @param name The well-known name to own. + * @param flags A set of flags from the BusNameOwnerFlags enumeration. + * @param bus_acquired_slot Slot to invoke when connected to the bus of + * type bus_type. + * @param name_acquired_slot Slot to invoke when name is acquired. + * @param name_lost_slot Slot to invoke when name is lost. + * @return An identifier (never 0) that an be used with unown_name() to stop + * owning the name. + * + * @newin{2,26} + */ +guint own_name(BusType bus_type, const Glib::ustring& name, + BusNameOwnerFlags flags, const SlotBusAcquired& bus_acquired_slot, + const SlotNameAcquired& name_acquired_slot, + const SlotNameLost& name_lost_slot); +_IGNORE(g_bus_own_name) + +//TODO: Add own_name() overloads that don't require all the slots. + +/** Stops owning a name. + * @param owner_id An identifier obtained from own_name(). + */ +void unown_name(guint owner_id); +_IGNORE(g_bus_unown_name) +} + +} // namespace Gio |