Gio::DBusConnection Class Reference

DBusConnection - D-Bus Connections. More...

#include <giomm/dbusconnection.h>

Inheritance diagram for Gio::DBusConnection:
Inheritance graph
[legend]

List of all members.

Public Member Functions

virtual ~DBusConnection ()
GDBusConnection* gobj ()
 Provides access to the underlying C GObject.
const GDBusConnection* gobj () const
 Provides access to the underlying C GObject.
GDBusConnection* gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void get (BusType bus_type, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >())
 TODO.
void create (const Glib::RefPtr< IOStream >& stream, const Glib::ustring& guid, DBusConnectionFlags flags, const Glib::RefPtr< DBusAuthObserver >& observer, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >())
 Asynchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.
void create_for_address (const Glib::ustring& address, DBusConnectionFlags flags, const Glib::RefPtr< DBusAuthObserver >& observer, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >())
 Asynchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by address which must be in the D-Bus address format.
Glib::RefPtr< DBusConnectioncreate (const Glib::RefPtr< IOStream >& stream, const Glib::ustring& guid, DBusConnectionFlags flags, const Glib::RefPtr< DBusAuthObserver >& observer, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >())
 Synchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.
Glib::RefPtr< DBusConnectioncreate_for_address (const Glib::ustring& address, DBusConnectionFlags flags, const Glib::RefPtr< DBusAuthObserver >& observer, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >())
 Synchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by address which must be in the D-Bus address format.
void close ()
void close (const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable)
void close (const SlotAsyncReady& slot)
bool close_finish (const Glib::RefPtr< AsyncResult >& result)
 Finishes an operation started with g_dbus_connection_close().
void close_sync ()
void close_sync (const Glib::RefPtr< Cancellable >& cancellable)
 Synchronously closees connection.
void flush ()
void flush (const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable)
void flush (const SlotAsyncReady& slot)
bool flush_finish (const Glib::RefPtr< AsyncResult >& result)
 Finishes an operation started with g_dbus_connection_flush().
void flush_sync ()
void flush_sync (const Glib::RefPtr< Cancellable >& cancellable)
 Synchronously flushes connection.
bool send_message (const Glib::RefPtr< DBusMessage >& message, DBusSendMessageFlags flags, guint32* out_serial)
 Asynchronously sends message to the peer represented by connection.
void send_message_with_reply (const Glib::RefPtr< DBusMessage >& message, int timeout_msec, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable=Glib::RefPtr< Cancellable >())
Glib::RefPtr< DBusMessagesend_message_with_reply_finish (const Glib::RefPtr< AsyncResult >& result)
void start_message_processing ()
 If connection was created with DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method starts processing messages.
bool is_closed () const
 Gets whether connection is closed.
Glib::RefPtr< IOStreamget_stream ()
 Gets the underlying stream used for IO.
Glib::RefPtr< const IOStreamget_stream () const
 Gets the underlying stream used for IO.
Glib::ustring get_guid () const
 The GUID of the peer performing the role of server when authenticating.
Glib::ustring get_unique_name () const
 Gets the unique name of connection as assigned by the message bus.
Glib::RefPtr< Credentialsget_peer_credentials ()
 Gets the credentials of the authenticated peer.
Glib::RefPtr< const Credentialsget_peer_credentials () const
 Gets the credentials of the authenticated peer.
bool get_exit_on_close () const
 Gets whether the process is terminated when connection is closed by the remote peer.
void set_exit_on_close (bool exit_on_close=true)
 Sets whether the process should be terminated when connection is closed by the remote peer.
DBusCapabilityFlags get_capabilities () const
 Gets the capabilities negotiated with the remote peer.

Static Public Member Functions

static Glib::RefPtr
< DBusConnection
get_finish (const Glib::RefPtr< AsyncResult >& res)
static Glib::RefPtr
< DBusConnection
create_finish (const Glib::RefPtr< AsyncResult >& res)
static Glib::RefPtr
< DBusConnection
create_for_address_finish (const Glib::RefPtr< AsyncResult >& res)

