Commit Graph

50 Commits

Author SHA1 Message Date
Philip Withnall
eb8d1c4826 gdbusconnection: Improve documentation formatting slightly
Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
2020-12-15 09:14:20 +00:00
Philip Withnall
06b5e3e54c gdbusconnection: Add missing (transfer) and (nullable) return annotations
This commit only looks at the `Returns:` lines in the documentation, and
has examined all of them in the file. Function arguments have not been
checked.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>

Helps: #2227
2020-12-15 09:13:22 +00:00
Corentin Noël
565ba0dbd1 gdbusconnection: GDBusSignalCallback can have a NULL sender_name
On a peer GDBusConnection, the returned sender_name can be NULL
2020-04-03 08:01:44 +02:00
Philip Withnall
b649946c00 gdbusconnection: Clarify nullability in a documentation comment
The comment previously said ‘never %NULL’, but it wasn’t clear whether
this meant `(not nullable)` or `(not optional)`. From looking at the
code, it means `(not optional)`.

Clarify things by removing the prose. The annotations themselves should
be clear and explicit enough.

Signed-off-by: Philip Withnall <withnall@endlessm.com>

Closes: #1836
2019-07-23 11:34:59 +01:00
Cosimo Cecchi
7d02e32644 gdbusconnection: add a getter for the flags property
Right now this can only be set at construction but not read back.
That seems unnecessarily restrictive, and we'll need to read these
flags from outside of gdbusconnection.c in the next commit, so let's
just make it public.

https://gitlab.gnome.org/GNOME/glib/issues/1620
2018-12-20 00:41:13 +00:00
Philip Withnall
e430541378 docs: Remove XML-style comments from documentation strings
gtk-doc doesn’t support them any more since it was ported to Markdown,
so they end up appearing in the generated documentation, which isn’t
great.

Mostly, they were used to split up things invisibly, which we can do in
other ways.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
Reviewed-by: nobody
2018-01-12 15:29:29 +00:00
Sébastien Wilmet
3bf4a720c3 gio/: LGPLv2+ -> LGPLv2.1+
Sub-directories inside gio/ already processed in a previous commit:
- fam/
- gdbus-2.0/ (which contains only codegen/)
- gvdb/
- inotify/
- tests/
- win32/
- xdgmime/

Other sub-directories inside gio/:
- completion/: no license headers
- kqueue/: not LGPL, BSD-style license

https://bugzilla.gnome.org/show_bug.cgi?id=776504
2017-05-29 19:53:34 +02:00
Philip Withnall
2411b76c5e docs: Fix some DocBook usage in a few gtk-doc comments
<emphasis> and <ulink> tags. Replace them with Markdown.

Signed-off-by: Philip Withnall <withnall@endlessm.com>
2017-03-16 13:50:19 +00:00
Christian Hergert
18a33f72db introspection: use (nullable) or (optional) instead of (allow-none)
If we have an input parameter (or return value) we need to use (nullable).
However, if it is an (inout) or (out) parameter, (optional) is sufficient.

It looks like (nullable) could be used for everything according to the
Annotation documentation, but (optional) is more specific.
2016-11-22 14:14:37 -08:00
Philip Withnall
25a7c817d3 glib: Add missing (nullable) and (optional) annotations
Add various (nullable) and (optional) annotations which were missing
from a variety of functions. Also port a couple of existing (allow-none)
annotations in the same files to use (nullable) and (optional) as
appropriate instead.

Secondly, add various (not nullable) annotations as needed by the new
default in gobject-introspection of marking gpointers as (nullable). See
https://bugzilla.gnome.org/show_bug.cgi?id=729660.

This includes adding some stub documentation comments for the
assertion macro error functions, which weren’t previously documented.
The new comments are purely to allow for annotations, and hence are
marked as (skip) to prevent the symbols appearing in the GIR file.

https://bugzilla.gnome.org/show_bug.cgi?id=719966
2015-11-07 10:48:32 +01:00
Janusz Lewandowski
5d014a802a Add a g_dbus_connection_register_object_with_closures function
This is a binding-friendly version of g_dbus_connection_register_object.
Based on a patch by Martin Pitt and the code of g_bus_watch_name_with_closures.

