Set up gtk-doc for GDBus

Also move send_credentials() and receive_credentials() to
GUnixConnection. This code might change, discussion is still ongoing
in

 https://bugzilla.gnome.org/show_bug.cgi?id=617483.
This commit is contained in:
David Zeuthen 2010-05-06 15:31:45 -04:00
parent d0a14469d0
commit c490c14f4e
20 changed files with 712 additions and 211 deletions

View File

@ -107,6 +107,8 @@
<xi:include href="xml/gsocketcontrolmessage.xml"/> <xi:include href="xml/gsocketcontrolmessage.xml"/>
<xi:include href="xml/gunixfdlist.xml"/> <xi:include href="xml/gunixfdlist.xml"/>
<xi:include href="xml/gunixfdmessage.xml"/> <xi:include href="xml/gunixfdmessage.xml"/>
<xi:include href="xml/gcredentials.xml"/>
<xi:include href="xml/gunixcredentialsmessage.xml"/>
</chapter> </chapter>
<chapter id="resolver"> <chapter id="resolver">
<title>DNS resolution</title> <title>DNS resolution</title>
@ -124,6 +126,25 @@
<xi:include href="xml/gsocketservice.xml"/> <xi:include href="xml/gsocketservice.xml"/>
<xi:include href="xml/gthreadedsocketservice.xml"/> <xi:include href="xml/gthreadedsocketservice.xml"/>
</chapter> </chapter>
<chapter id="gdbus-lowlevel">
<title>Lowlevel D-Bus Support</title>
<xi:include href="xml/gdbusutils.xml"/>
<xi:include href="xml/gdbusaddress.xml"/>
<xi:include href="xml/gdbusintrospection.xml"/>
<xi:include href="xml/gdbuserror.xml"/>
<xi:include href="xml/gdbusmessage.xml"/>
<xi:include href="xml/gdbusconnection.xml"/>
<xi:include href="xml/gdbusmethodinvocation.xml"/>
<xi:include href="xml/gdbusproxy.xml"/>
<xi:include href="xml/gdbusserver.xml"/>
<xi:include href="xml/gdbusauthobserver.xml"/>
</chapter>
<chapter id="gdbus-convenience">
<title>Highlevel D-Bus Support</title>
<xi:include href="xml/gdbusnameowning.xml"/>
<xi:include href="xml/gdbusnamewatching.xml"/>
<xi:include href="xml/gdbusproxywatching.xml"/>
</chapter>
<chapter id="utils"> <chapter id="utils">
<title>Utilities</title> <title>Utilities</title>
<xi:include href="xml/gfilenamecompleter.xml"/> <xi:include href="xml/gfilenamecompleter.xml"/>

View File