Protected Member Functions

 DBusConnection (const Glib::RefPtr< IOStream >& stream, const Glib::ustring& guid, DBusConnectionFlags flags, const Glib::RefPtr< DBusAuthObserver >& observer, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable)
 DBusConnection (const Glib::RefPtr< IOStream >& stream, const Glib::ustring& guid, DBusConnectionFlags flags, const Glib::RefPtr< DBusAuthObserver >& observer, const Glib::RefPtr< Cancellable >& cancellable)
 DBusConnection (const Glib::ustring& address, DBusConnectionFlags flags, const Glib::RefPtr< DBusAuthObserver >& observer, const SlotAsyncReady& slot, const Glib::RefPtr< Cancellable >& cancellable)
 DBusConnection (const Glib::ustring& address, DBusConnectionFlags flags, const Glib::RefPtr< DBusAuthObserver >& observer, const Glib::RefPtr< Cancellable >& cancellable)

Related Functions

(Note that these are not member functions.)



Glib::RefPtr< Gio::DBusConnectionwrap (GDBusConnection* object, bool take_copy=false)
 A Glib::wrap() method for this object.

Detailed Description

DBusConnection - D-Bus Connections.

The DBusConnection type is used for D-Bus connections to remote peers such as a message buses. It is a low-level API that offers a lot of flexibility. For instance, it lets you establish a connection over any transport that can by represented as an IOStream.

This class is rarely used directly in D-Bus clients. If you are writing an D-Bus client, it is often easier to use the Gio::DBus::own_name(), Gio::DBus::watch_name() or DBusProxy::create_for_bus() APIs.

Since glibmm 2.26:

Constructor & Destructor Documentation

virtual Gio::DBusConnection::~DBusConnection (  )  [virtual]
Gio::DBusConnection::DBusConnection ( const Glib::RefPtr< IOStream >&  stream,
const Glib::ustring guid,
DBusConnectionFlags  flags,
const Glib::RefPtr< DBusAuthObserver >&  observer,
const SlotAsyncReady slot,
const Glib::RefPtr< Cancellable >&  cancellable 
) [protected]
Gio::DBusConnection::DBusConnection ( const Glib::RefPtr< IOStream >&  stream,
const Glib::ustring guid,
DBusConnectionFlags  flags,
const Glib::RefPtr< DBusAuthObserver >&  observer,
const Glib::RefPtr< Cancellable >&  cancellable 
) [protected]
Gio::DBusConnection::DBusConnection ( const Glib::ustring address,
DBusConnectionFlags  flags,
const Glib::RefPtr< DBusAuthObserver >&  observer,
const SlotAsyncReady slot,
const Glib::RefPtr< Cancellable >&  cancellable 
) [protected]
Gio::DBusConnection::DBusConnection ( const Glib::ustring address,
DBusConnectionFlags  flags,
const Glib::RefPtr< DBusAuthObserver >&  observer,
const Glib::RefPtr< Cancellable >&  cancellable 
) [protected]

Member Function Documentation

void Gio::DBusConnection::close ( const SlotAsyncReady slot  ) 
void Gio::DBusConnection::close ( const SlotAsyncReady slot,
const Glib::RefPtr< Cancellable >&  cancellable 
)
void Gio::DBusConnection::close (  ) 
bool Gio::DBusConnection::close_finish ( const Glib::RefPtr< AsyncResult >&  result  ) 

Finishes an operation started with g_dbus_connection_close().

Since glibmm 2.26:
Parameters:
res A AsyncResult obtained from the AsyncReadyCallback passed to g_dbus_connection_close().
Returns:
true if the operation succeeded, false if error is set.
void Gio::DBusConnection::close_sync ( const Glib::RefPtr< Cancellable >&  cancellable  ) 