https://bugzilla.gnome.org/show_bug.cgi?id=656325
2015-08-18 16:41:12 -04:00
Owen W. Taylor
66fc112c74 GDBusInterfaceVTable: clarify memory handling for the method() virtual function
There are two consistent interpretations that could be taken for memory
handling of the 'invocation' parameter passed to the method_call() virtual
function of GDBusInterfaceVTable

 - A reference is passed (transfer full) to the method_call() virtual function,
   and that reference is then passed (transfer full) to the return_value/error
   functions on GDBusMethodInvocation.
 - An internal reference is retained from the point where method_call() is called
   until the return_value/error function is called.

Since the return_value/error functions were already marked (transfer full),
we use the first interpretation, annotate the invocation parameter of
method call as (transfer full) and describe this in the documentation, along
with the idea that you are always supposed to call one of the return_value/error
functions.

See bug 738122 for the leak this caused in GJS.

https://bugzilla.gnome.org/show_bug.cgi?id=738259
2014-10-28 13:57:52 -04:00
Matthias Clasen
49cc207e35 docs: Ditch more markup
Some markup was hiding in docs in headers. Drop it there, too.
2014-03-02 18:23:43 -05:00
Daniel Mustieles
078dbda148 Updated FSF's address 2014-01-31 14:31:55 +01:00
Dieter Verfaillie
fdc9379132 docs: fix GTK-Doc build
cd html && gtkdoc-mkhtml $mkhtml_options  gio ../gio-docs.xml
../xml/gdbusconnection.xml:2063: parser error : Opening and ending tag mismatch: literal line 2062 and para
</para>
       ^
2013-06-23 14:15:05 +02:00
Ryan Lortie
f754c4e85b GDBusConnection: allow async property handling
The existing advice in the documentation to "simply" register the
"org.freedesktop.DBus.Properties" interface if you want to handle
properties asynchronously is pretty unreasonable.  If you want to handle
this interface you have to deal with all properties for all interfaces
on the path, and you have to do all of the checking for yourself.  You
also have to provide your own introspection data.

Introduce a new convention for dealing with properties asynchronously.

If the user provides NULL for their get_property() or set_property()
functions in the vtable and has properties registered then the
properties are sent to the method_call() handler.  We get lucky here
that this function takes an "interface_name" parameter that we can set
to "org.freedesktop.DBus.Properties".

We also do the user the favour of setting the GDBusPropertyInfo on the
GDBusMethodInvocation for their convenience (for much the same reasons
as they might want the already-available GDBusMethodInfo).

Add a testcase as well as a bunch of documentation about this new
feature.

https://bugzilla.gnome.org/show_bug.cgi?id=698375
2013-06-22 13:38:31 -04:00
Ryan Lortie
0156092a42 various: add GLIB_AVAILABLE_IN_ALL everywhere else
Add the GLIB_AVAILABLE_IN_ALL annotation to all old functions (that
haven't already been annotated with the GLIB_AVAILABLE_IN_* macros or a
deprecation macro).

If we discover in the future that we cannot use only one macro on
Windows, it will be an easy sed patch to fix that.

https://bugzilla.gnome.org/show_bug.cgi?id=688681
2013-01-13 13:11:57 -05:00
Matthias Clasen
e1b99b2ddc Move single-include guards inside include guards
gcc has optimizations for include guards that only work
if they are outermost in the the header.
https://bugzilla.gnome.org/show_bug.cgi?id=689810
2012-12-27 23:43:14 -05:00
Tomas Bzatek
032e8dabd1 gdbus: Implement g_dbus_connection_get_last_serial()
This patch brings an ability to retrieve serial number of the last
message sent within the current thread.

https://bugzilla.gnome.org/show_bug.cgi?id=676825
2012-06-06 19:44:39 +02:00
Colin Walters
a963712646 Annotate API introduced for 2.30 with GLIB_AVAILABLE_IN_2_30
I didn't do this comprehensively, since there's a lot of it, mainly
due to the GDBus object manager stuff, but anyone trying to use
that would fail fast due to lack of the gdbus code generator.

My main goal was to get API additions to existing classes like
g_data_input_stream_read_line_utf8(), as well as the lower level new
API like glib-unix.h.

https://bugzilla.gnome.org/show_bug.cgi?id=676816
2012-05-26 10:13:30 -04:00
David Zeuthen
c404dbed11 gdbus-codegen: Add support for new org.gtk.GDBus.C.UnixFD annotation
Also add convenience _with_unix_fd_list variants to GDBusConnection,
GDBusProxy and GDBusMethodInvocation types to easily support this.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2011-07-21 16:06:18 -04:00
David Zeuthen
7c66068544 GDBusMessage: Don't reset serial number when copying
Ryan pointed out that it's safe to do this because we have the
G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag and that it simplifies
how filter functions work.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-09-09 15:15:13 -04:00
David Zeuthen
c3371efcaa Bug 624546 – Modification of GDBusMessage in filter function
Rework filter functions as per

 https://bugzilla.gnome.org/show_bug.cgi?id=624546#c8

