added documentation for Connection and Dispatcher class

most documentation is copied from the dbus documentation and
modified to fit into dbus-c++
This commit is contained in:
Andreas Volz 2008-07-30 13:47:31 +02:00
parent f091b42263
commit 7826341ba3
4 changed files with 408 additions and 8 deletions

2
README
View file

@ -4,5 +4,5 @@ To compile debugging code configure the project with the --enable-debug option.
Hints
-----
Your applications based on dbus-c++ have to support PTHREAD and to export the variable HAVE_PTHREAD_H. This is a work in progress and my change.
Your applications based on dbus-c++ have to support PTHREAD and to export the variable HAVE_PTHREAD_H.

View file

@ -72,38 +72,377 @@ public:
bool operator == ( const Connection& ) const;
/*!
* \brief Adds a match rule to match messages going through the message bus.
*
* The "rule" argument is the string form of a match rule.
*
* If you pass NULL for the error, this function will not block; the match
* thus won't be added until you flush the connection, and if there's an error
* adding the match (only possible error is lack of resources in the bus), you
* won't find out about it.
*
* Normal API conventions would have the function return a boolean value
* indicating whether the error was set, but that would require blocking always
* to determine the return value.
*
* The AddMatch method is fully documented in the D-Bus specification. For
* quick reference, the format of the match rules is discussed here, but the
* specification is the canonical version of this information.
*
* Rules are specified as a string of comma separated key/value pairs. An
* example is "type='signal',sender='org.freedesktop.DBus',
* interface='org.freedesktop.DBus',member='Foo', path='/bar/foo',destination=':452345.34'"
*
* Possible keys you can match on are type, sender, interface, member, path,
* destination and numbered keys to match message args (keys are 'arg0', 'arg1', etc.).
* Omitting a key from the rule indicates a wildcard match. For instance omitting
* the member from a match rule but adding a sender would let all messages from
* that sender through regardless of the member.
*
* Matches are inclusive not exclusive so as long as one rule matches the
* message will get through. It is important to note this because every time a
* essage is received the application will be paged into memory to process it.
* This can cause performance problems such as draining batteries on embedded platforms.
*
* If you match message args ('arg0', 'arg1', and so forth) only string arguments
* will match. That is, arg0='5' means match the string "5" not the integer 5.
*
* Currently there is no way to match against non-string arguments.
*
* Matching on interface is tricky because method call messages only optionally
* specify the interface. If a message omits the interface, then it will NOT
* match if the rule specifies an interface name. This means match rules on
* method calls should not usually give an interface.
*
* However, signal messages are required to include the interface so when
* matching signals usually you should specify the interface in the match rule.
*
* For security reasons, you can match arguments only up to DBUS_MAXIMUM_MATCH_RULE_ARG_NUMBER.
*
* Match rules have a maximum length of DBUS_MAXIMUM_MATCH_RULE_LENGTH bytes.
*
* Both of these maximums are much higher than you're likely to need, they only
* exist because the D-Bus bus daemon has fixed limits on all resource usage.
*
* \param rule Textual form of match rule.
* \throw Error
*/
void add_match( const char* rule );
/*!
* \brief Removes a previously-added match rule "by value" (the most
* recently-added identical rule gets removed).
*
* The "rule" argument is the string form of a match rule.
*
* The bus compares match rules semantically, not textually, so whitespace and
* ordering don't have to be identical to the rule you passed to add_match().
*
* \param rule Textual form of match rule.
* \throw Error
*/
void remove_match( const char* rule );
bool add_filter( MessageSlot& );
/*!
* \brief Adds a message filter.
*
* Filters are handlers that are run on all incoming messages, prior to the
* objects registered with ObjectAdaptor::register_obj(). Filters are
* run in the order that they were added. The same handler can be added as a
* filter more than once, in which case it will be run more than once. Filters
* added during a filter callback won't be run on the message being processed.
*
* \param s The MessageSlot to add.
*/
bool add_filter( MessageSlot& s);
void remove_filter( MessageSlot& );
/*!
* \brief Removes a previously-added message filter.
*
* It is a programming error to call this function for a handler that has not
* been added as a filter. If the given handler was added more than once, only
* one instance of it will be removed (the most recently-added instance).
*
* \param s The MessageSlot to remove.
*/
void remove_filter( MessageSlot& s);
/*!
* \brief Sets the unique name of the connection, as assigned by the message bus.
*
* Can only be used if you registered with the bus manually (i.e. if you did
* not call register_bus()). Can only be called once per connection. After
* the unique name is set, you can get it with unique_name(void).
*
* The only reason to use this function is to re-implement the equivalent of
* register_bus() yourself. One (probably unusual) reason to do that might
* be to do the bus registration call asynchronously instead of synchronously.
*
* \note Just use dbus_bus_get() or dbus_bus_get_private(), or worst case
* register_bus(), instead of messing with this function. There's
* really no point creating pain for yourself by doing things manually.
* (Not sure if this is yet wrapped.)
*
* It's hard to use this function safely on shared connections (created by
* Connection()) in a multithreaded application, because only one
* registration attempt can be sent to the bus. If two threads are both
* sending the registration message, there is no mechanism in libdbus itself
* to avoid sending it twice.
*
* Thus, you need a way to coordinate which thread sends the registration
* attempt; which also means you know which thread will call
* unique_name(const char*). If you don't know about all threads in the app
* (for example, if some libraries you're using might start libdbus-using
* threads), then you need to avoid using this function on shared connections.
*
* \param n The unique name.
*/
bool unique_name( const char* n );
/*!
* \brief Gets the unique name of the connection as assigned by the message bus.
*
* Only possible after the connection has been registered with the message bus.
* All connections returned by dbus_bus_get() or dbus_bus_get_private() have
* been successfully registered. (Not sure if this is yet wrapped.)
*
* The name remains valid until the connection is freed, and should not be
* freed by the caller.
*
* Other than dbus_bus_get(), there are two ways to set the unique name; one
* is register_bus(), the other is unique_name(const char*). You are
* responsible for calling unique_name(const char*) if you register by hand
* instead of using register_bus().
*/
const char* unique_name() const;
/*!
* \brief Registers a connection with the bus.
*
* This must be the first thing an application does when connecting to the
* message bus. If registration succeeds, the unique name will be set, and
* can be obtained using unique_name(void).
*
* This function will block until registration is complete.
*
* If the connection has already registered with the bus (determined by
* checking whether unique_name(void) returns a non-NULL value),
* then this function does nothing.
*
* If you use dbus_bus_get() or dbus_bus_get_private() this function will be
* called for you. (Not sure if this is yet wrapped.)
*
* \note Just use dbus_bus_get() or dbus_bus_get_private() instead of
* register_bus() and save yourself some pain. Using register_bus()
* manually is only useful if you have your own custom message bus not found
* in DBusBusType.
*
* If you open a bus connection by the contructor of Connection() you will have to register_bus()
* yourself, or make the appropriate registration method calls yourself. If
* you send the method calls yourself, call unique_name(const char*) with
* the unique bus name you get from the bus.
*
* For shared connections (created with dbus_connection_open()) in a
* multithreaded application, you can't really make the registration calls
* yourself, because you don't know whether some other thread is also
* registering, and the bus will kick you off if you send two registration
* messages. (TODO: how is this done in the wrapper?)
*
* If you use register_bus() however, there is a lock that keeps both
* apps from registering at the same time.
*
* The rule in a multithreaded app, then, is that register_bus() must be
* used to register, or you need to have your own locks that all threads in
* the app will respect.
*
* In a single-threaded application you can register by hand instead of using
* register_bus(), as long as you check unique_name(void) to
* see if a unique name has already been stored by another thread before you
* send the registration messages.
*/
bool register_bus();
/*!
* \brief Gets whether the connection is currently open.
*
* A connection may become disconnected when the remote application closes its
* end, or exits; a connection may also be disconnected with disconnect().
*
* There are not separate states for "closed" and "disconnected," the two
* terms are synonymous.
*
* \return true If the connection is still alive.
*/
bool connected() const;
/*!
* \brief Closes a private connection, so no further data can be sent or received.
*
* This disconnects the transport (such as a socket) underlying the connection.
*
* Attempts to send messages after closing a connection are safe, but will
* result in error replies generated locally in libdbus.
*
* This function does not affect the connection's reference count. It's safe
* to close a connection more than once; all calls after the first do nothing.
* It's impossible to "reopen" a connection, a new connection must be created.
* This function may result in a call to the DBusDispatchStatusFunction set
* with Private::init(), as the disconnect
* message it generates needs to be dispatched.
*
* If a connection is dropped by the remote application, it will close itself.
*
* You must close a connection prior to releasing the last reference to the
* connection.
*
* You may not close a shared connection. Connections created with
* dbus_connection_open() or dbus_bus_get() are shared. These connections are
* owned by libdbus, and applications should only unref them, never close them.
* Applications can know it is safe to unref these connections because libdbus
* will be holding a reference as long as the connection is open. Thus, either
* the connection is closed and it is OK to drop the last reference, or the
* connection is open and the app knows it does not have the last reference.
*
* Connections created with dbus_connection_open_private() or
* dbus_bus_get_private() are not kept track of or referenced by libdbus.
* The creator of these connections is responsible for calling
* dbus_connection_close() prior to releasing the last reference, if the
* connection is not already disconnected.
*
* \todo dbus_connection_disconnect() was removed in dbus 0.9x. Maybe this
* function should be renamed to close().
*/
void disconnect();
/*!
* \brief Set whether _exit() should be called when the connection receives a
* disconnect signal.
*
* The call to _exit() comes after any handlers for the disconnect signal run;
* handlers can cancel the exit by calling this function.
*
* By default, exit_on_disconnect is false; but for message bus connections
* returned from dbus_bus_get() it will be toggled on by default.
*
* \param exit true If _exit() should be called after a disconnect signal.
*/
void exit_on_disconnect( bool exit );
/*!
* \brief Blocks until the outgoing message queue is empty.
*/
void flush();
bool send( const Message&, unsigned int* serial = NULL );
/*!
* \brief Adds a message to the outgoing message queue.
*
* Does not block to write the message to the network; that happens
* asynchronously. To force the message to be written, call
* dbus_connection_flush(). Because this only queues the message, the only
* reason it can fail is lack of memory. Even if the connection is disconnected,
* no error will be returned.
*
* If the function fails due to lack of memory, it returns FALSE. The function
* will never fail for other reasons; even if the connection is disconnected,
* you can queue an outgoing message, though obviously it won't be sent.
*
* The message serial is used by the remote application to send a reply; see
* Message::serial() or the D-Bus specification.
*
* \param msg The Message to write.
* \param serial Return location for message serial, or NULL if you don't care.
* \return true On success.
*/
bool send( const Message& msg, unsigned int* serial = NULL );
/*!
* \brief Sends a message and blocks a certain time period while waiting for a reply.
*
* This function does not reenter the main loop, i.e. messages other than the
* reply are queued up but not processed. This function is used to invoke
* method calls on a remote object.
*
* If a normal reply is received, it is returned, and removed from the
* incoming message queue. If it is not received, NULL is returned and the
* error is set to DBUS_ERROR_NO_REPLY. If an error reply is received, it is
* converted to a DBusError and returned as an error, then the reply message
* is deleted and NULL is returned. If something else goes wrong, result is
* set to whatever is appropriate, such as DBUS_ERROR_NO_MEMORY or DBUS_ERROR_DISCONNECTED.
*
* \warning While this function blocks the calling thread will not be
* processing the incoming message queue. This means you can end up
* deadlocked if the application you're talking to needs you to reply
* to a method. To solve this, either avoid the situation, block in a
* separate thread from the main connection-dispatching thread, or
* use PendingCall to avoid blocking.
*
* \param msg The Message to write.
* \param timeout Timeout in milliseconds (omit for default).
* \throw Error
*/
Message send_blocking( Message& msg, int timeout = -1);
PendingCall send_async( Message& msg, int timeout );
/*!
* \brief Queues a message to send, as with send(), but also
* returns a DBusPendingCall used to receive a reply to the message.
*
* If no reply is received in the given timeout_milliseconds, this function
* expires the pending reply and generates a synthetic error reply (generated
* in-process, not by the remote application) indicating that a timeout occurred.
*
* A PendingCall will see a reply message before any filters or registered
* object path handlers. See Connection::Private::do_dispatch() in dbus documentation
* for details on when handlers are run. (here: Connection::Private::do_dispatch())
*
* A PendingCall will always see exactly one reply message, unless it's
* cancelled with PendingCall::cancel().
*
* If -1 is passed for the timeout, a sane default timeout is used. -1 is
* typically the best value for the timeout for this reason, unless you want
* a very short or very long timeout. There is no way to avoid a timeout
* entirely, other than passing INT_MAX for the timeout to mean "very long
* timeout." libdbus clamps an INT_MAX timeout down to a few hours timeout though.
*
* \param msg The Message to write.
* \param timeout Timeout in milliseconds (omit for default).
* \throw ErrorNoMemory
*/
PendingCall send_async( Message& msg, int timeout = -1);
void request_name( const char* name, int flags = 0 );
/*!
* \brief Asks the bus whether a certain name has an owner.
*
* Using this can easily result in a race condition, since an owner can appear
* or disappear after you call this.
*
* If you want to request a name, just request it; if you want to avoid
* replacing a current owner, don't specify DBUS_NAME_FLAG_REPLACE_EXISTING
* and you will get an error if there's already an owner.
*
* \param name The name.
* \throw Error
*/
bool has_name( const char* name );
/*!
* \brief Starts a service that will request ownership of the given name.
*
* The returned result will be one of be one of DBUS_START_REPLY_SUCCESS or
* DBUS_START_REPLY_ALREADY_RUNNING if successful. Pass NULL if you don't
* care about the result.
*
* The flags parameter is for future expansion, currently you should specify 0.
*
* It's often easier to avoid explicitly starting services, and just send a
* method call to the service's bus name instead. Method calls start a service
* to handle them by default unless you call dbus_message_set_auto_start() to
* disable this behavior.
*
* \todo dbus_message_set_auto_start() not yet wrapped!
*/
bool start_service( const char* name, unsigned long flags );
const std::vector<std::string>& names();