@ -1807,6 +1807,8 @@ g_tcp_connection_get_graceful_disconnect
GUnixConnection GUnixConnection
g_unix_connection_receive_fd g_unix_connection_receive_fd
g_unix_connection_send_fd g_unix_connection_send_fd
g_unix_connection_receive_credentials
g_unix_connection_send_credentials
<SUBSECTION> <SUBSECTION>
g_socket_connection_factory_create_connection g_socket_connection_factory_create_connection
g_socket_connection_factory_lookup_type g_socket_connection_factory_lookup_type
@ -2167,3 +2169,391 @@ G_SETTINGS_SCHEMA_GET_CLASS
<SUBSECTION Private> <SUBSECTION Private>
g_settings_get_type g_settings_get_type
</SECTION> </SECTION>
<SECTION>
<FILE>gunixcredentialsmessage</FILE>
<TITLE>GUnixCredentialsMessage</TITLE>
GUnixCredentialsMessage
GUnixCredentialsMessageClass
g_unix_credentials_message_new
g_unix_credentials_message_new_with_credentials
g_unix_credentials_message_get_credentials
g_unix_credentials_message_is_supported
<SUBSECTION Standard>
G_IS_UNIX_CREDENTIALS_MESSAGE
G_IS_UNIX_CREDENTIALS_MESSAGE_CLASS
G_TYPE_UNIX_CREDENTIALS_MESSAGE
G_UNIX_CREDENTIALS_MESSAGE
G_UNIX_CREDENTIALS_MESSAGE_CLASS
G_UNIX_CREDENTIALS_MESSAGE_GET_CLASS
<SUBSECTION Private>
GUnixCredentialsMessagePrivate
g_unix_credentials_message_get_type
</SECTION>
<SECTION>
<FILE>gcredentials</FILE>
<TITLE>GCredentials</TITLE>
GCredentials
GCredentialsClass
GCredentialType
g_credentials_new
g_credentials_new_for_process
g_credentials_new_for_string
g_credentials_to_string
g_credentials_has_unix_user
g_credentials_get_unix_user
g_credentials_set_unix_user
g_credentials_has_unix_group
g_credentials_get_unix_group
g_credentials_set_unix_group
g_credentials_has_unix_process
g_credentials_get_unix_process
g_credentials_set_unix_process
g_credentials_has_windows_user
g_credentials_get_windows_user
g_credentials_set_windows_user
<SUBSECTION Standard>
G_CREDENTIALS
G_IS_CREDENTIALS
G_TYPE_CREDENTIALS
g_credentials_get_type
G_CREDENTIALS_CLASS
G_IS_CREDENTIALS_CLASS
G_CREDENTIALS_GET_CLASS
</SECTION>
<SECTION>
<FILE>gdbusaddress</FILE>
g_dbus_is_address
g_dbus_is_supported_address
g_dbus_address_get_stream
g_dbus_address_get_stream_finish
g_dbus_address_get_stream_sync
g_dbus_address_get_for_bus_sync
</SECTION>
<SECTION>
<FILE>gdbusutils</FILE>
g_dbus_is_activated
g_dbus_generate_guid
g_dbus_is_guid
g_dbus_is_name
g_dbus_is_unique_name
g_dbus_is_member_name
g_dbus_is_interface_name
</SECTION>
<SECTION>
<FILE>gdbusauthobserver</FILE>
<TITLE>GDBusAuthObserver</TITLE>
GDBusAuthObserver
GDBusAuthObserverClass
g_dbus_auth_observer_new
g_dbus_auth_observer_deny_authenticated_peer
<SUBSECTION Standard>
G_DBUS_AUTH_OBSERVER
G_IS_DBUS_AUTH_OBSERVER
G_TYPE_DBUS_AUTH_OBSERVER
g_dbus_server_get_gtype
G_DBUS_AUTH_OBSERVER_CLASS
G_IS_DBUS_AUTH_OBSERVER_CLASS
G_DBUS_AUTH_OBSERVER_GET_CLASS
</SECTION>
<SECTION>
<FILE>gdbusserver</FILE>
<TITLE>GDBusServer</TITLE>
GDBusServer
GDBusServerClass
GDBusServerFlags
g_dbus_server_new_sync
g_dbus_server_start
g_dbus_server_stop
g_dbus_server_is_active
g_dbus_server_get_guid
g_dbus_server_get_flags
g_dbus_server_get_client_address
<SUBSECTION Standard>
G_DBUS_SERVER
G_IS_DBUS_SERVER
G_TYPE_DBUS_SERVER
g_dbus_server_get_gtype
G_DBUS_SERVER_CLASS
G_IS_DBUS_SERVER_CLASS
G_DBUS_SERVER_GET_CLASS
</SECTION>
<SECTION>
<FILE>gdbusmessage</FILE>
<TITLE>GDBusMessage</TITLE>
GDBusMessageType
GDBusMessageFlags
GDBusMessageHeaderField
GDBusMessage
GDBusMessageClass
g_dbus_message_new
g_dbus_message_new_signal
g_dbus_message_new_method_call
g_dbus_message_new_method_reply
g_dbus_message_new_method_error
g_dbus_message_new_method_error_valist
g_dbus_message_new_method_error_literal
g_dbus_message_print
g_dbus_message_get_type
g_dbus_message_set_type
g_dbus_message_get_serial
g_dbus_message_set_serial
g_dbus_message_get_flags
g_dbus_message_set_flags
g_dbus_message_get_body
g_dbus_message_set_body
g_dbus_message_get_unix_fd_list
g_dbus_message_set_unix_fd_list
g_dbus_message_get_header_fields
g_dbus_message_get_header
g_dbus_message_set_header
g_dbus_message_get_destination
g_dbus_message_set_destination
g_dbus_message_get_error_name
g_dbus_message_set_error_name
g_dbus_message_get_interface
g_dbus_message_set_interface
g_dbus_message_get_member
g_dbus_message_set_member
g_dbus_message_get_path
g_dbus_message_set_path
g_dbus_message_get_reply_serial
g_dbus_message_set_reply_serial
g_dbus_message_get_sender
g_dbus_message_set_sender
g_dbus_message_get_signature
g_dbus_message_set_signature
g_dbus_message_get_arg0
g_dbus_message_to_blob
g_dbus_message_bytes_needed
g_dbus_message_new_from_blob
g_dbus_message_to_gerror
<SUBSECTION Standard>
G_DBUS_MESSAGE
G_IS_DBUS_MESSAGE
G_TYPE_DBUS_MESSAGE
g_dbus_message_get_gtype
G_DBUS_MESSAGE_CLASS
G_IS_DBUS_MESSAGE_CLASS
G_DBUS_MESSAGE_GET_CLASS
</SECTION>
<SECTION>
<FILE>gdbusconnection</FILE>
<TITLE>GDBusConnection</TITLE>
GBusType
g_bus_get
g_bus_get_finish
g_bus_get_sync
GDBusConnection
GDBusConnectionClass
GDBusConnectionFlags
g_dbus_connection_new
g_dbus_connection_new_finish
g_dbus_connection_new_sync
g_dbus_connection_new_for_address
g_dbus_connection_new_for_address_finish
g_dbus_connection_new_for_address_sync
GDBusCapabilityFlags
g_dbus_connection_close
g_dbus_connection_is_closed
g_dbus_connection_get_exit_on_close
g_dbus_connection_set_exit_on_close
g_dbus_connection_get_stream
g_dbus_connection_get_guid
g_dbus_connection_get_unique_name
g_dbus_connection_get_capabilities
g_dbus_connection_get_peer_credentials
GDBusInvokeMethodFlags
g_dbus_connection_invoke_method
g_dbus_connection_invoke_method_finish
g_dbus_connection_invoke_method_sync
g_dbus_connection_emit_signal
GDBusSignalCallback
g_dbus_connection_signal_subscribe
g_dbus_connection_signal_unsubscribe
g_dbus_connection_send_message
g_dbus_connection_send_message_with_reply
g_dbus_connection_send_message_with_reply_finish
g_dbus_connection_send_message_with_reply_sync
GDBusMessageFilterFunction
g_dbus_connection_add_filter
g_dbus_connection_remove_filter
GDBusInterfaceVTable
GDBusInterfaceMethodCallFunc
GDBusInterfaceGetPropertyFunc
GDBusInterfaceSetPropertyFunc
g_dbus_connection_register_object
g_dbus_connection_unregister_object
GDBusSubtreeVTable
GDBusSubtreeEnumerateFunc
GDBusSubtreeIntrospectFunc
GDBusSubtreeDispatchFunc
GDBusSubtreeFlags
g_dbus_connection_register_subtree
g_dbus_connection_unregister_subtree
<SUBSECTION Standard>
G_DBUS_CONNECTION
G_IS_DBUS_CONNECTION
G_TYPE_DBUS_CONNECTION
g_dbus_connection_get_type
G_DBUS_CONNECTION_CLASS
G_IS_DBUS_CONNECTION_CLASS
G_DBUS_CONNECTION_GET_CLASS
</SECTION>
<SECTION>
<FILE>gdbusmethodinvocation</FILE>
<TITLE>GDBusMethodInvocation</TITLE>
GDBusMethodInvocation
GDBusMethodInvocationClass
g_dbus_method_invocation_new
g_dbus_method_invocation_get_sender
g_dbus_method_invocation_get_object_path
g_dbus_method_invocation_get_interface_name
g_dbus_method_invocation_get_method_name
g_dbus_method_invocation_get_method_info
g_dbus_method_invocation_get_connection
g_dbus_method_invocation_get_message
g_dbus_method_invocation_get_parameters
g_dbus_method_invocation_get_user_data
g_dbus_method_invocation_return_value
g_dbus_method_invocation_return_error
g_dbus_method_invocation_return_error_valist
g_dbus_method_invocation_return_error_literal
g_dbus_method_invocation_return_gerror
g_dbus_method_invocation_return_dbus_error
<SUBSECTION Standard>
G_DBUS_METHOD_INVOCATION
G_IS_DBUS_METHOD_INVOCATION
G_TYPE_DBUS_METHOD_INVOCATION
g_dbus_method_invocation_get_type
G_DBUS_METHOD_INVOCATION_CLASS
G_IS_DBUS_METHOD_INVOCATION_CLASS
G_DBUS_METHOD_INVOCATION_GET_CLASS
</SECTION>
<SECTION>
<FILE>gdbusnameowning</FILE>
GBusAcquiredCallback
GBusNameAcquiredCallback
GBusNameLostCallback
GBusNameOwnerFlags
g_bus_own_name
g_bus_own_name_on_connection
g_bus_unown_name
</SECTION>
<SECTION>
<FILE>gdbusnamewatching</FILE>
GBusNameAppearedCallback
GBusNameVanishedCallback
GBusNameWatcherFlags
g_bus_watch_name
g_bus_unwatch_name
</SECTION>
<SECTION>
<FILE>gdbusproxywatching</FILE>
GBusProxyAppearedCallback
GBusProxyVanishedCallback
g_bus_watch_proxy
g_bus_unwatch_proxy
</SECTION>
<SECTION>
<FILE>gdbuserror</FILE>
GDBusError
G_DBUS_ERROR
g_dbus_error_is_remote_error
g_dbus_error_get_remote_error
g_dbus_error_strip_remote_error
GDBusErrorEntry
g_dbus_error_register_error_domain
g_dbus_error_register_error
g_dbus_error_unregister_error
g_dbus_error_new_for_dbus_error
g_dbus_error_set_dbus_error
g_dbus_error_set_dbus_error_valist
g_dbus_error_encode_gerror
</SECTION>
<SECTION>
<FILE>gdbusproxy</FILE>
<TITLE>GDBusProxy</TITLE>
GDBusProxyFlags
GDBusProxy
GDBusProxyClass
g_dbus_proxy_new
g_dbus_proxy_new_finish
g_dbus_proxy_new_sync
g_dbus_proxy_get_flags
g_dbus_proxy_get_connection
g_dbus_proxy_get_unique_bus_name
g_dbus_proxy_get_object_path
g_dbus_proxy_get_interface_name
g_dbus_proxy_get_default_timeout
g_dbus_proxy_set_default_timeout
g_dbus_proxy_get_cached_property_names
g_dbus_proxy_get_cached_property
g_dbus_proxy_set_interface_info
g_dbus_proxy_get_interface_info
g_dbus_proxy_invoke_method
g_dbus_proxy_invoke_method_finish
g_dbus_proxy_invoke_method_sync
<SUBSECTION Standard>
G_DBUS_PROXY
G_IS_DBUS_PROXY
G_TYPE_DBUS_PROXY
g_dbus_proxy_get_type
G_DBUS_PROXY_CLASS
G_IS_DBUS_PROXY_CLASS
G_DBUS_PROXY_GET_CLASS
</SECTION>
<SECTION>
<FILE>gdbusintrospection</FILE>
GDBusAnnotationInfo
GDBusArgInfo
GDBusMethodInfo
GDBusSignalInfo
GDBusPropertyInfoFlags
GDBusPropertyInfo
GDBusInterfaceInfo
GDBusNodeInfo
g_dbus_annotation_info_lookup
g_dbus_interface_info_lookup_method
g_dbus_interface_info_lookup_signal
g_dbus_interface_info_lookup_property
g_dbus_interface_info_generate_xml
g_dbus_node_info_new_for_xml
g_dbus_node_info_lookup_interface
g_dbus_node_info_generate_xml
G_TYPE_DBUS_NODE_INFO
G_TYPE_DBUS_INTERFACE_INFO
G_TYPE_DBUS_METHOD_INFO
G_TYPE_DBUS_SIGNAL_INFO
G_TYPE_DBUS_PROPERTY_INFO
G_TYPE_DBUS_ARG_INFO
G_TYPE_DBUS_ANNOTATION_INFO
g_dbus_node_info_ref
g_dbus_interface_info_ref
g_dbus_method_info_ref
g_dbus_signal_info_ref
g_dbus_property_info_ref
g_dbus_arg_info_ref
g_dbus_annotation_info_ref
g_dbus_node_info_unref
g_dbus_interface_info_unref
g_dbus_method_info_unref
g_dbus_signal_info_unref
g_dbus_property_info_unref
g_dbus_arg_info_unref
g_dbus_annotation_info_unref
</SECTION>