This commit breaks ABI. However, this ABI break affects only
applications using filter functions. The only known user of is dconf.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-09-09 13:21:35 -04:00
David Zeuthen
0d0a9bb448 GDBusConnection: Document memory management semantics for get_property()
Turns out we are leaking non-floating GVariant instances returned by
get_property() functions.

Also avoid imprecise language such as "newly-allocated GVariant" as
this doesn't specify whether the variant can be floating or not.

Also see https://bugzilla.gnome.org/show_bug.cgi?id=627974 as it is
very related to this change.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-08-25 14:49:05 -04:00
David Zeuthen
3ff9894826 Bug 624546 – Modification of GDBusMessage in filter function
Allow modifying a GDBusMessage in a filter function and also add tests
for this. This breaks API but leaves ABI (almost) intact - at least
dconf's GSettings backend (the only big user I know of) will keep
working.

https://bugzilla.gnome.org/show_bug.cgi?id=624546

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-08-05 20:37:27 -04:00
David Zeuthen
0b2b4deac5 GDBus: Add GDBusSendMessageFlags
This is currently unused but might be useful in the future. For
example, it might be nice with a way to bypass the current queue of
outgoing messages - having a flag enumeration allows us to add a
G_DBUS_SEND_MESSAGE_FLAGS_BYPASS_QUEUE etc. etc.

This commit breaks ABI and API. Users of the (rarely used) API to send
messages will have to port to this new API.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-07-19 16:07:57 -04:00
David Zeuthen
7190af4394 GDBus: Remove constness from introspection data structures
Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-07-19 15:45:27 -04:00
David Zeuthen
4a1c5a1b98 GDBus: Add GDBusSignalFlags and use it in g_dbus_connection_signal_subscribe()
This is currently unused but will probably be useful in the
future. For example, we could have a _ARG0_IS_PATH to specify that
arg0 should be used for arg0path.

This commit breaks API and ABI. Users of
g_dbus_connection_signal_subscribe() will need to port to this new
version.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-07-19 15:05:10 -04:00
Ryan Lortie
8a2d157d49 Bug 624484: GDBusSubtreeDispatchFunc clarification
Pass NULL rather than "/" for the toplevel of a subtree.

Add clarification to the docs about how trees are flat.
2010-07-15 17:32:04 -04:00
Ryan Lortie
ca14ab7ac0 Bug 624483: GDBusSubtreeEnumerateFunc clarification
Clarify a couple of things in the docs:

  1) you must return flat names (no slashes)

  2) g_strfreev() will be called on the result

  3) a benefit of using the DISPATCH_TO_UNENUMERATED flag
2010-07-15 17:32:04 -04:00
Ryan Lortie
e6b5546cf5 Bug 624473: GDBusSubtreeIntrospectFunc return type
Return a NULL terminated C array instead of a GPtrArray

Also, document that %NULL is a permitted return value and clarify its
meaning.

Finally, avoid calling the enumeration function during dispatch when the
G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag was given.
2010-07-15 17:31:59 -04:00
David Zeuthen
baf383d1b1 GDBusConnection: copy object and subtree virtual tables
Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-07-14 14:46:12 -04:00
David Zeuthen
914b046226 GDBusConnection: Fix up g_dbus_connection_close()
... so it is async, cancelable and returns an error. Also provide a
synchronous version.

This is an API/ABI break but it is expected that only very few
applications use this API.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-07-14 12:37:32 -04:00
David Zeuthen
abc65b233c GDBus: Hide instance structures for classes we don't want to be subclassed
This also allows us to nuke the priv-> pointers and save a couple of
indirections.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-07-07 16:36:51 -04:00
David Zeuthen
2d2a321a4b GDBus: Hide class structures for classes we don't want to be subclassed
E.g. move these C structures out of public header files and into their
respective C files. Also nuke padding since this is no longer needed.

This leaves only GDBusProxy as an extendable type.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-07-07 15:57:37 -04:00
David Zeuthen
62a1ccf526 Bug 618882 – No way to ensure that a message is sent
Add g_dbus_connection_flush{_finish,sync}().