Synchronously closees connection.

The calling thread is blocked until this is done. See g_dbus_connection_close() for the asynchronous version of this method and more details about what it does.

Since glibmm 2.26:
Parameters:
cancellable A Cancellable or 0.
Returns:
true if the operation succeeded, false if error is set.
void Gio::DBusConnection::close_sync (  ) 
Glib::RefPtr<DBusConnection> Gio::DBusConnection::create ( const Glib::RefPtr< IOStream >&  stream,
const Glib::ustring guid,
DBusConnectionFlags  flags,
const Glib::RefPtr< DBusAuthObserver >&  observer,
const Glib::RefPtr< Cancellable >&  cancellable = Glib::RefPtrCancellable >() 
)

Synchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.

If observer is not 0 it may be used to control the authentication process.

This is a synchronous failable constructor. See g_dbus_connection_new() for the asynchronous version.

Since glibmm 2.26:
Parameters:
stream A IOStream.
guid The GUID to use if a authenticating as a server or 0.
flags Flags describing how to make the connection.
observer A DBusAuthObserver or 0.
cancellable A Cancellable or 0.
Returns:
A DBusConnection or 0 if error is set. Free with Glib::object_unref().
Exceptions:
Glib::Error. 
void Gio::DBusConnection::create ( const Glib::RefPtr< IOStream >&  stream,
const Glib::ustring guid,
DBusConnectionFlags  flags,
const Glib::RefPtr< DBusAuthObserver >&  observer,
const SlotAsyncReady slot,
const Glib::RefPtr< Cancellable >&  cancellable = Glib::RefPtrCancellable >() 
)

Asynchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.

If observer is not 0 it may be used to control the authentication process.

When the operation is finished, callback will be invoked. You can then call g_dbus_connection_new_finish() to get the result of the operation.

This is a asynchronous failable constructor. See g_dbus_connection_new_sync() for the synchronous version.

Since glibmm 2.26:
Parameters:
stream A IOStream.
guid The GUID to use if a authenticating as a server or 0.
flags Flags describing how to make the connection.
observer A DBusAuthObserver or 0.
cancellable A Cancellable or 0.
callback A AsyncReadyCallback to call when the request is satisfied.
user_data The data to pass to callback.
static Glib::RefPtr<DBusConnection> Gio::DBusConnection::create_finish ( const Glib::RefPtr< AsyncResult >&  res  )  [static]
Exceptions:
Glib::Error. 
Glib::RefPtr<DBusConnection> Gio::DBusConnection::create_for_address ( const Glib::ustring address,
DBusConnectionFlags  flags,
const Glib::RefPtr< DBusAuthObserver >&  observer,
const Glib::RefPtr< Cancellable >&  cancellable = Glib::RefPtrCancellable >() 
)

Synchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by address which must be in the D-Bus address format.

This constructor can only be used to initiate client-side connections - use g_dbus_connection_new_sync() if you need to act as the server. In particular, flags cannot contain the DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.

This is a synchronous failable constructor. See g_dbus_connection_new_for_address() for the asynchronous version.

If observer is not 0 it may be used to control the authentication process.

Since glibmm 2.26:
Parameters:
address A D-Bus address.
flags Flags describing how to make the connection.
observer A DBusAuthObserver or 0.
cancellable A Cancellable or 0.
Returns:
A DBusConnection or 0 if error is set. Free with Glib::object_unref().
Exceptions:
Glib::Error. 
void Gio::DBusConnection::create_for_address ( const Glib::ustring address,
DBusConnectionFlags  flags,
const Glib::RefPtr< DBusAuthObserver >&  observer,
const SlotAsyncReady slot,
const Glib::RefPtr< Cancellable >&  cancellable = Glib::RefPtrCancellable >() 
)

Asynchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by address which must be in the D-Bus address format.

This constructor can only be used to initiate client-side connections - use g_dbus_connection_new() if you need to act as the server. In particular, flags cannot contain the DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags.

