From 6ea86cc57f1b8b8c7acc4e08ece8baef5f28a53a Mon Sep 17 00:00:00 2001 From: Alexander Larsson Date: Mon, 18 May 2009 13:02:11 +0200 Subject: [PATCH] Update the docs for the new network APIs This imports the network APIs into the gio reference docs, and cleans up a bunch of gtk-doc warnings and documentation issues. --- docs/reference/gio/gio-docs.xml | 45 ++- docs/reference/gio/gio-sections.txt | 350 +++++++++++++++++++++- docs/reference/gio/gio.types | 20 +- docs/reference/gio/overview.xml | 28 ++ docs/reference/glib/tmpl/glib-unused.sgml | 67 +++++ docs/reference/glib/tmpl/macros_misc.sgml | 5 +- docs/reference/glib/tmpl/version.sgml | 68 ----- gio/gasyncinitable.c | 7 +- gio/gfile.c | 2 +- gio/gfile.h | 9 + gio/gfileenumerator.c | 2 +- gio/gfileiostream.c | 10 +- gio/ginetsocketaddress.c | 2 +- gio/ginitable.c | 9 +- gio/gioenums.h | 5 +- gio/giostream.c | 9 +- gio/giotypes.h | 2 + gio/gmount.c | 2 +- gio/gmount.h | 1 + gio/gsocket.c | 4 +- gio/gsocket.h | 5 - gio/gsocketclient.c | 25 +- gio/gsocketclient.h | 8 +- gio/gsocketconnection.c | 17 +- gio/gsocketconnection.h | 2 +- gio/gsocketlistener.c | 10 +- gio/gsocketservice.c | 3 +- gio/gthemedicon.c | 6 +- gio/gunixconnection.c | 2 +- gio/gunixsocketaddress.c | 2 +- 30 files changed, 576 insertions(+), 151 deletions(-) diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml index c0dd31d7a..7ef921d8f 100644 --- a/docs/reference/gio/gio-docs.xml +++ b/docs/reference/gio/gio-docs.xml @@ -45,9 +45,11 @@ + + @@ -90,19 +92,38 @@ - - Networking - - - - - - - - - + + Failable Initialization + + - + + Lowlevel platform-independent network support + + + + + + + + + + DNS resolution + + + + + + + + Highlevel network functionallity + + + + + + + Utilities diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt index 88b757f00..8b52e8386 100644 --- a/docs/reference/gio/gio-sections.txt +++ b/docs/reference/gio/gio-sections.txt @@ -1,3 +1,43 @@ +
+ginitable +GInitable +GInitable +GInitableIface +g_initable_init +g_initable_new +g_initable_new_valist +g_initable_newv + +G_INITABLE +G_INITABLE_GET_IFACE +G_IS_INITABLE +G_TYPE_INITABLE +G_TYPE_IS_INITABLE + +g_initable_get_type +
+ +
+gasyncinitable +GAsyncInitable +GAsyncInitable +GAsyncInitableIface +g_async_initable_init_async +g_async_initable_init_finish +g_async_initable_new_async +g_async_initable_new_finish +g_async_initable_new_valist_async +g_async_initable_newv_async + +G_ASYNC_INITABLE +G_ASYNC_INITABLE_GET_IFACE +G_IS_ASYNC_INITABLE +G_TYPE_ASYNC_INITABLE +G_TYPE_IS_ASYNC_INITABLE + +g_async_initable_get_type +
+
gvfs GVfs @@ -125,6 +165,15 @@ g_file_replace_contents g_file_replace_contents_async g_file_replace_contents_finish g_file_copy_attributes +g_file_create_readwrite +g_file_create_readwrite_async +g_file_create_readwrite_finish +g_file_open_readwrite +g_file_open_readwrite_async +g_file_open_readwrite_finish +g_file_replace_readwrite +g_file_replace_readwrite_async +g_file_replace_readwrite_finish G_FILE G_IS_FILE @@ -453,6 +502,7 @@ g_emblem_new_with_origin g_emblem_get_icon g_emblem_get_origin +GEmblemClass g_emblem_get_type G_EMBLEM G_EMBLEM_CLASS @@ -530,7 +580,6 @@ G_IS_FILTER_INPUT_STREAM_CLASS G_FILTER_INPUT_STREAM_GET_CLASS g_filter_input_stream_get_type -GFilterInputStreamPrivate
@@ -712,7 +761,6 @@ G_IS_FILTER_OUTPUT_STREAM_CLASS G_FILTER_OUTPUT_STREAM_GET_CLASS g_filter_output_stream_get_type -GFilterOutputStreamPrivate
@@ -786,7 +834,6 @@ G_DATA_OUTPUT_STREAM_GET_CLASS g_data_output_stream_get_type GDataOutputStreamPrivate -
@@ -810,6 +857,53 @@ g_unix_output_stream_get_type GUnixOutputStreamPrivate
+
+giostream +GIOStream +GIOStream +g_io_stream_clear_pending +g_io_stream_close +g_io_stream_close_async +g_io_stream_close_finish +g_io_stream_get_input_stream +g_io_stream_get_output_stream +g_io_stream_has_pending +g_io_stream_is_closed +g_io_stream_set_pending + +GIOStreamClass +G_IO_STREAM +G_IO_STREAM_CLASS +G_IO_STREAM_GET_CLASS +G_IS_IO_STREAM +G_IS_IO_STREAM_CLASS +G_TYPE_IO_STREAM + +GIOStreamPrivate +g_io_stream_get_type +
+ +
+gfileiostream +GFileIOStream +GFileIOStream +g_file_io_stream_get_etag +g_file_io_stream_query_info +g_file_io_stream_query_info_async +g_file_io_stream_query_info_finish + +GFileIOStreamClass +G_FILE_IO_STREAM +G_FILE_IO_STREAM_CLASS +G_FILE_IO_STREAM_GET_CLASS +G_IS_FILE_IO_STREAM +G_IS_FILE_IO_STREAM_CLASS +G_TYPE_FILE_IO_STREAM + +GFileIOStreamPrivate +g_file_io_stream_get_type +
+
gseekable GSeekable @@ -1449,8 +1543,7 @@ g_srv_target_get_hostname g_srv_target_get_port g_srv_target_get_priority g_srv_target_get_weight -g_srv_target_get_expires -g_srv_target_array_sort +g_srv_target_list_sort G_TYPE_SRV_TARGET @@ -1491,8 +1584,8 @@ g_socket_connectable_get_type GNetworkAddress g_network_address_new g_network_address_get_hostname -g_network_address_get_ascii_name g_network_address_get_port +g_network_address_parse GNetworkAddressClass GNetworkAddressPrivate @@ -1514,7 +1607,6 @@ g_network_service_new g_network_service_get_service g_network_service_get_protocol g_network_service_get_domain -g_network_service_get_expires GNetworkServiceClass GNetworkServicePrivate @@ -1527,3 +1619,247 @@ G_TYPE_NETWORK_SERVICE g_network_service_get_type
+ +
+gsocket +GSocket +GSocket +GSocketSourceFunc +GSocketType +GSocketMsgFlags +g_socket_new +g_socket_new_from_fd +g_socket_bind +g_socket_listen +g_socket_accept +g_socket_connect +g_socket_check_pending_error +g_socket_receive +g_socket_receive_from +g_socket_receive_message +g_socket_send +g_socket_send_to +g_socket_send_message +g_socket_close +g_socket_is_closed +g_socket_is_connected +g_socket_create_source +g_socket_condition_check +g_socket_condition_wait +g_socket_set_listen_backlog +g_socket_get_listen_backlog +g_socket_get_blocking +g_socket_set_blocking +g_socket_get_keepalive +g_socket_set_keepalive +g_socket_get_family +g_socket_get_fd +g_socket_get_local_address +g_socket_get_protocol_id +g_socket_get_protocol_name +g_socket_get_remote_address +g_socket_get_socket_type +g_socket_protocol_id_lookup_by_name + +GSocketClass +G_IS_SOCKET +G_IS_SOCKET_CLASS +G_SOCKET +G_SOCKET_CLASS +G_TYPE_SOCKET +G_SOCKET_GET_CLASS + +g_socket_get_type +GSocketPrivate +
+ +
+gsocketclient +GSocketClient +GSocketClient +g_socket_client_new +g_socket_client_connect +g_socket_client_connect_async +g_socket_client_connect_finish +g_socket_client_connect_to_host +g_socket_client_connect_to_host_async +g_socket_client_connect_to_host_finish +g_socket_client_set_family +g_socket_client_set_local_address +g_socket_client_set_protocol +g_socket_client_set_socket_type +g_socket_client_get_family +g_socket_client_get_local_address +g_socket_client_get_protocol +g_socket_client_get_socket_type + +GSocketClientClass +G_IS_SOCKET_CLIENT +G_IS_SOCKET_CLIENT_CLASS +G_SOCKET_CLIENT +G_SOCKET_CLIENT_CLASS +G_SOCKET_CLIENT_GET_CLASS +G_TYPE_SOCKET_CLIENT + +GSocketClientPrivate +g_socket_client_get_type +
+ +
+gsocketconnection +GSocketConnection +GSocketConnection +g_socket_connection_get_local_address +g_socket_connection_get_remote_address +g_socket_connection_get_socket + +GTcpConnection + +GUnixConnection +g_unix_connection_receive_fd +g_unix_connection_send_fd + +g_socket_connection_factory_create_connection +g_socket_connection_factory_lookup_type +g_socket_connection_factory_register_type + +GSocketConnectionClass +G_IS_SOCKET_CONNECTION +G_IS_SOCKET_CONNECTION_CLASS +G_SOCKET_CONNECTION +G_SOCKET_CONNECTION_CLASS +G_SOCKET_CONNECTION_GET_CLASS +G_TYPE_SOCKET_CONNECTION +GTcpConnectionClass +G_IS_TCP_CONNECTION +G_IS_TCP_CONNECTION_CLASS +G_TCP_CONNECTION +G_TCP_CONNECTION_CLASS +G_TCP_CONNECTION_GET_CLASS +G_TYPE_TCP_CONNECTION +GUnixConnectionClass +G_IS_UNIX_CONNECTION +G_IS_UNIX_CONNECTION_CLASS +G_TYPE_UNIX_CONNECTION +G_UNIX_CONNECTION +G_UNIX_CONNECTION_CLASS +G_UNIX_CONNECTION_GET_CLASS + +GSocketConnectionPrivate +g_socket_connection_get_type +GTcpConnectionPrivate +g_tcp_connection_get_type +GUnixConnectionPrivate +g_unix_connection_get_type +
+ +
+gsocketcontrolmessage +GSocketControlMessage +GSocketControlMessage +g_socket_control_message_deserialize +g_socket_control_message_get_level +g_socket_control_message_get_msg_type +g_socket_control_message_get_size +g_socket_control_message_serialize + +GSocketControlMessageClass +G_IS_SOCKET_CONTROL_MESSAGE +G_IS_SOCKET_CONTROL_MESSAGE_CLASS +G_SOCKET_CONTROL_MESSAGE +G_SOCKET_CONTROL_MESSAGE_CLASS +G_SOCKET_CONTROL_MESSAGE_GET_CLASS +G_TYPE_SOCKET_CONTROL_MESSAGE + +GSocketControlMessagePrivate +g_socket_control_message_get_type +
+ +
+gsocketlistener +GSocketListener +GSocketListener +g_socket_listener_new +g_socket_listener_add_socket +g_socket_listener_add_address +g_socket_listener_add_inet_port +g_socket_listener_accept +g_socket_listener_accept_async +g_socket_listener_accept_finish +g_socket_listener_accept_socket +g_socket_listener_accept_socket_async +g_socket_listener_accept_socket_finish +g_socket_listener_close +g_socket_listener_set_backlog + +GSocketListenerClass +G_IS_SOCKET_LISTENER +G_IS_SOCKET_LISTENER_CLASS +G_SOCKET_LISTENER +G_SOCKET_LISTENER_CLASS +G_SOCKET_LISTENER_GET_CLASS +G_TYPE_SOCKET_INPUT_STREAM +G_TYPE_SOCKET_LISTENER + +GSocketListenerPrivate +g_socket_listener_get_type +
+ +
+gsocketservice +GSocketService +GSocketService +g_socket_service_new +g_socket_service_start +g_socket_service_stop +g_socket_service_is_active + +GSocketServiceClass +G_IS_SOCKET_SERVICE +G_IS_SOCKET_SERVICE_CLASS +G_SOCKET_SERVICE +G_SOCKET_SERVICE_CLASS +G_SOCKET_SERVICE_GET_CLASS +G_TYPE_SOCKET_SERVICE + +GSocketServicePrivate +g_socket_service_get_type +
+ +
+gthreadedsocketservice +GThreadedSocketService +GThreadedSocketService +g_threaded_socket_service_new + +GThreadedSocketServiceClass +G_IS_THREADED_SOCKET_SERVICE +G_IS_THREADED_SOCKET_SERVICE_CLASS +G_THREADED_SOCKET_SERVICE +G_THREADED_SOCKET_SERVICE_CLASS +G_THREADED_SOCKET_SERVICE_GET_CLASS +G_TYPE_THREADED_SOCKET_SERVICE + +GThreadedSocketServicePrivate +g_threaded_socket_service_get_type +
+ +
+gunixfdmessage +GUnixFDMessage +GUnixFDMessage +g_unix_fd_message_new +g_unix_fd_message_append_fd +g_unix_fd_message_steal_fds + +GUnixFDMessageClass +G_IS_UNIX_FD_MESSAGE +G_IS_UNIX_FD_MESSAGE_CLASS +G_TYPE_UNIX_FD_MESSAGE +G_UNIX_FD_MESSAGE +G_UNIX_FD_MESSAGE_CLASS +G_UNIX_FD_MESSAGE_GET_CLASS + +GUnixFDMessagePrivate +g_unix_fd_message_get_type +
diff --git a/docs/reference/gio/gio.types b/docs/reference/gio/gio.types index 2fe81cd76..e6cbdffe5 100644 --- a/docs/reference/gio/gio.types +++ b/docs/reference/gio/gio.types @@ -2,6 +2,7 @@ g_app_info_create_flags_get_type g_app_info_get_type g_app_launch_context_get_type g_ask_password_flags_get_type +g_async_initable_get_type g_async_result_get_type g_buffered_input_stream_get_type g_buffered_output_stream_get_type @@ -13,8 +14,8 @@ g_data_stream_newline_type_get_type g_desktop_app_info_get_type g_desktop_app_info_lookup_get_type g_drive_get_type -g_emblemed_icon_get_type g_emblem_get_type +g_emblemed_icon_get_type g_file_attribute_info_flags_get_type g_file_attribute_status_get_type g_file_attribute_type_get_type @@ -25,22 +26,25 @@ g_file_get_type g_file_icon_get_type g_file_info_get_type g_file_input_stream_get_type +g_file_io_stream_get_type g_file_monitor_event_get_type g_file_monitor_flags_get_type g_file_monitor_get_type -g_filename_completer_get_type g_file_output_stream_get_type g_file_query_info_flags_get_type -g_filesystem_preview_type_get_type g_file_type_get_type +g_filename_completer_get_type +g_filesystem_preview_type_get_type g_filter_input_stream_get_type g_filter_output_stream_get_type g_icon_get_type g_inet_address_get_type g_inet_socket_address_get_type +g_initable_get_type g_input_stream_get_type g_io_error_enum_get_type g_io_module_get_type +g_io_stream_get_type g_loadable_icon_get_type g_local_directory_monitor_get_type g_local_file_monitor_get_type @@ -62,8 +66,18 @@ g_seekable_get_type g_simple_async_result_get_type g_socket_address_enumerator_get_type g_socket_address_get_type +g_socket_client_get_type g_socket_connectable_get_type +g_socket_connection_get_type +g_socket_control_message_get_type +g_socket_get_type +g_socket_listener_get_type +g_socket_service_get_type +g_tcp_connection_get_type g_themed_icon_get_type +g_threaded_socket_service_get_type +g_unix_connection_get_type +g_unix_fd_message_get_type g_unix_input_stream_get_type g_unix_mount_monitor_get_type g_unix_output_stream_get_type diff --git a/docs/reference/gio/overview.xml b/docs/reference/gio/overview.xml index a55c4638e..99649212e 100644 --- a/docs/reference/gio/overview.xml +++ b/docs/reference/gio/overview.xml @@ -53,6 +53,10 @@ GOutputStream write data + + GIOStream + read and write data + GSeekable interface optionally implemented by streams to support seeking @@ -70,6 +74,30 @@ abstract type for file and application icons + There is support for network programming, including name resolution, lowlevel socket + APIs and highlevel client and server helper classes: + + + GSocket + lowlevel platform independent socket object + + + GResolver + asynchronous and cancellable DNS resolver + + + GSocketClient + high-level network client helper + + + GSocketService + high-level network server helper + + + GSocketConnection + network connection stream + + Beyond these, GIO provides facilities for file monitoring, asynchronous I/O and filename completion. In addition to the interfaces, GIO provides implementations for the local case. diff --git a/docs/reference/glib/tmpl/glib-unused.sgml b/docs/reference/glib/tmpl/glib-unused.sgml index ca73e16e9..139c5004a 100644 --- a/docs/reference/glib/tmpl/glib-unused.sgml +++ b/docs/reference/glib/tmpl/glib-unused.sgml @@ -900,6 +900,73 @@ Turns the argument into a string literal by using the '#' stringizing operator. + + +This is the binary age passed to libtool. If +libtool means nothing to you, don't worry +about it. ;-) + + + + + + + + +@required_major: +@required_minor: +@required_micro: +@Returns: + + + +This is the interface age passed to libtool. If +libtool means nothing to you, don't worry +about it. ;-) + + + + + +The major version number of the GLib library. +(e.g. in GLib version 1.2.5 this is 1.) + + + +This variable is in the library, so represents the +GLib library you have linked against. Contrast with the +#GLIB_MAJOR_VERSION macro, which represents the major version of the +GLib headers you have included. + + + + + +The micro version number of the GLib library. +(e.g. in GLib version 1.2.5 this is 5.) + + + +This variable is in the library, so represents the GLib library you +have linked against. Contrast with the #GLIB_MICRO_VERSION macro, which +represents the micro version of the GLib headers you have included. + + + + + +The minor version number of the GLib library. +(e.g. in GLib version 1.2.5 this is 2.) + + + +This variable is in the library, so represents the +GLib library you have linked against. Contrast with the +#GLIB_MINOR_VERSION macro, which represents the minor version of the +GLib headers you have included. + + + diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml index d37b01b0f..9dbd65cb1 100644 --- a/docs/reference/glib/tmpl/macros_misc.sgml +++ b/docs/reference/glib/tmpl/macros_misc.sgml @@ -403,7 +403,7 @@ Since: 2.14 - + Hints the compiler that the expression is likely to evaluate to a true value. The compiler may use this information for optimizations. @@ -413,10 +413,9 @@ if (G_LIKELY (random () != 1)) g_print ("not one"); +@expr: the expression @Returns: the value of @expr @Since: 2.2 - -@expr: the expression diff --git a/docs/reference/glib/tmpl/version.sgml b/docs/reference/glib/tmpl/version.sgml index f46c1e1a5..b1cf0bb6f 100644 --- a/docs/reference/glib/tmpl/version.sgml +++ b/docs/reference/glib/tmpl/version.sgml @@ -19,74 +19,6 @@ typically use the features described here. - - -The major version number of the GLib library. -(e.g. in GLib version 1.2.5 this is 1.) - - - -This variable is in the library, so represents the -GLib library you have linked against. Contrast with the -#GLIB_MAJOR_VERSION macro, which represents the major version of the -GLib headers you have included. - - - - - -The minor version number of the GLib library. -(e.g. in GLib version 1.2.5 this is 2.) - - - -This variable is in the library, so represents the -GLib library you have linked against. Contrast with the -#GLIB_MINOR_VERSION macro, which represents the minor version of the -GLib headers you have included. - - - - - -The micro version number of the GLib library. -(e.g. in GLib version 1.2.5 this is 5.) - - - -This variable is in the library, so represents the GLib library you -have linked against. Contrast with the #GLIB_MICRO_VERSION macro, which -represents the micro version of the GLib headers you have included. - - - - - -This is the binary age passed to libtool. If -libtool means nothing to you, don't worry -about it. ;-) - - - - - -This is the interface age passed to libtool. If -libtool means nothing to you, don't worry -about it. ;-) - - - - - - - - -@required_major: -@required_minor: -@required_micro: -@Returns: - - The major version number of the GLib library. diff --git a/gio/gasyncinitable.c b/gio/gasyncinitable.c index 5b9b2c722..9c10c4f62 100644 --- a/gio/gasyncinitable.c +++ b/gio/gasyncinitable.c @@ -243,8 +243,9 @@ g_async_initable_real_init_finish (GAsyncInitable *initable, * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the initialization is finished * @user_data: the data to pass to callback function - * @first_property_name: the name of the first property, followed by - * the value, and other property value pairs, and ended by %NULL. + * @first_property_name: the name of the first property, or %NULL if no properties + * @...: the value if the first property, followed by and other property + * value pairs, and ended by %NULL. * * Helper function for constructing #GAsyncInitiable object. This is * similar to g_object_new() but also initializes the object asyncronously. @@ -313,7 +314,7 @@ g_async_initable_newv_async (GType object_type, } /** - * g_async_initable_new_async: + * g_async_initable_new_valist_async: * @object_type: a #GType supporting #GAsyncInitable. * @first_property_name: the name of the first property, followed by * the value, and other property value pairs, and ended by %NULL. diff --git a/gio/gfile.c b/gio/gfile.c index 83f0f4644..493ae6b8b 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -1779,7 +1779,7 @@ g_file_create_readwrite (GFile *file, } /** - * g_file_replace: + * g_file_replace_readwrite: * @file: input #GFile. * @etag: an optional entity tag for the * current #GFile, or #NULL to ignore. diff --git a/gio/gfile.h b/gio/gfile.h index 1b86d1565..aeb372e97 100644 --- a/gio/gfile.h +++ b/gio/gfile.h @@ -132,6 +132,15 @@ typedef struct _GFileIface GFileIface; * @mount_enclosing_volume_finish: Finishes mounting a specified location. * @monitor_dir: Creates a #GFileMonitor for the location. * @monitor_file: Creates a #GFileMonitor for the location. + * @open_readwrite: Open file read/write. Since 2.22. + * @open_readwrite_async: Asynchronously opens file read/write. Since 2.22. + * @open_readwrite_finish: Finishes an asynchronous open read/write. Since 2.22. + * @create_readwrite: Creates file read/write. Since 2.22. + * @create_readwrite_async: Asynchronously creates file read/write. Since 2.22. + * @create_readwrite_finish: Finishes an asynchronous creates read/write. Since 2.22. + * @replace_readwrite: Replaces file read/write. Since 2.22. + * @replace_readwrite_async: Asynchronously replaces file read/write. Since 2.22. + * @replace_readwrite_finish: Finishes an asynchronous replace read/write. Since 2.22. * * An interface for writing VFS file handles. **/ diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c index 579215f0e..3577bb6d4 100644 --- a/gio/gfileenumerator.c +++ b/gio/gfileenumerator.c @@ -589,7 +589,7 @@ g_file_enumerator_set_pending (GFileEnumerator *enumerator, * * Returns: the #GFile which is being enumerated. * - * Since: 2.18. + * Since: 2.18 */ GFile * g_file_enumerator_get_container (GFileEnumerator *enumerator) diff --git a/gio/gfileiostream.c b/gio/gfileiostream.c index 3cc72ed76..14cdbfefd 100644 --- a/gio/gfileiostream.c +++ b/gio/gfileiostream.c @@ -36,7 +36,7 @@ /** * SECTION:gfileiostream - * @short_description: read write streams for File + * @short_description: File read and write streaming operations * @include: gio/gio.h * @see_also: #GIOStream, #GFileInputStream, #GFileOutputStream, #GSeekable * @@ -49,13 +49,17 @@ * operations. In addition to the generic g_seekable_ API, * GFileIOStream has its own API for seeking and positioning. * To find the position of a file io stream, use - * g_file_io_stream_tell(). To find out if a file io - * stream supports seeking, use g_file_io_stream_can_seek(). + * g_file_io_stream_tell(). + * + * To find out if a file io stream supports seeking, use g_file_io_stream_can_seek(). * To position a file io stream, use g_file_io_stream_seek(). * To find out if a file io stream supports truncating, use * g_file_io_stream_can_truncate(). To truncate a file io * stream, use g_file_io_stream_truncate(). * + * The default implementation of all the #GFileIOStream operations + * and the implementation of #GSeekable just call into the same operations + * on the output stream. * Since: 2.22 **/ diff --git a/gio/ginetsocketaddress.c b/gio/ginetsocketaddress.c index b8275a8d4..cd07dc628 100644 --- a/gio/ginetsocketaddress.c +++ b/gio/ginetsocketaddress.c @@ -33,7 +33,7 @@ /** * SECTION:ginetsocketaddress - * @short_description: Internet socket addresses + * @short_description: Internet #GSocketAddress * * An IPv4 or IPv6 socket address; that is, the combination of a * #GInetAddress and a port number. diff --git a/gio/ginitable.c b/gio/ginitable.c index cc4ca3f53..29b60ddce 100644 --- a/gio/ginitable.c +++ b/gio/ginitable.c @@ -135,9 +135,10 @@ g_initable_init (GInitable *initable, * @object_type: a #GType supporting #GInitable. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occuring, or %NULL to - * ignore. - * @first_property_name: the name of the first property, followed by - * the value, and other property value pairs, and ended by %NULL. + * ignore. + * @first_property_name: the name of the first property, or %NULL if no properties + * @...: the value if the first property, followed by and other property + * value pairs, and ended by %NULL. * * Helper function for constructing #GInitiable object. This is * similar to g_object_new() but also initializes the object @@ -167,7 +168,7 @@ g_initable_new (GType object_type, } /** - * g_initable_new: + * g_initable_newv: * @object_type: a #GType supporting #GInitable. * @n_parameters: the number of parameters in @parameters * @parameters: the parameters to use to construct the object diff --git a/gio/gioenums.h b/gio/gioenums.h index 9d9581d7e..2f5ad760a 100644 --- a/gio/gioenums.h +++ b/gio/gioenums.h @@ -464,7 +464,7 @@ typedef enum { /** * GEmblemOrigin: * @G_EMBLEM_ORIGIN_UNKNOWN: Emblem of unknown origin - * @G_EMBLEM_ORIGIN_DEVICE: Embleme adds device-specific information + * @G_EMBLEM_ORIGIN_DEVICE: Emblem adds device-specific information * @G_EMBLEM_ORIGIN_LIVEMETADATA: Emblem depicts live metadata, such as "readonly" * @G_EMBLEM_ORIGIN_TAG: Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) * @@ -536,6 +536,7 @@ typedef enum /** * GSocketMsgFlags: + * @G_SOCKET_MSG_NONE: No flags. * @G_SOCKET_MSG_OOB: Request to send/receive out of band data. * @G_SOCKET_MSG_PEEK: Read data from the socket without removing it from the queue. * @G_SOCKET_MSG_DONTROUTE: Don't use a gateway to send out the packet, only send to hosts on directly connected networks. @@ -549,7 +550,7 @@ typedef enum */ typedef enum { - G_SOCKET_MSG_INVALID, + G_SOCKET_MSG_NONE, G_SOCKET_MSG_OOB = GLIB_SYSDEF_MSG_OOB, G_SOCKET_MSG_PEEK = GLIB_SYSDEF_MSG_PEEK, G_SOCKET_MSG_DONTROUTE = GLIB_SYSDEF_MSG_DONTROUTE diff --git a/gio/giostream.c b/gio/giostream.c index 6c3a07303..7669734d7 100644 --- a/gio/giostream.c +++ b/gio/giostream.c @@ -35,15 +35,20 @@ G_DEFINE_TYPE (GIOStream, g_io_stream, G_TYPE_OBJECT); /** - * SECTION:ginputstream - * @short_description: Base class for implementing readwrite streams + * SECTION:giostream + * @short_description: Base class for implementing read/write streams * @include: gio/gio.h + * @see_also: #GInputStream, #GOutputStream * * GIOStream represents an object that has both read and write streams. * Generally the two streams acts as separate input and output streams, * but they share some common resources and state. For instance, for * seekable streams they may use the same position in both streams. * + * Examples of #GIOStream objects are #GSocketConnection which represents + * a two-way network connection, and #GFileIOStream which represent a + * file handle opened in read-write mode. + * * To do the actual reading and writing you need to get the substreams * with g_io_stream_get_input_stream() and g_io_stream_get_output_stream(). * diff --git a/gio/giotypes.h b/gio/giotypes.h index 2a7fbac2b..7b386e732 100644 --- a/gio/giotypes.h +++ b/gio/giotypes.h @@ -280,6 +280,8 @@ typedef void (*GSimpleAsyncThreadFunc) (GSimpleAsyncResult *res, * This is the function type of the callback used for the #GSource * returned by g_socket_create_source(). * + * Returns: it should return FALSE if the source should be removed. + * * Since: 2.22 */ typedef gboolean (*GSocketSourceFunc) (GSocket *socket, diff --git a/gio/gmount.c b/gio/gmount.c index b8c33955b..e4753c422 100644 --- a/gio/gmount.c +++ b/gio/gmount.c @@ -148,7 +148,7 @@ g_mount_base_init (gpointer g_class) * This signal is emitted when the #GMount is about to be * unmounted. * - * Since: 2.22. + * Since: 2.22 **/ g_signal_new (I_("pre-unmount"), G_TYPE_MOUNT, diff --git a/gio/gmount.h b/gio/gmount.h index a1afe2c6a..41d092ed9 100644 --- a/gio/gmount.h +++ b/gio/gmount.h @@ -44,6 +44,7 @@ typedef struct _GMountIface GMountIface; * @g_iface: The parent interface. * @changed: Changed signal that is emitted when the mount's state has changed. * @unmounted: The unmounted signal that is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. + * @pre_unmount: The pre_unmout signal that is emitted when the #GMount will soon be emitted. If the recipient is somehow holding the mount open by keeping an open file on it it should close the file. * @get_root: Gets a #GFile to the root directory of the #GMount. * @get_name: Gets a string containing the name of the #GMount. * @get_icon: Gets a #GIcon for the #GMount. diff --git a/gio/gsocket.c b/gio/gsocket.c index bf80ce315..0fc09b007 100644 --- a/gio/gsocket.c +++ b/gio/gsocket.c @@ -57,7 +57,7 @@ /** * SECTION:gsocket - * @short_description: Low-level network socket handling + * @short_description: Low-level socket object * @include: gio/gio.h * @see_also: #GInitable * @@ -2441,7 +2441,7 @@ g_socket_condition_wait (GSocket *socket, } /** - * g_socket_send_to: + * g_socket_send_message: * @socket: a #GSocket * @address: a #GSocketAddress, or %NULL * @vectors: an array of #GOutputVector structs diff --git a/gio/gsocket.h b/gio/gsocket.h index 00a987260..b43167d1c 100644 --- a/gio/gsocket.h +++ b/gio/gsocket.h @@ -136,11 +136,6 @@ gssize g_socket_send_to (GSocket const gchar *buffer, gsize size, GError **error); -GSocketControlMessage *g_socket_receive_control_message (GSocket *socket, - GError **error); -gboolean g_socket_send_control_message (GSocket *socket, - GSocketControlMessage *message, - GError **error); gssize g_socket_receive_message (GSocket *socket, GSocketAddress **address, GInputVector *vectors, diff --git a/gio/gsocketclient.c b/gio/gsocketclient.c index 84b9b32a6..ddb13839a 100644 --- a/gio/gsocketclient.c +++ b/gio/gsocketclient.c @@ -43,7 +43,7 @@ /** * SECTION:gsocketclient - * @short_description: High-level client network helper + * @short_description: Helper for connecting to a network service * @include: gio/gio.h * @see_also: #GSocketConnection, #GSocketListener * @@ -223,7 +223,7 @@ g_socket_client_set_property (GObject *object, /** * g_socket_client_get_family: - * @socket: a #GSocket. + * @client: a #GSocketClient. * * Gets the socket family of the socket client. * @@ -241,7 +241,7 @@ g_socket_client_get_family (GSocketClient *client) /** * g_socket_client_set_family: - * @socket: a #GSocket. + * @client: a #GSocketClient. * @family: a #GSocketFamily * * Sets the socket family of the socket client. @@ -268,7 +268,7 @@ g_socket_client_set_family (GSocketClient *client, /** * g_socket_client_get_socket_type: - * @socket: a #GSocket. + * @client: a #GSocketClient. * * Gets the socket type of the socket client. * @@ -286,7 +286,7 @@ g_socket_client_get_socket_type (GSocketClient *client) /** * g_socket_client_set_socket_type: - * @socket: a #GSocket. + * @client: a #GSocketClient. * @type: a #GSocketType * * Sets the socket type of the socket client. @@ -311,7 +311,7 @@ g_socket_client_set_socket_type (GSocketClient *client, /** * g_socket_client_get_protocol: - * @socket: a #GSocket. + * @client: a #GSocketClient. * * Gets the protocol name type of the socket client. * @@ -329,7 +329,7 @@ g_socket_client_get_protocol (GSocketClient *client) /** * g_socket_client_set_protocol: - * @socket: a #GSocket. + * @client: a #GSocketClient. * @protocol: a string, or %NULL * * Sets the protocol of the socket client. @@ -355,7 +355,7 @@ g_socket_client_set_protocol (GSocketClient *client, /** * g_socket_client_get_local_address: - * @socket: a #GSocket. + * @client: a #GSocketClient. * * Gets the local address of the socket client. * @@ -373,8 +373,8 @@ g_socket_client_get_local_address (GSocketClient *client) /** * g_socket_client_set_local_address: - * @socket: a #GSocket. - * @addres: a #GSocketAddress, or %NULL + * @client: a #GSocketClient. + * @address: a #GSocketAddress, or %NULL * * Sets the local address of the socket client. * The sockets created by this object will bound to the @@ -538,12 +538,11 @@ g_socket_client_connect (GSocketClient *client, /** * g_socket_client_connect_to_host: - * @client: a #GTcpClient + * @client: a #SocketClient * @host_and_port: the name and optionally port of the host to connect to * @default_port: the default port to connect to * @cancellable: a #GCancellable, or %NULL * @error: a pointer to a #GError, or %NULL - * @returns: a #GSocketConnection if successful, or %NULL on error * * This is a helper function for g_socket_client_connect(). * @@ -771,7 +770,7 @@ g_socket_client_enumerator_callback (GObject *object, } /** - * g_socket_client_connect_to_host_async: + * g_socket_client_connect_async: * @client: a #GTcpClient * @connectable: a #GSocketConnectable specifying the remote address. * @cancellable: a #GCancellable, or %NULL diff --git a/gio/gsocketclient.h b/gio/gsocketclient.h index d8259b3a6..b70246fa0 100644 --- a/gio/gsocketclient.h +++ b/gio/gsocketclient.h @@ -88,8 +88,8 @@ GSocketConnection * g_socket_client_connect (GSocket GCancellable *cancellable, GError **error); GSocketConnection * g_socket_client_connect_to_host (GSocketClient *client, - const char *hostname, - int port, + const char *host_and_port, + int default_port, GCancellable *cancellable, GError **error); void g_socket_client_connect_async (GSocketClient *client, @@ -101,8 +101,8 @@ GSocketConnection * g_socket_client_connect_finish (GSocket GAsyncResult *result, GError **error); void g_socket_client_connect_to_host_async (GSocketClient *client, - const char *hostname, - int port, + const char *host_and_port, + int default_port, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data); diff --git a/gio/gsocketconnection.c b/gio/gsocketconnection.c index 878a282b4..e2d01cb51 100644 --- a/gio/gsocketconnection.c +++ b/gio/gsocketconnection.c @@ -41,7 +41,7 @@ /** * SECTION:gsocketconnection - * @short_description: High-level socket connection stream + * @short_description: A socket connection * @include: gio/gio.h * @see_also: #GIOStream, #GSocketClient, #GSocketListener * @@ -113,6 +113,18 @@ g_socket_connection_get_output_stream (GIOStream *io_stream) return connection->priv->output_stream; } +/** + * g_socket_connection_get_socket: + * @connection: a #GSocketConnection. + * + * Gets the underlying #GSocket object of the connection. + * This can be useful if you want to do something unusual on it + * not supported by the #GSocketConnection APIs. + * + * Returns: a #GSocketAddress or %NULL on error. + * + * Since: 2.22 + **/ GSocket * g_socket_connection_get_socket (GSocketConnection *connection) { @@ -357,11 +369,10 @@ G_LOCK_DEFINE_STATIC(connection_factories); * @protocol: a protocol id * * Looks up the #GType to be used when creating socket connections on - * sockets with the specified @family,@type and @protocol_id. + * sockets with the specified @family,@type and @protocol. * * If no type is registered, the #GSocketConnection base type is returned. * - * Returns: a #GType * Since: 2.22 **/ void diff --git a/gio/gsocketconnection.h b/gio/gsocketconnection.h index df37c9143..7d96af9ff 100644 --- a/gio/gsocketconnection.h +++ b/gio/gsocketconnection.h @@ -83,7 +83,7 @@ void g_socket_connection_factory_register_type (GType gint protocol); GType g_socket_connection_factory_lookup_type (GSocketFamily family, GSocketType type, - gint protocol); + gint protocol_id); GSocketConnection *g_socket_connection_factory_create_connection (GSocket *socket); G_END_DECLS diff --git a/gio/gsocketlistener.c b/gio/gsocketlistener.c index 228d9142f..ce1d79481 100644 --- a/gio/gsocketlistener.c +++ b/gio/gsocketlistener.c @@ -43,7 +43,7 @@ /** * SECTION: gsocketlistener * @title: GSocketListener - * @short_description: a high-level helper object for server sockets + * @short_description: Helper for accepting network client connections * @see_also: #GThreadedSocketService, #GSocketService. * * A #GSocketListener is an object that keeps track of a set @@ -166,7 +166,7 @@ g_socket_listener_init (GSocketListener *listener) } /** - * g_socket_service_new: + * g_socket_listener_new: * * Creates a new #GSocketListener with no sockets to listen for. * New listeners can be added with e.g. g_socket_listener_add_address() @@ -245,7 +245,7 @@ g_socket_listener_add_socket (GSocketListener *listener, } /** - * g_socket_listener_add_socket: + * g_socket_listener_add_address: * @listener: a #GSocketListener * @address: a #GSocketAddres * @type: a #GSocketType @@ -693,7 +693,7 @@ g_socket_listener_accept_socket_finish (GSocketListener *listener, } /** - * g_socket_listener_accept_socket_async: + * g_socket_listener_accept_async: * @listener: a #GSocketListener * @cancellable: a #GCancellable, or %NULL * @callback: a #GAsyncReadyCallback @@ -755,7 +755,7 @@ g_socket_listener_accept_finish (GSocketListener *listener, } /** - * g_socket_listener_accept_finish: + * g_socket_listener_set_backlog: * @listener: a #GSocketListener * @listen_backlog: an integer * diff --git a/gio/gsocketservice.c b/gio/gsocketservice.c index 9c56a696e..b9e8668dc 100644 --- a/gio/gsocketservice.c +++ b/gio/gsocketservice.c @@ -25,7 +25,7 @@ /** * SECTION: gsocketservice * @title: GSocketService - * @short_description: a high-level object representing a service + * @short_description: Make it easy to implement a network service * @see_also: #GThreadedSocketService, #GSocketListener. * * A #GSocketService is an object that represents a service that is @@ -310,7 +310,6 @@ g_socket_service_ready (GObject *object, /** * g_socket_service_new: - * @returns: a new #GSocketService. * * Creates a new #GSocketService with no sockets to listen for. * New listeners can be added with e.g. g_socket_listener_add_address() diff --git a/gio/gthemedicon.c b/gio/gthemedicon.c index ed78b8da7..8ce22e465 100644 --- a/gio/gthemedicon.c +++ b/gio/gthemedicon.c @@ -348,11 +348,11 @@ g_themed_icon_new_with_default_fallbacks (const char *iconname) /** * g_themed_icon_get_names: * @icon: a #GThemedIcon. - * + * * Gets the names of icons from within @icon. - * + * * Returns: a list of icon names. - **/ + */ const char * const * g_themed_icon_get_names (GThemedIcon *icon) { diff --git a/gio/gunixconnection.c b/gio/gunixconnection.c index b7416513f..1877f3772 100644 --- a/gio/gunixconnection.c +++ b/gio/gunixconnection.c @@ -19,7 +19,7 @@ /** * SECTION: gunixconnection * @title: GUnixConnection - * @short_description: a TCP #GSocketConnection + * @short_description: a Unix domain #GSocketConnection * @see_also: #GSocketConnection. * * This is the subclass of #GSocketConnection that is created diff --git a/gio/gunixsocketaddress.c b/gio/gunixsocketaddress.c index b6e304fb7..ebb93e79a 100644 --- a/gio/gunixsocketaddress.c +++ b/gio/gunixsocketaddress.c @@ -33,7 +33,7 @@ /** * SECTION:gunixsocketaddress - * @short_description: Unix socket addresses + * @short_description: Unix #GSocketAddress * * Support for UNIX-domain (aka local) sockets. **/