dbus基本接口

 

 

dbus例程


建立服务的流程:
----------------------------------
    建立一个dbus连接之后 -- dbus_bus_get()，为这个dbus连接(DbusConnection)起名 -- dbus_bus_request_name()，这个名字将会成为我们在后续进行远程调用的时候的服务名，然后我们进入监听循环 -- dbus_connection_read_write()。在循环中，我们从总线上取出消息 -- dbus_connection_pop_message()，并通过比对消息中的方法接口名和方法名 -- dbus_message_is_method_call()，如果一致，那么我们跳转到相应的处理中去。在相应的处理中，我们会从消息中取出远程调用的参数。并且建立起回传结果的通路 -- reply_to_method_call()。回传动作本身等同于一次不需要等待结果的远程调用。


发送信号的流程:
----------------------------------
    建立一个dbus连接之后，为这个dbus连接起名，建立一个发送信号的通道，注意，在建立通道的函数中，需要我们填写该信号的接口名和信号名 -- dbus_message_new_signal()。然后我们把信号对应的相关参数压进去 -- dbus_message_iter_init_append(); dbus_message_iter_append_basic()。然后就可以启动发送了 -- dbus_connection_send(); dbus_connection_flush。


进行一次远程调用的流程:
----------------------------------
    建立好dbus连接之后，为这dbus连接命名，申请一个远程调用通道 -- dbus_message_new_method_call()，注意，在申请远程调用通道的时候，需要填写服务器名，本次调用的接口名，和本次调用名(方法名)。压入本次调用的参数 -- dbus_message_iter_init_append(); dbus_message_iter_append_basic()，实际上是申请了一个首地址，我们就是把我们真正要传的参数，往这个首地址里面送(送完之后一般都会判断是否内存越界了)。然后就是启动发送调用并释放发送相关的消息结构 -- dbus_connection_send_with_reply()。这个启动函数中带有一个句柄。我们马上会阻塞等待这个句柄给我们带回总线上回传的消息。当这个句柄回传消息之后，我们从消息结构中分离出参数。用dbus提供的函数提取参数的类型和参数 -- dbus_message_iter_init(); dbus_message_iter_next(); dbus_message_iter_get_arg_type(); dbus_message_iter_get_basic()。也就达成了我们进行本次远程调用的目的了。


信号接收流程:
----------------------------------
    建立一个dbus连接之后，为这个dbus连接起名，为我们将要进行的消息循环添加匹配条件(就是通过信号名和信号接口名来进行匹配控制的) -- dbus_bus_add_match()。我们进入等待循环后，只需要对信号名，信号接口名进行判断就可以分别处理各种信号了。在各个处理分支上。我们可以分离出消息中的参数。对参数类型进行判断和其他的处理。


_read_write()
--------------------------------------
    As long as the connection is open, this function will block until it can read or write, then read or write, then return #TRUE.
    If the connection is closed, the function returns #FALSE.


dbus_connection_pop_message()
--------------------------------------
    Returns the first-received message from the incoming message queue, removing it from the queue. The caller owns a reference to the returned message. If the queue is empty, returns #NULL.


dbus_connection_send()
--------------------------------------
    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.
    @param connection the connection.
    @param message the message to write.
    @param serial return location for message serial, or #NULL if you don't care
    @returns #TRUE on success.


dbus_connection_send_with_reply()
--------------------------------------
    Queues a message to send, as with dbus_connection_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 #DBusPendingCall will see a reply message before any filters or registered object path handlers. See dbus_connection_dispatch() for details on when handlers are run.

    A #DBusPendingCall will always see exactly one reply message, unless it's cancelled with dbus_pending_call_cancel().

    If #NULL is passed for the pending_return, the #DBusPendingCall will still be generated internally, and used to track the message reply timeout. This means a timeout error will occur if no reply arrives, unlike with dbus_connection_send().
   
    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.

    @warning if the connection is disconnected, the #DBusPendingCall will be set to #NULL, so be careful with this.
   
    @param connection the connection
    @param message the message to send
    @param pending_return return location for a #DBusPendingCall object, or #NULL if connection is disconnected
    @param timeout_milliseconds timeout in milliseconds or -1 for default
    @returns #FALSE if no memory, #TRUE otherwise.




_is_signal()
--------------------------------------
    Checks whether the message is a signal with the given interface and member fields. If the message is not #DBUS_MESSAGE_TYPE_SIGNAL, or has a different interface or member field, returns #FALSE.