When the operation is finished, callback will be invoked. You can then call g_dbus_connection_new_finish() to get the result of the operation.

If observer is not 0 it may be used to control the authentication process.

This is a asynchronous failable constructor. See g_dbus_connection_new_for_address_sync() for the synchronous version.

Since glibmm 2.26:
Parameters:
address A D-Bus address.
flags Flags describing how to make the connection.
observer A DBusAuthObserver or 0.
cancellable A Cancellable or 0.
callback A AsyncReadyCallback to call when the request is satisfied.
user_data The data to pass to callback.
static Glib::RefPtr<DBusConnection> Gio::DBusConnection::create_for_address_finish ( const Glib::RefPtr< AsyncResult >&  res  )  [static]
Exceptions:
Glib::Error. 
void Gio::DBusConnection::flush ( const SlotAsyncReady slot  ) 
void Gio::DBusConnection::flush ( const SlotAsyncReady slot,
const Glib::RefPtr< Cancellable >&  cancellable 
)
void Gio::DBusConnection::flush (  ) 
bool Gio::DBusConnection::flush_finish ( const Glib::RefPtr< AsyncResult >&  result  ) 

Finishes an operation started with g_dbus_connection_flush().

Since glibmm 2.26:
Parameters:
res A AsyncResult obtained from the AsyncReadyCallback passed to g_dbus_connection_flush().
Returns:
true if the operation succeeded, false if error is set.
void Gio::DBusConnection::flush_sync ( const Glib::RefPtr< Cancellable >&  cancellable  ) 

Synchronously flushes connection.

The calling thread is blocked until this is done. See g_dbus_connection_flush() for the asynchronous version of this method and more details about what it does.

Since glibmm 2.26:
Parameters:
cancellable A Cancellable or 0.
Returns:
true if the operation succeeded, false if error is set.
void Gio::DBusConnection::flush_sync (  ) 
void Gio::DBusConnection::get ( BusType  bus_type,
const SlotAsyncReady slot,
const Glib::RefPtr< Cancellable >&  cancellable = Glib::RefPtrCancellable >() 
)

TODO.

DBusCapabilityFlags Gio::DBusConnection::get_capabilities (  )  const

Gets the capabilities negotiated with the remote peer.

Since glibmm 2.26:
Returns:
Zero or more flags from the DBusCapabilityFlags enumeration.
bool Gio::DBusConnection::get_exit_on_close (  )  const

Gets whether the process is terminated when connection is closed by the remote peer.

See DBusConnection:exit-on-close for more details.

Since glibmm 2.26:
Returns:
Whether the process is terminated when connection is closed by the remote peer.
static Glib::RefPtr<DBusConnection> Gio::DBusConnection::get_finish ( const Glib::RefPtr< AsyncResult >&  res  )  [static]
Exceptions:
Glib::Error. 
Glib::ustring Gio::DBusConnection::get_guid (  )  const

The GUID of the peer performing the role of server when authenticating.

See DBusConnection:guid for more details.

Since glibmm 2.26:
Returns:
The GUID. Do not free this string, it is owned by connection.
Glib::RefPtr<const Credentials> Gio::DBusConnection::get_peer_credentials (  )  const

Gets the credentials of the authenticated peer.

This will always return 0 unless connection acted as a server (e.g. DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) when set up and the client passed credentials as part of the authentication process.

In a message bus setup, the message bus is always the server and each application is a client. So this method will always return 0 for message bus clients.

Since glibmm 2.26:
Returns:
A Credentials or 0 if not available. Do not free this object, it is owned by connection.
Glib::RefPtr<Credentials> Gio::DBusConnection::get_peer_credentials (  ) 

Gets the credentials of the authenticated peer.

This will always return 0 unless connection acted as a server (e.g. DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) when set up and the client passed credentials as part of the authentication process.

