From 29e9a62c1da12f45113779235796ccbb4226d7d8 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Sun, 16 Dec 2012 11:47:54 +0100 Subject: Update annotations from glib git --- gir/gio-2.0.c | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++- gir/glib-2.0.c | 54 ++++++++++++------------- gir/gobject-2.0.c | 14 +++++++ 3 files changed, 155 insertions(+), 29 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index db413910..fa453370 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -5608,6 +5608,33 @@ */ +/** + * SECTION:gnetworking + * @title: gnetworking.h + * @short_description: System networking includes + * @include: gio/gnetworking.h + * + * The gnetworking.h header can be included to get + * various low-level networking-related system headers, automatically + * taking care of certain portability issues for you. + * + * This can be used, for example, if you want to call setsockopt() + * on a #GSocket. + * + * Note that while WinSock has many of the same APIs as the + * traditional UNIX socket API, most of them behave at least slightly + * differently (particularly with respect to error handling). If you + * want your code to work under both UNIX and Windows, you will need + * to take these differences into account. + * + * Also, under glibc, certain non-portable functions are only visible + * in the headers if you define _GNU_SOURCE before + * including them. Note that this symbol must be defined before + * including any headers, or it may not take + * effect. + */ + + /** * SECTION:gnetworkmonitor * @title: GNetworkMonitor @@ -6446,7 +6473,7 @@ * SECTION:gsocket * @short_description: Low-level socket object * @include: gio/gio.h - * @see_also: #GInitable + * @see_also: #GInitable, gnetworking.h * * A #GSocket is a low-level networking primitive. It is a more or less * direct mapping of the BSD socket API in a portable GObject based API. @@ -18486,6 +18513,27 @@ */ +/** + * g_file_enumerator_get_child: + * @enumerator: a #GFileEnumerator + * @info: a #GFileInfo gotten from g_file_enumerator_next_file() or the async equivalents. + * + * Return a new #GFile which refers to the file named by @info in the source + * directory of @enumerator. This function is primarily intended to be used + * inside loops with g_file_enumerator_next_file(). + * + * This is a convenience method that's equivalent to: + * |[ + * gchar *name = g_file_info_get_name (info); + * GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr), + * name); + * ]| + * + * Returns: (transfer full): a #GFile for the #GFileInfo passed it. + * Since: 2.36 + */ + + /** * g_file_enumerator_get_container: * @enumerator: a #GFileEnumerator @@ -21149,7 +21197,7 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if there was any error, %FALSE otherwise. + * Returns: %FALSE if there was any error, %TRUE otherwise. */ @@ -24978,6 +25026,18 @@ */ +/** + * g_networking_init: + * + * Initializes the platform networking libraries (eg, on Windows, this + * calls WSAStartup()). GLib will call this itself if it is needed, so + * you only need to call it if you directly call system networking + * functions (without calling any GLib networking functions first). + * + * Since: 2.36 + */ + + /** * g_null_settings_backend_new: * @@ -29835,6 +29895,34 @@ */ +/** + * g_socket_get_option: + * @socket: a #GSocket + * @level: the "API level" of the option (eg, SOL_SOCKET) + * @optname: the "name" of the option (eg, SO_BROADCAST) + * @value: (out): return location for the option value + * @error: #GError for error reporting, or %NULL to ignore. + * + * Gets the value of an integer-valued option on @socket, as with + * getsockopt (). (If you need to fetch a + * non-integer-valued option, you will need to call + * getsockopt () directly.) + * + * The <gio/gnetworking.h> + * header pulls in system headers that will define most of the + * standard/portable socket options. For unusual socket protocols or + * platform-dependent options, you may need to include additional + * headers. + * + * Note that even for socket options that are a single byte in size, + * @value is still a pointer to a #gint variable, not a #guchar; + * g_socket_get_option() will handle the conversion internally. + * + * Returns: success or failure. On failure, @error will be set, and the system error value (errno or WSAGetLastError ()) will still be set to the result of the getsockopt () call. + * Since: 2.36 + */ + + /** * g_socket_get_protocol: * @socket: a #GSocket. @@ -30698,6 +30786,30 @@ */ +/** + * g_socket_set_option: + * @socket: a #GSocket + * @level: the "API level" of the option (eg, SOL_SOCKET) + * @optname: the "name" of the option (eg, SO_BROADCAST) + * @value: the value to set the option to + * @error: #GError for error reporting, or %NULL to ignore. + * + * Sets the value of an integer-valued option on @socket, as with + * setsockopt (). (If you need to set a + * non-integer-valued option, you will need to call + * setsockopt () directly.) + * + * The <gio/gnetworking.h> + * header pulls in system headers that will define most of the + * standard/portable socket options. For unusual socket protocols or + * platform-dependent options, you may need to include additional + * headers. + * + * Returns: success or failure. On failure, @error will be set, and the system error value (errno or WSAGetLastError ()) will still be set to the result of the setsockopt () call. + * Since: 2.36 + */ + + /** * g_socket_set_timeout: * @socket: a #GSocket. diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index ec3aa02b..4c858e20 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -10975,7 +10975,7 @@ /** - * g_checksum_get_digest: + * g_checksum_get_digest: (skip) * @checksum: a #GChecksum * @buffer: output buffer * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest. @@ -11024,7 +11024,7 @@ * will be closed and it won't be possible to call g_checksum_update() * on it anymore. * - * Returns: the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. + * Returns: (transfer full): the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. * Since: 2.16 */ @@ -11053,7 +11053,7 @@ /** * g_checksum_update: * @checksum: a #GChecksum - * @data: buffer used to compute the checksum + * @data: (array length=length) (element-type guint8): buffer used to compute the checksum * @length: size of the buffer, or -1 if it is a null-terminated string. * * Feeds @data into an existing #GChecksum. The checksum must still be @@ -11232,7 +11232,7 @@ /** * g_compute_checksum_for_data: * @checksum_type: a #GChecksumType - * @data: binary blob to compute the digest of + * @data: (array length=length) (element-type guint8): binary blob to compute the digest of * @length: length of @data * * Computes the checksum for a binary @data of @length. This is a @@ -14516,31 +14516,31 @@ /** * g_get_home_dir: * - * Gets the current user's home directory as defined in the - * password database. + * Gets the current user's home directory. * - * Note that in contrast to traditional UNIX tools, this function - * prefers passwd entries over the HOME - * environment variable. + * As with most UNIX tools, this function will return the value of the + * HOME environment variable if it is set to an existing + * absolute path name, falling back to the passwd + * file in the case that it is unset. * - * One of the reasons for this decision is that applications in many - * cases need special handling to deal with the case where - * HOME is - * - * Not owned by the user - * Not writeable - * Not even readable - * - * Since applications are in general not written - * to deal with these situations it was considered better to make - * g_get_home_dir() not pay attention to HOME and to - * return the real home directory for the user. If applications - * want to pay attention to HOME, they can do: - * |[ - * const char *homedir = g_getenv ("HOME"); - * if (!homedir) - * homedir = g_get_home_dir (); - * ]| + * If the path given in HOME is non-absolute, does not + * exist, or is not a directory, the result is undefined. + * + * + * Before version 2.36 this function would ignore the + * HOME environment variable, taking the value from the + * passwd database instead. This was changed to + * increase the compatibility of GLib with other programs (and the XDG + * basedir specification) and to increase testability of programs + * based on GLib (by making it easier to run them from test + * frameworks). + * + * If your program has a strong requirement for either the new or the + * old behaviour (and if you don't wish to increase your GLib + * dependency to ensure that the new behaviour is in effect) then you + * should either directly check the HOME environment + * variable yourself or unset it before calling any functions in GLib. + * * * Returns: the current user's home directory */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index fff5b1b0..fe54ac1c 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -4574,6 +4574,20 @@ */ +/** + * g_type_get_type_registration_serial: + * + * Returns an opaque serial number that represents the state of the set of registered + * types. Any time a type is registred this serial changes, which means you can + * cache information based on type lookups (such as g_type_from_name) and know if + * the cache is still valid at a later time by comparing the current serial with + * the one at the type lookup. + * + * Since: 2.36 + * Returns: An unsigned int, representing the state of type registrations. + */ + + /** * g_type_init: * -- cgit v1.2.1