View file

@ -43,12 +43,33 @@ public:
virtual ~Timeout(){}
/*!
* return The dbus timeout interval in miliseconds.
* \brief Gets the timeout interval.
*
* The dbus_timeout_handle() should be called each time this interval elapses,
* starting after it elapses once.
*
* The interval may change during the life of the timeout; if so, the timeout
* will be disabled and re-enabled (calling the "timeout toggled function") to
* notify you of the change.
*
* return The interval in miliseconds.
*/
int interval() const;
bool enabled() const;
/*!
* \brief Calls the timeout handler for this timeout.
*
* This function should be called when the timeout occurs.
*
* If this function returns FALSE, then there wasn't enough memory to handle
* the timeout. Typically just letting the timeout fire again next time it
* naturally times out is an adequate response to that problem, but you could
* try to do more if you wanted.
*
* return false If there wasn't enough memory.
*/
bool handle();
virtual void toggle() = 0;
@ -72,12 +93,48 @@ public:
virtual ~Watch(){}
/*!
* \brief A main loop could poll this descriptor to integrate dbus-c++.
*
* This function calls dbus_watch_get_socket() on win32 and
* dbus_watch_get_unix_fd() on all other systems. (see dbus documentation)
*
* @return The file descriptor.
*/
int descriptor() const;
/*!
* \brief Gets flags from DBusWatchFlags indicating what conditions should be
* monitored on the file descriptor.
*
* The flags returned will only contain DBUS_WATCH_READABLE and DBUS_WATCH_WRITABLE,
* never DBUS_WATCH_HANGUP or DBUS_WATCH_ERROR; all watches implicitly include
* a watch for hangups, errors, and other exceptional conditions.
*
* @return The conditions to watch.
*/
int flags() const;
bool enabled() const;
/*!
* \brief Called to notify the D-Bus library when a previously-added watch
* is ready for reading or writing, or has an exception such as a hangup.
*
* If this function returns FALSE, then the file descriptor may still be
* ready for reading or writing, but more memory is needed in order to do the
* reading or writing. If you ignore the FALSE return, your application may
* spin in a busy loop on the file descriptor until memory becomes available,
* but nothing more catastrophic should happen.
*
* dbus_watch_handle() cannot be called during the DBusAddWatchFunction, as the
* connection will not be ready to handle that watch yet.
*
* It is not allowed to reference a DBusWatch after it has been passed to remove_function.
*
* @param flags The poll condition using DBusWatchFlags values.
* @return false If there wasn't enough memory.
*/
bool handle( int flags );
virtual void toggle() = 0;

View file

@ -70,7 +70,11 @@ Watch::Watch( Watch::Internal* i )
int Watch::descriptor() const
{
return dbus_watch_get_fd((DBusWatch*)_int);
#if HAVE_WIN32
return dbus_watch_get_socket((DBusWatch*)_int);
#else
return dbus_watch_get_unix_fd((DBusWatch*)_int);
#endif
}
int Watch::flags() const