In a message bus setup, the message bus is always the server and each application is a client. So this method will always return 0 for message bus clients.

Since glibmm 2.26:
Returns:
A Credentials or 0 if not available. Do not free this object, it is owned by connection.
Glib::RefPtr<const IOStream> Gio::DBusConnection::get_stream (  )  const

Gets the underlying stream used for IO.

Since glibmm 2.26:
Returns:
The stream used for IO.
Glib::RefPtr<IOStream> Gio::DBusConnection::get_stream (  ) 

Gets the underlying stream used for IO.

Since glibmm 2.26:
Returns:
The stream used for IO.
Glib::ustring Gio::DBusConnection::get_unique_name (  )  const

Gets the unique name of connection as assigned by the message bus.

This can also be used to figure out if connection is a message bus connection.

Since glibmm 2.26:
Returns:
The unique name or 0 if connection is not a message bus connection. Do not free this string, it is owned by connection.
const GDBusConnection* Gio::DBusConnection::gobj (  )  const [inline]

Provides access to the underlying C GObject.

Reimplemented from Gio::AsyncInitable.

GDBusConnection* Gio::DBusConnection::gobj (  )  [inline]

Provides access to the underlying C GObject.

Reimplemented from Gio::AsyncInitable.

GDBusConnection* Gio::DBusConnection::gobj_copy (  ) 

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

bool Gio::DBusConnection::is_closed (  )  const

Gets whether connection is closed.

Since glibmm 2.26:
Returns:
true if the connection is closed, false otherwise.
bool Gio::DBusConnection::send_message ( const Glib::RefPtr< DBusMessage >&  message,
DBusSendMessageFlags  flags,
guint32 *  out_serial 
)

Asynchronously sends message to the peer represented by connection.

Unless flags contain the DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number will be assigned by connection and set on message via g_dbus_message_set_serial(). If out_serial is not 0, then the serial number used will be written to this location prior to submitting the message to the underlying transport.

If connection is closed then the operation will fail with IO_ERROR_CLOSED. If message is not well-formed, the operation fails with IO_ERROR_INVALID_ARGUMENT.

See <xref linkend="gdbus-server"> and <xref linkend="gdbus-unix-fd-client"> for an example of how to use this low-level API to send and receive UNIX file descriptors.

Since glibmm 2.26:
Parameters:
message A DBusMessage.
flags Flags affecting how the message is sent.
out_serial Return location for serial number assigned to message when sending it or 0.
Returns:
true if the message was well-formed and queued for transmission, false if error is set.
void Gio::DBusConnection::send_message_with_reply ( const Glib::RefPtr< DBusMessage >&  message,
int  timeout_msec,
const SlotAsyncReady slot,
const Glib::RefPtr< Cancellable >&  cancellable = Glib::RefPtrCancellable >() 
)
Glib::RefPtr<DBusMessage> Gio::DBusConnection::send_message_with_reply_finish ( const Glib::RefPtr< AsyncResult >&  result  ) 
Exceptions:
Glib::Error. 
void Gio::DBusConnection::set_exit_on_close ( bool  exit_on_close = true  ) 

Sets whether the process should be terminated when connection is closed by the remote peer.

See DBusConnection:exit-on-close for more details.

Since glibmm 2.26:
Parameters:
exit_on_close Whether the process should be terminated when connection is closed by the remote peer.
void Gio::DBusConnection::start_message_processing (  ) 

If connection was created with DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method starts processing messages.

Does nothing on if connection wasn't created with this flag or if the method has already been called.

Since glibmm 2.26:

Friends And Related Function Documentation

Glib::RefPtr< Gio::DBusConnection > wrap ( GDBusConnection *  object,
bool  take_copy = false 
) [related]

A Glib::wrap() method for this object.

Parameters:
object The C instance.
take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns:
A C++ instance that wraps this C instance.
Generated on Sun Sep 19 21:30:34 2010 for glibmm by  doxygen 1.6.3