https://bugzilla.gnome.org/show_bug.cgi?id=618882

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-07-07 15:03:03 -04:00
David Zeuthen
5ac2722975 GDBus: Rename introspection_data' parameter to interface_info'
Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-06-30 12:18:49 -04:00
David Zeuthen
038d03cd08 Bug 623142 – Ensure ::new-connection runs before processing D-Bus messages
Without this guarantee, peer-to-peer connections are not very
useful. However, with this guarantee it's possible to export objects
in a handler for the GDBusServer::new-connection signal.

There are two caveats with this patch

 - it won't work on message bus connections
 - we don't queue up messages to be written

that can be addresses later if needed.

https://bugzilla.gnome.org/show_bug.cgi?id=623142

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-06-30 11:51:40 -04:00
David Zeuthen
2be38f6926 GDBus: update padding
Add lots of padding for public class structures. Notably, we seemed to
lack any padding whatsoever in the GDBusMessageClass struct (spotted
by Dan Winship). Also switch to using

 gpointer padding[N];

instead of

 void (*_g_reserved1) (void);
 ...
 void (*_g_reservedN) (void);

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-06-22 12:14:31 -04:00
David Zeuthen
45411ccbe3 Bug 621945 – Filter outgoing messages in GDBusConnection
This patch breaks some rarely-used public API (only known user is
dconf).

This patch is based on work from Peng Huang <shawn.p.huang@gmail.com>.

See https://bugzilla.gnome.org/show_bug.cgi?id=621945

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-06-21 16:12:23 -04:00
Matthias Clasen
6427e93757 Merge the wip/gapplication branch
This adds a GApplication object to GIO, which is the core of
an application support class, supporting
- uniqueness
- exporting actions (simple scripting)
- standard actions (quit, activate)

The implementation for Linux uses D-Bus, takes a name on the
session bus, and exports a org.gtk.Application interface.

Implementations for Win32 and OS X are still missing.
2010-06-07 13:48:42 -04:00
Matthias Clasen
2aca3b506a Add single-include guards to new headers
As pointed out by Christian Persch in bug 620173, all the new
gdbus and gsettings headers were missing these.
2010-06-06 16:20:21 -04:00
Ryan Lortie
3160bcad6a GDBusConnection.call(): add 'reply_type' argument
This allows the caller to specify the reply type that they are expecting
for this call.  If the reply comes back with the wrong type, GDBus will
generate an appropriate error internally.

  - add a GVariantType * argument to g_dbus_connection_call() and
    _call_sync().

  - move the internal API for computing message types from introspection
    data to be based on GVariantType instead of strings.  Update users
    of this code.

  - have GDBusProxy pass this calculated GVariantType into
    g_dbus_connection_call().  Remove the checks done in GDBusProxy.

  - Update other users of the code (test cases, gdbus-tool, GSettings
    tool, etc).  In some cases, remove redundant checks; in some other
    cases, we are fixing bugs because no checking was done where it
    should have been.

Closes bug #619391.
2010-05-24 17:00:04 -04:00
David Zeuthen
60e7ae26af GDBus: Add GDBusAuthObserver param in g_dbus_connection_new_for_address()
This is to match g_dbus_connection_new(). This extension allows us to
extend GDBusAuthObserver to also be used in client-side authentication
in the future (right now it's only used on the server-side).
2010-05-13 16:32:11 -04:00
Matthias Clasen
107b4d4bae remove the redundant interface_name parameter 2010-05-13 13:09:58 -04:00
Matthias Clasen
e4b1e48fca Match up parameter names
and similar cleanups to make gtk-doc happy.
2010-05-11 20:57:44 -04:00
David Zeuthen
869b4c6833 GDBus: Use call() instead of invoke_method()
Lots of people been suggesting this. We still use MethodInvocation /
method_invocation for handling incoming method calls so use call()
instead of invoke_method() helps to separate the client and server
facilities. Which is a good thing(tm).
2010-05-10 11:47:08 -04:00
Matthias Clasen
0cf467c2ca Update copyright years to include 2010 2010-05-09 13:14:55 -04:00
David Zeuthen
0fd6498cd8 Add "Since: 2.26" to all new GDBus API 2010-05-06 16:02:08 -04:00
David Zeuthen
d0a14469d0 Initial GDBus code-drop from GDBus-standalone repo
Things compile and the test-suite passes. Still need to hook up
gio.symbols and docs. There are still a bunch of TODOs left in the
sources that needs to be addressed.

Signed-off-by: David Zeuthen <davidz@redhat.com>
2010-05-06 14:21:32 -04:00