View File

@ -107,3 +107,14 @@ g_volume_monitor_get_type
g_zlib_compressor_get_type g_zlib_compressor_get_type
g_zlib_compressor_format_get_type g_zlib_compressor_format_get_type
g_zlib_decompressor_get_type g_zlib_decompressor_get_type
g_dbus_message_get_gtype
g_dbus_connection_get_type
g_bus_type_get_type
g_bus_name_owner_flags_get_type
g_dbus_error_get_type
g_dbus_proxy_get_type
g_dbus_method_invocation_get_type
g_dbus_server_get_type
g_dbus_auth_observer_get_type
g_credentials_get_type
g_unix_credentials_message_get_type

View File

@ -36,8 +36,8 @@
/** /**
* SECTION:gcredentials * SECTION:gcredentials
* @short_description: Credentials * @short_description: An object containing credentials
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* The #GCredentials type is used for storing information that can be * The #GCredentials type is used for storing information that can be
* used for identifying, authenticating and authorizing processes. * used for identifying, authenticating and authorizing processes.

View File

@ -40,7 +40,7 @@
* SECTION:gdbusaddress * SECTION:gdbusaddress
* @title: D-Bus Addresses * @title: D-Bus Addresses
* @short_description: D-Bus connection endpoints * @short_description: D-Bus connection endpoints
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* Routines for working with D-Bus addresses. * Routines for working with D-Bus addresses.
*/ */

