luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-08-25 02:18:55 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update the docs for the new network APIs

Browse Source 
This imports the network APIs into the gio reference docs, and cleans
up a bunch of gtk-doc warnings and documentation issues.
This commit is contained in:
Alexander Larsson
2009-05-18 13:02:11 +02:00
parent e1afc6e79b
commit 6ea86cc57f
30 changed files with 576 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
gio/gasyncinitable.c
View File

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

2
gio/gfile.c
View File

@@ -1779,7 +1779,7 @@ g_file_create_readwrite (GFile *file,
}
/**
* g_file_replace:
* g_file_replace_readwrite:
* @file: input #GFile.
* @etag: an optional <link linkend="gfile-etag">entity tag</link> for the
* current #GFile, or #NULL to ignore.

9
gio/gfile.h
View File

@@ -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.
**/

2
gio/gfileenumerator.c
View File

@@ -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)

10
gio/gfileiostream.c
View File

@@ -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
**/

2
gio/ginetsocketaddress.c
View File

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

9
gio/ginitable.c
View File

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

5
gio/gioenums.h
View File

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

9
gio/giostream.c
View File

@@ -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().
*

2
gio/giotypes.h
View File

@@ -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,

2
gio/gmount.c
View File

@@ -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,

1
gio/gmount.h
View File

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

4
gio/gsocket.c
View File

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

5
gio/gsocket.h
View File

@@ -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,

25
gio/gsocketclient.c
View File

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

8
gio/gsocketclient.h
View File

@@ -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);

17
gio/gsocketconnection.c
View File

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

2
gio/gsocketconnection.h
View File

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

10
gio/gsocketlistener.c
View File

@@ -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
*

3
gio/gsocketservice.c
View File

@@ -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()

6
gio/gthemedicon.c
View File

@@ -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)
{

2
gio/gunixconnection.c
View File

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

2
gio/gunixsocketaddress.c
View File

@@ -33,7 +33,7 @@
/**
* SECTION:gunixsocketaddress
* @short_description: Unix socket addresses
* @short_description: Unix #GSocketAddress
*
* Support for UNIX-domain (aka local) sockets.
**/