dbus_message_iter_init()
--------------------------------------
    Initializes a #DBusMessageIter for reading the arguments of the message passed in.


dbus_message_iter_next()
--------------------------------------
    Moves the iterator to the next field, if any. If there's no next field, returns #FALSE. If the iterator moves forward, returns #TRUE.


dbus_message_iter_get_arg_type()
--------------------------------------
    Returns the argument type of the argument that the message iterator points to. If the iterator is at the end of the message, returns #DBUS_TYPE_INVALID.


dbus_message_iter_get_basic()
--------------------------------------
    Reads a basic-typed value from the message iterator. Basic types are the non-containers such as integer and string.


dbus_message_new_signal()
--------------------------------------
    Constructs a new message representing a signal emission. Returns #NULL if memory can't be allocated for the message. A signal is identified by its originating object path, interface, and the name of the signal.

    Path, interface, and signal name must all be valid (the D-Bus specification defines the syntax of these fields).
   
    @param path the path to the object emitting the signal
    @param interface the interface the signal is emitted from
    @param name name of the signal
    @returns a new DBusMessage, free with dbus_message_unref()


dbus_message_iter_init_append()
--------------------------------------
    Initializes a #DBusMessageIter for appending arguments to the end of a message.
    @param message the message
    @param iter pointer to an iterator to initialize


dbus_message_iter_append_basic()
--------------------------------------
    Appends a basic-typed value to the message. The basic types are the non-container types such as integer and string.
    @param iter the append iterator
    @param type the type of the value
    @param value the address of the value
    @returns #FALSE if not enough memory


dbus_message_new_method_call()
--------------------------------------
    Constructs a new message to invoke a method on a remote object. Returns #NULL if memory can't be allocated for the message. The destination may be #NULL in which case no destination is set; this is appropriate when using D-Bus in a peer-to-peer context (no message bus). The interface may be #NULL, which means that if multiple methods with the given name exist it is undefined which one will be invoked.

    The path and method names may not be #NULL.

    Destination, path, interface, and method name can't contain any invalid characters (see the D-Bus specification).

    @param destination name that the message should be sent to or #NULL
    @param path object path the message should be sent to
    @param interface interface to invoke method on, or #NULL
    @param method method to invoke

    @returns a new DBusMessage, free with dbus_message_unref()


_get()
--------------------------------------
    Connects to a bus daemon and registers the client with it. If a connection to the bus already exists, then that connection is returned. The caller of this function owns a reference to the bus.
    @param type bus type
    @param error address where an error can be returned.
    @returns a #DBusConnection with new ref


dbus_bus_request_name()
--------------------------------------
    Asks the bus to assign the given name to this connection by invoking the RequestName method on the bus.

    First you should know that for each bus name, the bus stores a queue of connections that would like to own it. Only one owns it at a time - called the primary owner. If the primary owner releases the name or disconnects, then the next owner in the queue atomically takes over.

    So for example if you have an application org.freedesktop.TextEditor and multiple instances of it can be run, you can have all of them sitting in the queue. The first one to start up will receive messages sent to org.freedesktop.TextEditor, but if that one exits another will become the primary owner and receive messages.

    The queue means you don't need to manually watch for the current owner to disappear and then request the name again.
   
    @param connection the connection
    @param name the name to request
    @param flags flags
    @param error location to store the error
    @returns a result code, -1 if error is set

    给DBusConnection起名字(命名) -- 两个相互通信的连接(connection)不能同名
    命名规则: xxx.xxx (zeng.xiaolong)


dbus_bus_add_match()
--------------------------------------
    Adds a match rule to match messages going through the message bus. The "rule" argument is the string form of a match rule.
    @param connection connection to the message bus
    @param rule textual form of match rule
    @param error location to store any errors





dbus_pending_call_block()
--------------------------------------
    Block until the pending call is completed. The blocking is as with dbus_connection_send_with_reply_and_block(); it does not enter the main loop or process other messages, it simply waits for the reply in question.

    If the pending call is already completed, this function returns immediately.

    @todo when you start blocking, the timeout is reset, but it should really only use time remaining since the pending call was created. This requires storing timestamps instead of intervals in the timeout

    @param pending the pending call


dbus_pending_call_steal_reply()
--------------------------------------
    Gets the reply, or returns #NULL if none has been received yet. Ownership of the reply message passes to the caller. This function can only be called once per pending call, since the reply message is tranferred to the caller.

    @param pending the pending call
    @returns the reply message or #NULL.