View File

@ -78,195 +78,6 @@ debug_print (const gchar *message, ...)
#endif #endif
} }
/* ---------------------------------------------------------------------------------------------------- */
/* TODO: move to gio */
/**
* g_unix_connection_send_credentials:
* @connection: A #GUnixConnection.
* @credentials: A #GCredentials to send.
* @cancellable: A #GCancellable or %NULL.
* @error: Return location for error or %NULL.
*
* Passes the credentials stored in @credentials to the recieving side
* of the connection. The recieving end has to call
* g_unix_connection_receive_credentials() (or similar) to accept the
* credentials.
*
* The credentials which the sender specifies are checked by the
* kernel. A process with effective user ID 0 is allowed to specify
* values that do not match its own. This means that the credentials
* can be used to authenticate other connections.
*
* As well as sending the credentials this also writes a single NUL
* byte to the stream, as this is required for credentials passing to
* work on some implementations.
*
* Returns: %TRUE on success, %FALSE if @error is set.
*
* Since: 2.26
*/
static gboolean
g_unix_connection_send_credentials (GUnixConnection *connection,
GCredentials *credentials,
GCancellable *cancellable,
GError **error)
{
GSocketControlMessage *scm;
GSocket *socket;
gboolean ret;
GOutputVector vector;
guchar nul_byte[1] = {'\0'};
g_return_val_if_fail (G_IS_UNIX_CONNECTION (connection), FALSE);
g_return_val_if_fail (G_IS_CREDENTIALS (credentials), FALSE);
g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
ret = FALSE;
vector.buffer = &nul_byte;
vector.size = 1;
scm = g_unix_credentials_message_new_with_credentials (credentials);
g_object_get (connection, "socket", &socket, NULL);
if (g_socket_send_message (socket,
NULL, /* address */
&vector,
1,
&scm,
1,
G_SOCKET_MSG_NONE,
cancellable,
error) != 1)
{
g_prefix_error (error, _("Error sending credentials: "));
goto out;
}
ret = TRUE;
out:
g_object_unref (socket);
g_object_unref (scm);
return ret;
}
/**
* g_unix_connection_receive_credentials:
* @connection: A #GUnixConnection.
* @cancellable: A #GCancellable or %NULL.
* @error: Return location for error or %NULL.
*
* Receives credentials from the sending end of the connection. The
* sending end has to call g_unix_connection_send_credentials() (or
* similar) for this to work.
*
* As well as reading the credentials this also reads (and discards) a
* single byte from the stream, as this is required for credentials
* passing to work on some implementations.
*
* Returns: Received credentials on success (free with
* g_object_unref()), %NULL if @error is set.
*
* Since: 2.26
*/
static GCredentials *
g_unix_connection_receive_credentials (GUnixConnection *connection,
GCancellable *cancellable,
GError **error)
{
GCredentials *ret;
GSocketControlMessage **scms;
gint nscm;
GSocket *socket;
gint n;
volatile GType credentials_message_gtype;
gssize num_bytes_read;
g_return_val_if_fail (G_IS_UNIX_CONNECTION (connection), NULL);
g_return_val_if_fail (error == NULL || *error == NULL, NULL);
ret = NULL;
scms = NULL;
g_object_get (connection, "socket", &socket, NULL);
#if 1
/* TODO: Move this to gsocket.c... */
{
int opt_val = 1;
if (setsockopt (g_socket_get_fd (socket),
SOL_SOCKET,
SO_PASSCRED,
&opt_val,
sizeof opt_val) != 0)
{
g_warning ("boo, error setting SO_PASSCRED: %m");
}
}
#endif
/* ensure the type of GUnixCredentialsMessage has been registered with the type system */
credentials_message_gtype = G_TYPE_UNIX_CREDENTIALS_MESSAGE;
num_bytes_read = g_socket_receive_message (socket,
NULL, /* GSocketAddress **address */
NULL,
0,
&scms,
&nscm,
NULL,
cancellable,
error);
if (num_bytes_read != 1)
{
/* Handle situation where g_socket_receive_message() returns
* 0 bytes and not setting @error
*/
if (num_bytes_read == 0 && error != NULL && *error == NULL)
{
g_set_error_literal (error,
G_IO_ERROR,
G_IO_ERROR_FAILED,
_("Expecting to read a single byte for receiving credentials but read zero bytes"));
}
goto out;
}
if (nscm != 1)
{
g_set_error (error,
G_IO_ERROR,
G_IO_ERROR_FAILED,
_("Expecting 1 control message, got %d"),
nscm);
goto out;
}
if (!G_IS_UNIX_CREDENTIALS_MESSAGE (scms[0]))
{
g_set_error_literal (error,
G_IO_ERROR,
G_IO_ERROR_FAILED,
_("Unexpected type of ancillary data"));
goto out;
}
ret = g_unix_credentials_message_get_credentials (G_UNIX_CREDENTIALS_MESSAGE (scms[0]));
g_object_ref (ret);
out:
if (scms != NULL)
{
for (n = 0; n < nscm; n++)
g_object_unref (scms[n]);
g_free (scms);
}
g_object_unref (socket);
return ret;
}
/* ---------------------------------------------------------------------------------------------------- */
typedef struct typedef struct
{ {
const gchar *name; const gchar *name;

View File

@ -33,7 +33,7 @@
/** /**
* SECTION:gdbusauthobserver * SECTION:gdbusauthobserver
* @short_description: Object used for authenticating connections * @short_description: Object used for authenticating connections
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* The #GDBusAuthObserver type provides a mechanism for participating * The #GDBusAuthObserver type provides a mechanism for participating
* in how a #GDBusServer (or a #GDBusConnection) authenticates remote * in how a #GDBusServer (or a #GDBusConnection) authenticates remote

View File

@ -78,7 +78,7 @@
/** /**
* SECTION:gdbusconnection * SECTION:gdbusconnection
* @short_description: D-Bus Connections * @short_description: D-Bus Connections
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* <para><note> * <para><note>
* This class is rarely used directly in D-Bus clients. If you are * This class is rarely used directly in D-Bus clients. If you are
@ -89,11 +89,11 @@
* The #GDBusConnection type is used for D-Bus connections to remote * The #GDBusConnection type is used for D-Bus connections to remote
* peers such as a message buses. * peers such as a message buses.
* *
* <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
* *
* <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
* *
* <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/ */
/* ---------------------------------------------------------------------------------------------------- */ /* ---------------------------------------------------------------------------------------------------- */

View File

@ -36,7 +36,7 @@
* SECTION:gdbuserror * SECTION:gdbuserror
* @title: GDBusError * @title: GDBusError
* @short_description: Mapping D-Bus errors to and from #GError * @short_description: Mapping D-Bus errors to and from #GError
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* All facilities that return errors from remote methods (such as * All facilities that return errors from remote methods (such as
* g_dbus_connection_invoke_method_sync()) use #GError to represent * g_dbus_connection_invoke_method_sync()) use #GError to represent

View File

@ -32,7 +32,7 @@
* SECTION:gdbusintrospection * SECTION:gdbusintrospection
* @title: Introspection XML * @title: Introspection XML
* @short_description: Parse and Generate Introspection XML * @short_description: Parse and Generate Introspection XML
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* Various data structures and convenience routines to parse and * Various data structures and convenience routines to parse and
* generate D-Bus introspection XML. * generate D-Bus introspection XML.

View File

@ -48,7 +48,7 @@
/** /**
* SECTION:gdbusmessage * SECTION:gdbusmessage
* @short_description: D-Bus Message * @short_description: D-Bus Message
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* A type for representing D-Bus messages that can be sent or received * A type for representing D-Bus messages that can be sent or received
* on a #GDBusConnection. * on a #GDBusConnection.

View File

@ -36,7 +36,7 @@
/** /**
* SECTION:gdbusmethodinvocation * SECTION:gdbusmethodinvocation
* @short_description: Object for handling remote calls * @short_description: Object for handling remote calls
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* Instances of the #GDBusMethodInvocation class are used when * Instances of the #GDBusMethodInvocation class are used when
* handling D-Bus method calls. It provides a way to asynchronously * handling D-Bus method calls. It provides a way to asynchronously

View File

@ -36,11 +36,11 @@
* SECTION:gdbusnameowning * SECTION:gdbusnameowning
* @title: Owning Bus Names * @title: Owning Bus Names
* @short_description: Simple API for owning bus names * @short_description: Simple API for owning bus names
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* Convenience API for owning bus names. * Convenience API for owning bus names.
* *
* <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> * <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/ */
G_LOCK_DEFINE_STATIC (lock); G_LOCK_DEFINE_STATIC (lock);

View File

@ -36,11 +36,11 @@
* SECTION:gdbusnamewatching * SECTION:gdbusnamewatching
* @title: Watching Bus Names * @title: Watching Bus Names
* @short_description: Simple API for watching bus names * @short_description: Simple API for watching bus names
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* Convenience API for watching bus names. * Convenience API for watching bus names.
* *
* <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> * <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/ */
G_LOCK_DEFINE_STATIC (lock); G_LOCK_DEFINE_STATIC (lock);

View File

@ -42,7 +42,7 @@
/** /**
* SECTION:gdbusproxy * SECTION:gdbusproxy
* @short_description: Base class for proxies * @short_description: Base class for proxies
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* #GDBusProxy is a base class used for proxies to access a D-Bus * #GDBusProxy is a base class used for proxies to access a D-Bus
* interface on a remote object. A #GDBusProxy can only be constructed * interface on a remote object. A #GDBusProxy can only be constructed

View File

@ -39,11 +39,11 @@
* SECTION:gdbusproxywatching * SECTION:gdbusproxywatching
* @title: Watching Proxies * @title: Watching Proxies
* @short_description: Simple API for watching proxies * @short_description: Simple API for watching proxies
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* Convenience API for watching bus proxies. * Convenience API for watching bus proxies.
* *
* <example id="gdbus-watching-proxy"><title>Simple application watching a proxy</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> * <example id="gdbus-watching-proxy"><title>Simple application watching a proxy</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/ */
/* ---------------------------------------------------------------------------------------------------- */ /* ---------------------------------------------------------------------------------------------------- */

View File

@ -44,12 +44,12 @@
/** /**
* SECTION:gdbusserver * SECTION:gdbusserver
* @short_description: Helper for accepting connections * @short_description: Helper for accepting connections
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* #GDBusServer is a helper for listening to and accepting D-Bus * #GDBusServer is a helper for listening to and accepting D-Bus
* connections. * connections.
* *
* <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*/ */
struct _GDBusServerPrivate struct _GDBusServerPrivate

View File

@ -33,7 +33,7 @@
* SECTION:gdbusutils * SECTION:gdbusutils
* @title: D-Bus Utilities * @title: D-Bus Utilities
* @short_description: Various utilities related to D-Bus. * @short_description: Various utilities related to D-Bus.
* @include: gdbus/gdbus.h * @include: gio/gio.h
* *
* Various utility routines related to D-Bus. * Various utility routines related to D-Bus.
*/ */

View File

@ -36,6 +36,14 @@
#include <gio/gsocket.h> #include <gio/gsocket.h>
#include <unistd.h> #include <unistd.h>
#ifdef __linux__
/* for getsockopt() and setsockopt() */
#include <sys/types.h> /* See NOTES */
#include <sys/socket.h>
#include <errno.h>
#include <string.h>
#endif
#include "gioalias.h" #include "gioalias.h"
G_DEFINE_TYPE_WITH_CODE (GUnixConnection, g_unix_connection, G_DEFINE_TYPE_WITH_CODE (GUnixConnection, g_unix_connection,
@ -287,5 +295,255 @@ gboolean g_unix_connection_create_pair (GUnixCo
GError **error); GError **error);
*/ */
/**
* g_unix_connection_send_credentials:
* @connection: A #GUnixConnection.
* @credentials: A #GCredentials to send.
* @cancellable: A #GCancellable or %NULL.
* @error: Return location for error or %NULL.
*
* Passes the credentials stored in @credentials to the recieving side
* of the connection. The recieving end has to call
* g_unix_connection_receive_credentials() (or similar) to accept the
* credentials.
*
* The credentials which the sender specifies are checked by the
* kernel. A process with effective user ID 0 is allowed to specify
* values that do not match its own. This means that the credentials
* can be used to authenticate other connections.
*
* As well as sending the credentials this also writes a single NUL
* byte to the stream, as this is required for credentials passing to
* work on some implementations.
*
* Returns: %TRUE on success, %FALSE if @error is set.
*
* Since: 2.26
*/
gboolean
g_unix_connection_send_credentials (GUnixConnection *connection,
GCredentials *credentials,
GCancellable *cancellable,
GError **error)
{
GSocketControlMessage *scm;
GSocket *socket;
gboolean ret;
GOutputVector vector;
guchar nul_byte[1] = {'\0'};
g_return_val_if_fail (G_IS_UNIX_CONNECTION (connection), FALSE);
g_return_val_if_fail (G_IS_CREDENTIALS (credentials), FALSE);
g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
ret = FALSE;
vector.buffer = &nul_byte;
vector.size = 1;
scm = g_unix_credentials_message_new_with_credentials (credentials);
g_object_get (connection, "socket", &socket, NULL);
if (g_socket_send_message (socket,
NULL, /* address */
&vector,
1,
&scm,
1,
G_SOCKET_MSG_NONE,
cancellable,
error) != 1)
{
g_prefix_error (error, _("Error sending credentials: "));
goto out;
}
ret = TRUE;
out:
g_object_unref (socket);
g_object_unref (scm);
return ret;
}
/**
* g_unix_connection_receive_credentials:
* @connection: A #GUnixConnection.
* @cancellable: A #GCancellable or %NULL.
* @error: Return location for error or %NULL.
*
* Receives credentials from the sending end of the connection. The
* sending end has to call g_unix_connection_send_credentials() (or
* similar) for this to work.
*
* As well as reading the credentials this also reads (and discards) a
* single byte from the stream, as this is required for credentials
* passing to work on some implementations.
*
* Returns: Received credentials on success (free with
* g_object_unref()), %NULL if @error is set.
*
* Since: 2.26
*/
GCredentials *
g_unix_connection_receive_credentials (GUnixConnection *connection,
GCancellable *cancellable,
GError **error)
{
GCredentials *ret;
GSocketControlMessage **scms;
gint nscm;
GSocket *socket;
gint n;
volatile GType credentials_message_gtype;
gssize num_bytes_read;
#ifdef __linux__
gboolean turn_off_so_passcreds;
#endif
g_return_val_if_fail (G_IS_UNIX_CONNECTION (connection), NULL);
g_return_val_if_fail (error == NULL || *error == NULL, NULL);
ret = NULL;
scms = NULL;
g_object_get (connection, "socket", &socket, NULL);
/* On Linux, we need to turn on SO_PASSCRED if it isn't enabled
* already. We also need to turn it off when we're done. See
* #617483 for more discussion.
*/
#ifdef __linux__
{
gint opt_val;
socklen_t opt_len;
turn_off_so_passcreds = FALSE;
opt_val = 0;
opt_len = sizeof (gint);
if (getsockopt (g_socket_get_fd (socket),
SOL_SOCKET,
SO_PASSCRED,
&opt_val,
&opt_len) != 0)
{
g_set_error (error,
G_IO_ERROR,
g_io_error_from_errno (errno),
_("Error checking if SO_PASSCRED is enabled for socket: %s"),
strerror (errno));
goto out;
}
if (opt_len != sizeof (gint))
{
g_set_error (error,
G_IO_ERROR,
G_IO_ERROR_FAILED,
_("Unexpected option length while checking if SO_PASSCRED is enabled for socket. "
"Expected %d bytes, got %d"),
(gint) sizeof (gint), (gint) opt_len);
goto out;
}
if (opt_val == 0)
{
opt_val = 1;
if (setsockopt (g_socket_get_fd (socket),
SOL_SOCKET,
SO_PASSCRED,
&opt_val,
sizeof opt_val) != 0)
{
g_set_error (error,
G_IO_ERROR,
g_io_error_from_errno (errno),
_("Error enabling SO_PASSCRED: %s"),
strerror (errno));
goto out;
}
turn_off_so_passcreds = TRUE;
}
}
#endif
/* ensure the type of GUnixCredentialsMessage has been registered with the type system */
credentials_message_gtype = G_TYPE_UNIX_CREDENTIALS_MESSAGE;
num_bytes_read = g_socket_receive_message (socket,
NULL, /* GSocketAddress **address */
NULL,
0,
&scms,
&nscm,
NULL,
cancellable,
error);
if (num_bytes_read != 1)
{
/* Handle situation where g_socket_receive_message() returns
* 0 bytes and not setting @error
*/
if (num_bytes_read == 0 && error != NULL && *error == NULL)
{
g_set_error_literal (error,
G_IO_ERROR,
G_IO_ERROR_FAILED,
_("Expecting to read a single byte for receiving credentials but read zero bytes"));
}
goto out;
}
if (nscm != 1)
{
g_set_error (error,
G_IO_ERROR,
G_IO_ERROR_FAILED,
_("Expecting 1 control message, got %d"),
nscm);
goto out;
}
if (!G_IS_UNIX_CREDENTIALS_MESSAGE (scms[0]))
{
g_set_error_literal (error,
G_IO_ERROR,
G_IO_ERROR_FAILED,
_("Unexpected type of ancillary data"));
goto out;
}
ret = g_unix_credentials_message_get_credentials (G_UNIX_CREDENTIALS_MESSAGE (scms[0]));
g_object_ref (ret);
out:
#ifdef __linux__
if (turn_off_so_passcreds)
{
gint opt_val;
opt_val = 0;
if (setsockopt (g_socket_get_fd (socket),
SOL_SOCKET,
SO_PASSCRED,
&opt_val,
sizeof opt_val) != 0)
{
g_set_error (error,
G_IO_ERROR,
g_io_error_from_errno (errno),
_("Error while disabling SO_PASSCRED: %s"),
strerror (errno));
goto out;
}
}
#endif
if (scms != NULL)
{
for (n = 0; n < nscm; n++)
g_object_unref (scms[n]);
g_free (scms);
}
g_object_unref (socket);
return ret;
}
#define __G_UNIX_CONNECTION_C__ #define __G_UNIX_CONNECTION_C__
#include "gioaliasdef.c" #include "gioaliasdef.c"

View File

@ -71,6 +71,16 @@ gint g_unix_connection_receive_fd (GUnixCo
GCancellable *cancellable, GCancellable *cancellable,
GError **error); GError **error);
gboolean g_unix_connection_send_credentials (GUnixConnection *connection,
GCredentials *credentials,
GCancellable *cancellable,
GError **error);
GCredentials *g_unix_connection_receive_credentials (GUnixConnection *connection,
GCancellable *cancellable,
GError **error);
G_END_DECLS G_END_DECLS
#endif /* __G_UNIX_CONNECTION_H__ */ #endif /* __G_UNIX_CONNECTION_H__ */