From 7652304bff969afb3969603149bb385efe861fe8 Mon Sep 17 00:00:00 2001 From: "John (J5) Palmieri" Date: Thu, 3 Aug 2006 20:34:36 +0000 Subject: * s/D-BUS/D-Bus/g --- doc/dbus-faq.xml | 132 ++++++++++++++++++++++----------------------- doc/dbus-specification.xml | 98 ++++++++++++++++----------------- doc/dbus-test-plan.xml | 36 ++++++------- doc/dbus-tutorial.xml | 126 +++++++++++++++++++++---------------------- doc/introspect.dtd | 6 +-- 5 files changed, 199 insertions(+), 199 deletions(-) (limited to 'doc') diff --git a/doc/dbus-faq.xml b/doc/dbus-faq.xml index a233a212..963db366 100644 --- a/doc/dbus-faq.xml +++ b/doc/dbus-faq.xml @@ -6,7 +6,7 @@
- D-BUS FAQ + D-Bus FAQ Version 0.1 22 January 2005 @@ -33,12 +33,12 @@ - What is D-BUS? + What is D-Bus? - This is probably best answered by reading the D-BUS tutorial. In + This is probably best answered by reading the D-Bus tutorial. In short, it is a system consisting of 1) a wire protocol for exposing a typical object-oriented language/framework to other applications; and 2) a bus daemon that allows applications to find and monitor one another. @@ -49,12 +49,12 @@ - Is D-BUS stable/finished? + Is D-Bus stable/finished? - D-BUS has not yet reached 1.0. The README + D-Bus has not yet reached 1.0. The README file has a discussion of the API/ABI stability guarantees before and after 1.0. In short, there are no guarantees before 1.0, and stability of both protocol and reference library will be maintained after 1.0. @@ -80,8 +80,8 @@ as well. The AFL is an "X-style" or "BSD-style" license compatible with proprietary licensing, but it does have some requirements; in particular it prohibits you from filing a lawsuit alleging that the - D-BUS software infringes your patents while you continue to - use D-BUS. If you're going to sue, you have to stop using + D-Bus software infringes your patents while you continue to + use D-Bus. If you're going to sue, you have to stop using the software. Read the licenses to determine their meaning, this FAQ entry is not intended to change the meaning or terms of the licenses. @@ -150,12 +150,12 @@ - Is D-BUS a "component system"? + Is D-Bus a "component system"? - D-BUS is not a component system. "Component system" was originally + D-Bus is not a component system. "Component system" was originally defined by COM, and was essentially a workaround for the limitations of the C++ object system (adding introspection, runtime location of objects, ABI guarantees, and so forth). With the C# language and CLR, @@ -178,9 +178,9 @@ A third, orthogonal feature is interprocess communication or IPC. - D-BUS is an IPC system. Given an object (or "component" if you must), + D-Bus is an IPC system. Given an object (or "component" if you must), you can expose the functionality of that object over an IPC system. - Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-BUS. + Examples of IPC systems are DCOM, CORBA, SOAP, XML-RPC, and D-Bus. You can use any of these IPC systems with any object/component system, though some of them are "tuned" for specific object systems. You can think of an IPC system primarily as a wire protocol. @@ -223,7 +223,7 @@ - How fast is the D-BUS reference implementation? + How fast is the D-Bus reference implementation? @@ -231,13 +231,13 @@ Of course it depends a bit on what you're doing. This mail contains some benchmarking. At the time of that - benchmark, D-BUS one-to-one communication was about 2.5x slower than + benchmark, D-Bus one-to-one communication was about 2.5x slower than simply pushing the data raw over a socket. After the recent rewrite of - the marshaling code, D-BUS is slower than that because a lot of + the marshaling code, D-Bus is slower than that because a lot of optimization work was lost. But it can probably be sped up again. - D-BUS communication with the intermediate bus daemon should be + D-Bus communication with the intermediate bus daemon should be (and as last profiled, was) about twice as slow as one-to-one mode, because a round trip involves four socket reads/writes rather than two socket reads/writes. @@ -252,7 +252,7 @@ not a good idea all things considered. - Raw bandwidth isn't the only concern; D-BUS is designed to + Raw bandwidth isn't the only concern; D-Bus is designed to enable asynchronous communication and avoid round trips. This is frequently a more important performance issue than throughput. @@ -264,7 +264,7 @@ - How large is the D-BUS reference implementation? + How large is the D-Bus reference implementation? @@ -283,39 +283,39 @@ - How does D-BUS differ from other interprocess communication + How does D-Bus differ from other interprocess communication or networking protocols? - The best place to start is to read the D-BUS tutorial, so - you have a concrete idea what D-BUS actually is. If you + The best place to start is to read the D-Bus tutorial, so + you have a concrete idea what D-Bus actually is. If you understand other protocols on a wire format level, you - may also want to read the D-BUS specification to see what - D-BUS looks like on a low level. + may also want to read the D-Bus specification to see what + D-Bus looks like on a low level. - As the tutorial and specification both explain, D-BUS is tuned + As the tutorial and specification both explain, D-Bus is tuned for some specific use cases. Thus, it probably isn't tuned for what you want to do, unless you are doing the things - D-BUS was designed for. Don't make the mistake of thinking + D-Bus was designed for. Don't make the mistake of thinking that any system labeled "IPC" is the same thing. - The D-BUS authors would not recommend using D-BUS + The D-Bus authors would not recommend using D-Bus for applications where it doesn't make sense. - The following questions compare D-BUS to some other - protocols primarily to help you understand D-BUS - and decide whether it's appropriate; D-BUS is neither intended + The following questions compare D-Bus to some other + protocols primarily to help you understand D-Bus + and decide whether it's appropriate; D-Bus is neither intended nor claimed to be the right choice for every application. - It should be possible to bridge D-BUS to other IPC systems, - just as D-BUS can be bridged to object systems. + It should be possible to bridge D-Bus to other IPC systems, + just as D-Bus can be bridged to object systems. - Note: the D-BUS mailing list subscribers are very much not + Note: the D-Bus mailing list subscribers are very much not interested in debating which IPC system is the One True System. So if you want to discuss that, please use another forum. @@ -326,7 +326,7 @@ - How does D-BUS differ from CORBA? + How does D-Bus differ from CORBA? @@ -360,18 +360,18 @@ SOAP are the latest fad. - Like D-BUS, CORBA uses a fast binary protocol (IIOP). Both systems + Like D-Bus, CORBA uses a fast binary protocol (IIOP). Both systems work in terms of objects and methods, and have concepts such as - "oneway" calls. Only D-BUS has direct support for "signals" as in + "oneway" calls. Only D-Bus has direct support for "signals" as in GLib/Qt (or Java listeners, or C# delegates). - D-BUS hardcodes and specifies a lot of things that CORBA leaves open-ended, - because CORBA is more generic and D-BUS has two specific use-cases in mind. - This makes D-BUS a bit simpler. + D-Bus hardcodes and specifies a lot of things that CORBA leaves open-ended, + because CORBA is more generic and D-Bus has two specific use-cases in mind. + This makes D-Bus a bit simpler. - However, unlike CORBA D-BUS does not specify the + However, unlike CORBA D-Bus does not specify the API for the language bindings. Instead, "native" bindings adapted specifically to the conventions of a framework such as QObject, GObject, C#, Java, Python, etc. are encouraged. The libdbus reference @@ -383,14 +383,14 @@ Many CORBA implementations such as ORBit are faster than the libdbus - reference implementation. One reason is that D-BUS considers data + reference implementation. One reason is that D-Bus considers data from the other end of the connection to be untrusted and extensively validates it. But generally speaking other priorities were placed - ahead of raw speed in the libdbus implementation. A fast D-BUS + ahead of raw speed in the libdbus implementation. A fast D-Bus implementation along the lines of ORBit should be possible, of course. - On a more trivial note, D-BUS involves substantially fewer acronyms + On a more trivial note, D-Bus involves substantially fewer acronyms than CORBA. @@ -400,7 +400,7 @@ - How does D-BUS differ from XML-RPC and SOAP? + How does D-Bus differ from XML-RPC and SOAP? @@ -421,7 +421,7 @@ constant fine-grained IPC among applications in a desktop session. - D-BUS offers persistent connections and with the bus daemon + D-Bus offers persistent connections and with the bus daemon supports lifecycle tracking of other applications connected to the bus. With XML-RPC and SOAP, typically each method call exists in isolation and has its own HTTP connection. @@ -432,7 +432,7 @@ - How does D-BUS differ from DCE? + How does D-Bus differ from DCE? @@ -447,7 +447,7 @@ has released an implementation as open source software. DCE is quite capable, and includes a vast amount of functionality such as a distributed time service. As the name implies, DCE is intended for - use in a large, multi-computer distributed application. D-BUS would + use in a large, multi-computer distributed application. D-Bus would not be well-suited for this. @@ -457,7 +457,7 @@ - How does D-BUS differ from DCOM and COM? + How does D-Bus differ from DCOM and COM? @@ -465,7 +465,7 @@ Start by reading . - Comparing D-BUS to COM is apples and oranges; + Comparing D-Bus to COM is apples and oranges; see . @@ -478,7 +478,7 @@ - How does D-BUS differ from ZeroC's Internet Communications Engine (Ice) + How does D-Bus differ from ZeroC's Internet Communications Engine (Ice) @@ -488,7 +488,7 @@ The Internet Communications Engine (Ice) is a powerful IPC mechanism more - on the level of SOAP or CORBA than D-BUS. Ice has a "dual-license" + on the level of SOAP or CORBA than D-Bus. Ice has a "dual-license" business around it; i.e. you can use it under the GPL, or pay for a proprietary license. @@ -498,7 +498,7 @@ - How does D-BUS differ from Inter-Client Exchange (ICE)? + How does D-Bus differ from Inter-Client Exchange (ICE)? @@ -510,7 +510,7 @@ ICE is a binary protocol designed for desktop use, and KDE's DCOP - builds on ICE. ICE is substantially simpler than D-BUS (in contrast + builds on ICE. ICE is substantially simpler than D-Bus (in contrast to most of the other IPC systems mentioned here, which are more complex). ICE doesn't really define a mapping to objects and methods (DCOP adds that layer). The reference implementation of ICE (libICE) @@ -518,7 +518,7 @@ DCOP and XSMP are the only two widely-used applications of ICE, - and both could in principle be replaced by D-BUS. (Though whether + and both could in principle be replaced by D-Bus. (Though whether GNOME and KDE will bother is an open question.) @@ -529,7 +529,7 @@ - How does D-BUS differ from DCOP? + How does D-Bus differ from DCOP? @@ -537,15 +537,15 @@ Start by reading . - D-BUS is intentionally pretty similar to DCOP, and can be thought of as a "DCOP the next generation" suitable for sharing between the various open source desktop projects. - D-BUS is a bit more complex than DCOP, though the Qt binding for D-BUS + D-Bus is a bit more complex than DCOP, though the Qt binding for D-Bus should not be more complex for programmers. The additional complexity - of D-BUS arises from its separation of object references vs. bus names + of D-Bus arises from its separation of object references vs. bus names vs. interfaces as distinct concepts, and its support for one-to-one connections in addition to connections over the bus. The libdbus reference implementation has a lot of API to support multiple bindings @@ -553,14 +553,14 @@ in order to support secure applications such as the systemwide bus. - D-BUS is probably somewhat slower than DCOP due to data validation + D-Bus is probably somewhat slower than DCOP due to data validation and more "layers" in the reference implementation. A comparison hasn't been posted to the list though. - At this time, KDE has not committed to using D-BUS, but there have - been discussions of KDE bridging D-BUS and DCOP, or even changing - DCOP's implementation to use D-BUS internally (so that GNOME and KDE + At this time, KDE has not committed to using D-Bus, but there have + been discussions of KDE bridging D-Bus and DCOP, or even changing + DCOP's implementation to use D-Bus internally (so that GNOME and KDE would end up using exactly the same bus). See the KDE mailing list archives for some of these discussions. @@ -571,7 +571,7 @@ - How does D-BUS differ from [yet more IPC mechanisms]? + How does D-Bus differ from [yet more IPC mechanisms]? @@ -604,10 +604,10 @@ If you're writing a desktop application for UNIX, - then D-BUS is of course our recommendation for + then D-Bus is of course our recommendation for talking to other parts of the desktop session. (With the caveat that you should use a stable release - of D-BUS; until we reach 1.0, there isn't a stable release.) + of D-Bus; until we reach 1.0, there isn't a stable release.) If you're doing something complicated such as clustering, @@ -616,10 +616,10 @@ areas and you should ask someone else or try a search engine. - Note: the D-BUS mailing list is probably not the place to + Note: the D-Bus mailing list is probably not the place to discuss which system is appropriate for your application, though you are welcome to ask specific questions about - D-BUS after reading this FAQ, the tutorial, and + D-Bus after reading this FAQ, the tutorial, and searching the list archives. The best way to search the list archives is probably to use an Internet engine such as Google. On Google, @@ -637,7 +637,7 @@ - The D-BUS web site + The D-Bus web site has a link to the bug tracker, which is the best place to store patches. You can also post them to the list, especially if you want to discuss the patch or get feedback. diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml index 05f6ad1c..2861a2ce 100644 --- a/doc/dbus-specification.xml +++ b/doc/dbus-specification.xml @@ -6,7 +6,7 @@
- D-BUS Specification + D-Bus Specification Version 0.11 6 February 2005 @@ -46,30 +46,30 @@ Introduction - D-BUS is a system for low-latency, low-overhead, easy to use + D-Bus is a system for low-latency, low-overhead, easy to use interprocess communication (IPC). In more detail: - D-BUS is low-latency because it is designed + D-Bus is low-latency because it is designed to avoid round trips and allow asynchronous operation, much like the X protocol. - D-BUS is low-overhead because it uses a + D-Bus is low-overhead because it uses a binary protocol, and does not have to convert to and from a text - format such as XML. Because D-BUS is intended for potentially + format such as XML. Because D-Bus is intended for potentially high-resolution same-machine IPC, not primarily for Internet IPC, this is an interesting optimization. - D-BUS is easy to use because it works in terms + D-Bus is easy to use because it works in terms of messages rather than byte streams, and - automatically handles a lot of the hard IPC issues. Also, the D-BUS + automatically handles a lot of the hard IPC issues. Also, the D-Bus library is designed to be wrapped in a way that lets developers use their framework's existing object/type system, rather than learning a new one specifically for IPC. @@ -79,25 +79,25 @@ - The base D-BUS protocol is a one-to-one (peer-to-peer or client-server) + The base D-Bus protocol is a one-to-one (peer-to-peer or client-server) protocol, specified in . That is, it is a system for one application to talk to a single other application. However, the primary intended application of the protocol is the - D-BUS message bus, specified in message bus, specified in . The message bus is a special application that accepts connections from multiple other applications, and forwards messages among them. - Uses of D-BUS include notification of system changes (notification of when + Uses of D-Bus include notification of system changes (notification of when a camera is plugged in to a computer, or a new version of some software has been installed), or desktop interoperability, for example a file monitoring service or a configuration service. - D-BUS is designed for two specific use cases: + D-Bus is designed for two specific use cases: @@ -112,9 +112,9 @@ - D-BUS is not intended to be a generic IPC system for any possible + D-Bus is not intended to be a generic IPC system for any possible application, and intentionally omits many features found in other - IPC systems for this reason. D-BUS may turn out to be useful + IPC systems for this reason. D-Bus may turn out to be useful in unanticipated applications, but future versions of this spec and the reference implementation probably will not incorporate features that interfere with the core use cases. @@ -160,7 +160,7 @@ Type Signatures - The D-BUS protocol does not include type tags in the marshaled data; a + The D-Bus protocol does not include type tags in the marshaled data; a block of marshaled values must have a known type signature. The type signature is made up of type codes. A type code is an ASCII character representing the @@ -212,7 +212,7 @@ - The STRUCT type code 'r' is not currently used in the D-BUS protocol, + The STRUCT type code 'r' is not currently used in the D-Bus protocol, but is useful in code that implements the protocol. This type code is specified to allow such code to interoperate in non-protocol contexts. @@ -296,7 +296,7 @@ - The following table summarizes the D-BUS types. + The following table summarizes the D-Bus types. @@ -389,12 +389,12 @@ Given a type signature, a block of bytes can be converted into typed values. This section describes the format of the block of bytes. Byte - order and alignment issues are handled uniformly for all D-BUS types. + order and alignment issues are handled uniformly for all D-Bus types. A block of bytes has an associated byte order. The byte order - has to be discovered in some way; for D-BUS messages, the + has to be discovered in some way; for D-Bus messages, the byte order is part of the message header as described in . For now, assume that the byte order is known to be either little endian or big @@ -550,7 +550,7 @@ An object path is a name used to refer to an object instance. - Conceptually, each participant in a D-BUS message exchange may have + Conceptually, each participant in a D-Bus message exchange may have any number of object instances (think of C++ or Java objects) and each such instance will have a path. Like a filesystem, the object instances in an application form a hierarchical tree. @@ -721,7 +721,7 @@ Major protocol version of the sending application. If the major protocol version of the receiving application does not match, the applications will not be able to communicate and the - D-BUS connection must be disconnected. The major protocol + D-Bus connection must be disconnected. The major protocol version for this version of the specification is 0. FIXME this field is stupid and pointless to put in every message. @@ -960,7 +960,7 @@ Valid Names - The various names in D-BUS messages have some restrictions. + The various names in D-Bus messages have some restrictions. There is a maximum name length @@ -1129,16 +1129,16 @@ Mapping method calls to native APIs - APIs for D-BUS may map method calls to a method call in a specific + APIs for D-Bus may map method calls to a method call in a specific programming language, such as C++, or may map a method call written - in an IDL to a D-BUS message. + in an IDL to a D-Bus message. In APIs of this nature, arguments to a method are often termed "in" (which implies sent in the METHOD_CALL), or "out" (which implies returned in the METHOD_RETURN). Some APIs such as CORBA also have "inout" arguments, which are both sent and received, i.e. the caller - passes in a value which is modified. Mapped to D-BUS, an "inout" + passes in a value which is modified. Mapped to D-Bus, an "inout" argument is equivalent to an "in" argument, followed by an "out" argument. You can't pass things "by reference" over the wire, so "inout" is purely an illusion of the in-process API. @@ -1159,14 +1159,14 @@ exceptions. - In converting from native APIs to D-BUS, it is perhaps nice to - map D-BUS naming conventions ("FooBar") to native conventions + In converting from native APIs to D-Bus, it is perhaps nice to + map D-Bus naming conventions ("FooBar") to native conventions such as "fooBar" or "foo_bar" automatically. This is OK as long as you can say that the native API is one that - was specifically written for D-BUS. It makes the most sense + was specifically written for D-Bus. It makes the most sense when writing object implementations that will be exported - over the bus. Object proxies used to invoke remote D-BUS - objects probably need the ability to call any D-BUS method, + over the bus. Object proxies used to invoke remote D-Bus + objects probably need the ability to call any D-Bus method, and thus a magic name mapping like this could be a problem. @@ -1256,7 +1256,7 @@ Invalid Protocol and Spec Extensions - For security reasons, the D-BUS protocol should be strictly parsed and + For security reasons, the D-Bus protocol should be strictly parsed and validated, with the exception of defined extension points. Any invalid protocol or spec violations should result in immediately dropping the connection without notice to the other end. Exceptions should be @@ -1275,10 +1275,10 @@ - The following extension points are built in to D-BUS on purpose and must + The following extension points are built in to D-Bus on purpose and must not be treated as invalid protocol. The extension points are intended for use by future versions of this spec, they are not intended for third - parties. At the moment, the only way a third party could extend D-BUS + parties. At the moment, the only way a third party could extend D-Bus without breaking interoperability would be to introduce a way to negotiate new feature support as part of the auth protocol, using EXTENSION_-prefixed commands. There is not yet a standard way to negotiate features. @@ -1432,12 +1432,12 @@ The first octet received by the client after the \r\n of the OK command must be the first octet of the authenticated/encrypted - stream of D-BUS messages. + stream of D-Bus messages. The first octet received by the server after the \r\n of the BEGIN command from the client must be the first octet of the - authenticated/encrypted stream of D-BUS messages. + authenticated/encrypted stream of D-Bus messages. @@ -1471,7 +1471,7 @@ The first octet received by the server after the \r\n of the BEGIN command from the client must be the first octet of the - authenticated/encrypted stream of D-BUS messages. + authenticated/encrypted stream of D-Bus messages. @@ -1493,13 +1493,13 @@ OK Command The OK command indicates that the client has been authenticated, - and that further communication will be a stream of D-BUS messages + and that further communication will be a stream of D-Bus messages (optionally encrypted, as negotiated) rather than this protocol. The first octet received by the client after the \r\n of the OK command must be the first octet of the authenticated/encrypted - stream of D-BUS messages. + stream of D-Bus messages. The client must respond to the OK command by sending a BEGIN @@ -1531,12 +1531,12 @@ if only canceling/rejecting the authentication. - If the D-BUS protocol changes incompatibly at some future time, + If the D-Bus protocol changes incompatibly at some future time, applications implementing the new protocol would probably be able to check for support of the new protocol by sending a new command and receiving an ERROR from applications that don't understand it. Thus the ERROR feature of the auth protocol is an escape hatch that lets us - negotiate extensions or changes to the D-BUS protocol in the future. + negotiate extensions or changes to the D-Bus protocol in the future. @@ -2016,7 +2016,7 @@ Authentication mechanisms This section describes some new authentication mechanisms. - D-BUS also allows any standard SASL mechanism of course. + D-Bus also allows any standard SASL mechanism of course. DBUS_COOKIE_SHA1 @@ -2266,7 +2266,7 @@ Naming Conventions - D-BUS namespaces are all lowercase and correspond to reversed domain + D-Bus namespaces are all lowercase and correspond to reversed domain names, as with Java. e.g. "org.freedesktop" @@ -2284,7 +2284,7 @@ See for details on the notation used in this section. There are some standard interfaces - that may be useful across various D-BUS applications. + that may be useful across various D-Bus applications. <literal>org.freedesktop.DBus.Peer</literal> @@ -2961,7 +2961,7 @@ The following table describes the keys that can be used to create a match rule: - The following table summarizes the D-BUS types. + The following table summarizes the D-Bus types. @@ -3032,7 +3032,7 @@ service. - With D-BUS, starting a service is normally done by name. That is, + With D-Bus, starting a service is normally done by name. That is, applications ask the message bus to start some program that will own a well-known name, such as org.freedesktop.TextEditor. This implies a contract documented along with the name @@ -3175,7 +3175,7 @@ unix:path=/var/run/dbus/system_bus_socket. - The D-BUS reference implementation actually honors the + The D-Bus reference implementation actually honors the $(localstatedir) configure option for this address, on both client and server side. @@ -3747,7 +3747,7 @@ Message - A message is the atomic unit of communication via the D-BUS + A message is the atomic unit of communication via the D-Bus protocol. It consists of a header and a body; the body is made up of arguments. @@ -3772,7 +3772,7 @@ See . "Name" may also be used to refer to some of the other names - in D-BUS, such as interface names. + in D-Bus, such as interface names. @@ -3803,7 +3803,7 @@ An application talking directly to another application, without going through a message bus. One-to-one connections may be "peer to peer" or - "client to server." The D-BUS protocol has no concept of client + "client to server." The D-Bus protocol has no concept of client vs. server after a connection has authenticated; the flow of messages is symmetrical (full duplex). @@ -3813,7 +3813,7 @@ Path - Object references (object names) in D-BUS are organized into a + Object references (object names) in D-Bus are organized into a filesystem-style hierarchy, so each object is named by a path. As in LDAP, there's no difference between "files" and "directories"; a path can refer to an object, while still having child objects below it. diff --git a/doc/dbus-test-plan.xml b/doc/dbus-test-plan.xml index b69f9405..e6aafb9a 100644 --- a/doc/dbus-test-plan.xml +++ b/doc/dbus-test-plan.xml @@ -6,7 +6,7 @@
- D-BUS Test Plan + D-Bus Test Plan 14 February 2003 @@ -22,7 +22,7 @@ Introduction - This document tries to explain the details of the test plan for D-BUS + This document tries to explain the details of the test plan for D-Bus The importance of testing @@ -32,21 +32,21 @@ overall. - D-BUS is a large and complex piece of software (about 25,000 + D-Bus is a large and complex piece of software (about 25,000 lines of code for the client library, and 2,500 lines of code for the bus daemon) and it's therefore important to try to make sure that all parts of the software is functioning correctly. - D-BUS can be built with support for testing by passing + D-Bus can be built with support for testing by passing --enable-tests. to the configure script. It is recommended that production systems build without testing - since that reduces the D-BUS client library size. + since that reduces the D-Bus client library size. - Testing the D-BUS client library + Testing the D-Bus client library The tests for the client library consist of the dbus-test program which is a unit test for all aspects of the client @@ -56,7 +56,7 @@ Data Structures - The D-BUS client library consists of some data structures that + The D-Bus client library consists of some data structures that are used internally; a linked list class, a hashtable class and a string class. All aspects of those are tested by dbus-test. @@ -64,15 +64,15 @@ Message loader - The message loader is the part of D-BUS that takes messages in + The message loader is the part of D-Bus that takes messages in raw character form and parses them, turning them into DBusMessages. - This is one of the parts of D-BUS that + This is one of the parts of D-Bus that must be absolutely bug-free and robust. The message loader should be able to handle invalid and incomplete messages without crashing. Not doing so is a - serious issue and can easily result in D-BUS being exploitable + serious issue and can easily result in D-Bus being exploitable to DoS attacks. @@ -101,7 +101,7 @@ The file format of messages in string form is documented in - the D-BUS Reference Manual. + the D-Bus Reference Manual. The message test part of dbus-test is using the message @@ -145,9 +145,9 @@ - Testing the D-BUS bus daemon + Testing the D-Bus bus daemon - Since the D-BUS bus daemon is using the D-BUS client library it + Since the D-Bus bus daemon is using the D-Bus client library it will benefit from all tests done on the client library, but there is still the issue of testing client-server communication. This is more complicated since it it may require another process @@ -156,15 +156,15 @@ The debug transport - In D-BUS, a transport is a class that + In D-Bus, a transport is a class that handles sending and receiving raw data over a certain - medium. The transport that is used most in D-BUS is the UNIX + medium. The transport that is used most in D-Bus is the UNIX transport with sends and recevies data over a UNIX socket. A transport that tunnels data through X11 client messages is also under development. - The D-BUS debug transport is a specialized transport that + The D-Bus debug transport is a specialized transport that works in-process. This means that a client and server that exists in the same process can talk to eachother without using a socket. @@ -174,7 +174,7 @@ The bus-test program The bus-test program is a program that is used to test various - parts of the D-BUS bus daemon; robustness and that it conforms + parts of the D-Bus bus daemon; robustness and that it conforms to the specifications. @@ -197,7 +197,7 @@ Out-Of-Memory robustness - Since D-BUS should be able to be used in embedded devices, and + Since D-Bus should be able to be used in embedded devices, and also as a system service, it should be able to cope with low-memory situations without exiting or crashing. diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml index 78e8489c..6d814fce 100644 --- a/doc/dbus-tutorial.xml +++ b/doc/dbus-tutorial.xml @@ -6,7 +6,7 @@
- D-BUS Tutorial + D-Bus Tutorial Version 0.4.1 15 July 2005 @@ -42,9 +42,9 @@ - What is D-BUS? + What is D-Bus? - D-BUS is a system for interprocess communication + D-Bus is a system for interprocess communication (IPC). Architecturally, it has several layers: @@ -68,7 +68,7 @@ application frameworks. For example, libdbus-glib and libdbus-qt. There are also bindings to languages such as Python. These wrapper libraries are the API most people should use, - as they simplify the details of D-BUS programming. libdbus is + as they simplify the details of D-Bus programming. libdbus is intended to be a low-level backend for the higher level bindings. Much of the libdbus API is only useful for binding implementation. @@ -77,7 +77,7 @@ - If you just want to use D-BUS and don't care how it works, jump directly + If you just want to use D-Bus and don't care how it works, jump directly to . Otherwise, read on. @@ -115,7 +115,7 @@ - D-BUS applications + D-Bus applications There are many, many technologies in the world that have "Inter-process communication" or "networking" in their stated purpose: Internet Communications Engine (ICE), and probably hundreds more. Each of these is tailored for particular kinds of application. - D-BUS is designed for two specific cases: + D-Bus is designed for two specific cases: @@ -151,9 +151,9 @@ For the within-desktop-session use case, the GNOME and KDE desktops have significant previous experience with different IPC solutions - such as CORBA and DCOP. D-BUS is built on that experience and + such as CORBA and DCOP. D-Bus is built on that experience and carefully tailored to meet the needs of these desktop projects - in particular. D-BUS may or may not be appropriate for other + in particular. D-Bus may or may not be appropriate for other applications; the FAQ has some comparisons to other IPC systems. @@ -186,7 +186,7 @@ - D-BUS may happen to be useful for purposes other than the one it was + D-Bus may happen to be useful for purposes other than the one it was designed for. Its general properties that distinguish it from other forms of IPC are: @@ -233,7 +233,7 @@ Concepts Some basic concepts apply no matter what application framework you're - using to write a D-BUS application. The exact code you write will be + using to write a D-Bus application. The exact code you write will be different for GLib vs. Qt vs. Python applications, however. @@ -246,10 +246,10 @@ Objects and Object Paths - Each application using D-BUS contains objects, + Each application using D-Bus contains objects, which generally map to GObject, QObject, C++ objects, or Python objects (but need not). An object is an instance rather - than a type. When messages are received over a D-BUS connection, they + than a type. When messages are received over a D-Bus connection, they are sent to a specific object, not to the application as a whole. @@ -261,7 +261,7 @@ application, and thus can't be passed from one application to another. - To solve this, D-BUS introduces a name for each object. The name + To solve this, D-Bus introduces a name for each object. The name looks like a filesystem path, for example an object could be named /org/kde/kspread/sheets/3/cells/4/5. Human-readable paths are nice, but you are free to create an @@ -289,7 +289,7 @@ Message Types - Messages are not all the same; in particular, D-BUS has + Messages are not all the same; in particular, D-Bus has 4 built-in message types: @@ -331,7 +331,7 @@ Object paths, interfaces, and messages exist on the level of - libdbus and the D-BUS protocol; they are used even in the + libdbus and the D-Bus protocol; they are used even in the 1-to-1 case with no message bus involved. @@ -395,7 +395,7 @@ Addresses - Applications using D-BUS are either servers or clients. A server + Applications using D-Bus are either servers or clients. A server listens for incoming connections; a client connects to a server. Once the connection is established, it is a symmetric flow of messages; the client-server distinction only matters when setting up the @@ -403,17 +403,17 @@ - A D-BUS address specifies where a server will + A D-Bus address specifies where a server will listen, and where a client will connect. For example, the address unix:path=/tmp/abcdef specifies that the server will listen on a UNIX domain socket at the path /tmp/abcdef and the client will connect to that socket. An address can also specify TCP/IP sockets, or any other - transport defined in future iterations of the D-BUS specification. + transport defined in future iterations of the D-Bus specification. - When using D-BUS with a message bus, the bus daemon is a server + When using D-Bus with a message bus, the bus daemon is a server and all other applications are clients of the bus daemon. libdbus automatically discovers the address of the per-session bus daemon by reading an environment variable. It discovers the @@ -422,7 +422,7 @@ - If you're using D-BUS without a bus daemon, it's up to you to + If you're using D-Bus without a bus daemon, it's up to you to define which application will be the server and which will be the client, and specify a mechanism for them to agree on the server's address. @@ -450,7 +450,7 @@ The interface is also optional, primarily for historical reasons; DCOP does not require specifying the interface, instead simply forbidding duplicate method names - on the same object instance. D-BUS will thus let you + on the same object instance. D-Bus will thus let you omit the interface, but if your method name is ambiguous it is undefined which method will be invoked. @@ -468,11 +468,11 @@ - D-BUS - GLib type mappings + D-Bus - GLib type mappings - The heart of the GLib bindings for D-BUS is the mapping it - provides between D-BUS "type signatures" and GLib types - (GType). The D-BUS type system is composed of + The heart of the GLib bindings for D-Bus is the mapping it + provides between D-Bus "type signatures" and GLib types + (GType). The D-Bus type system is composed of a number of "basic" types, along with several "container" types. @@ -484,7 +484,7 @@ - D-BUS basic type + D-Bus basic type GType Free function Notes @@ -556,9 +556,9 @@ Container type mappings - The D-BUS type system also has a number of "container" + The D-Bus type system also has a number of "container" types, such as DBUS_TYPE_ARRAY and - DBUS_TYPE_STRUCT. The D-BUS type system + DBUS_TYPE_STRUCT. The D-Bus type system is fully recursive, so one can for example have an array of array of strings (i.e. type signature aas). @@ -574,13 +574,13 @@ "natural". - First, D-BUS type signatures which have an "obvious" + First, D-Bus type signatures which have an "obvious" corresponding built-in GLib type are mapped using that type: - D-BUS type signature + D-Bus type signature Description GType C typedef @@ -618,15 +618,15 @@ contained type. Why we need this we will see below. - The approach taken is to create these types in the D-BUS GLib - bindings; however, there is nothing D-BUS specific about them. + The approach taken is to create these types in the D-Bus GLib + bindings; however, there is nothing D-Bus specific about them. In the future, we hope to include such "fundamental" types in GLib itself. - D-BUS type signature + D-Bus type signature Description GType C typedef @@ -696,7 +696,7 @@ - D-BUS also includes a special type DBUS_TYPE_DICT_ENTRY which + D-Bus also includes a special type DBUS_TYPE_DICT_ENTRY which is only valid in arrays. It's intended to be mapped to a "dictionary" type by bindings. The obvious GLib mapping here is GHashTable. Again, however, there is no builtin GType for a GHashTable. @@ -710,7 +710,7 @@ - D-BUS type signature + D-Bus type signature Description GType C typedef @@ -735,7 +735,7 @@ Arbitrarily recursive type mappings - Finally, it is possible users will want to write or invoke D-BUS + Finally, it is possible users will want to write or invoke D-Bus methods which have arbitrarily complex type signatures not directly supported by these bindings. For this case, we have a DBusGValue which acts as a kind of special @@ -750,7 +750,7 @@ A sample program - Here is a D-BUS program using the GLib bindings. + Here is a D-Bus program using the GLib bindings. int main (int argc, char **argv) @@ -872,9 +872,9 @@ main (int argc, char **argv) - An internal D-BUS error, such as an out-of-memory + An internal D-Bus error, such as an out-of-memory condition, an I/O error, or a network timeout. Errors - generated by the D-BUS library itself have the domain + generated by the D-Bus library itself have the domain DBUS_GERROR, and a corresponding code such as DBUS_GERROR_NO_MEMORY. It will not be typical for applications to handle these errors @@ -883,8 +883,8 @@ main (int argc, char **argv) - A remote D-BUS exception, thrown by the peer, bus, or - service. D-BUS remote exceptions have both a textual + A remote D-Bus exception, thrown by the peer, bus, or + service. D-Bus remote exceptions have both a textual "name" and a "message". The GLib bindings store this information in the GError, but some special rules apply. @@ -1149,7 +1149,7 @@ typedef void GLib API: Implementing Objects - At the moment, to expose a GObject via D-BUS, you must + At the moment, to expose a GObject via D-Bus, you must write XML by hand which describes the methods exported by the object. In the future, this manual step will be obviated by the upcoming GLib introspection support. @@ -1178,7 +1178,7 @@ typedef void - This XML is in the same format as the D-BUS introspection XML + This XML is in the same format as the D-Bus introspection XML format. Except we must include an "annotation" which give the C symbols corresponding to the object implementation prefix (my_object). In addition, if particular @@ -1398,14 +1398,14 @@ my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error) Python API: Using Remote Objects - The Python bindings provide a simple to use interface for talking over D-BUS. - Where possible much of the inner-workings of D-BUS are hidden behind what looks + The Python bindings provide a simple to use interface for talking over D-Bus. + Where possible much of the inner-workings of D-Bus are hidden behind what looks like normal Python objects. - D-BUS - Python type mappings + D-Bus - Python type mappings - While python itself is a largely untyped language D-BUS provides a simple type system + While python itself is a largely untyped language D-Bus provides a simple type system for talking with other languages which may be strongly typed. Python for the most part tries automatically map python objects to types on the bus. It is none the less good to know what the type mappings are so one can better utilize services over the bus. @@ -1419,7 +1419,7 @@ my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error) - D-BUS basic type + D-Bus basic type Python wrapper Notes @@ -1478,21 +1478,21 @@ my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error) Container type mappings - The D-BUS type system also has a number of "container" + The D-Bus type system also has a number of "container" types, such as DBUS_TYPE_ARRAY and - DBUS_TYPE_STRUCT. The D-BUS type system + DBUS_TYPE_STRUCT. The D-Bus type system is fully recursive, so one can for example have an array of array of strings (i.e. type signature aas). - D-BUS container types have native corresponding built-in Python types + D-Bus container types have native corresponding built-in Python types so it is easy to use them. - D-BUS type + D-Bus type Python type Python wrapper Notes @@ -1505,7 +1505,7 @@ my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error) dbus.Array Python lists, denoted by square brackets [], are converted into arrays and visa versa. The one restriction is that when sending a Python list each element of the list must be of the same - type. This is because D-BUS arrays can contain only one element type. Use Python tuples for mixed types. + type. This is because D-Bus arrays can contain only one element type. Use Python tuples for mixed types. When using the wrapper you may also specify a type or signature of the elements contained in the Array. This is manditory when passing an empty Array to a method on the bus because Python can not guess at the @@ -1532,7 +1532,7 @@ my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error) DICTIONARY Python dictionary dbus.Dictionary - D-BUS doesn't have an explicit dictionary type. Instead it uses LISTS of DICT_ENTRIES to + D-Bus doesn't have an explicit dictionary type. Instead it uses LISTS of DICT_ENTRIES to represent a dictionary. A DICT_ENTRY is simply a two element struct containing a key/value pair. Python dictionaries are automatically converted to a LIST of DICT_ENTRIES and visa versa. @@ -1569,7 +1569,7 @@ my_object_increment_retval_error (MyObject *obj, gint32 x, GError **error) Invoking Methods - Here is a D-BUS program using the Python bindings to get a listing of all names on the session bus. + Here is a D-Bus program using the Python bindings to get a listing of all names on the session bus. import dbus @@ -1597,7 +1597,7 @@ proxy_obj.ListNames(dbus_interface = 'org.freedesktop.DBus') This is all fine and good if all you want to do is call methods on the bus and then exit. In order to do more complex things such as use a GUI or make asynchronous calls you will need a mainloop. You would use asynchronous calls because in GUI applications it is very bad to block for any long period of time. This cause - the GUI to seem to freeze. Since replies to D-BUS messages can take an indeterminate amount of time using async + the GUI to seem to freeze. Since replies to D-Bus messages can take an indeterminate amount of time using async calls allows you to return control to the GUI while you wait for the reply. This is exceedingly easy to do in Python. Here is an example using the GLib/GTK+ mainloop. @@ -1631,8 +1631,8 @@ mainloop.run() You will also notice that I check the version of the dbus bindings before importing dbus.glib. In older versions glib was the only available mainloop. As of version 0.41.0 we split out the glib dependency to allow for other mainloops - to be implemented. Notice also the python binding version does not match up with the D-BUS version. Once we reach 1.0 - this should change with Python changes simply tracking the D-BUS changes. + to be implemented. Notice also the python binding version does not match up with the D-Bus version. Once we reach 1.0 + this should change with Python changes simply tracking the D-Bus changes. While the glib mainloop is the only mainloop currently implemented, integrating other mainloops should be very easy to do. There are plans for creating a a generic mainloop to be the default for non gui programs. @@ -1747,7 +1747,7 @@ bus.add_signal_receiver(myname_changed, Version Alert - The Python D-BUS bindings require version 2.4 or greater of Python when creating D-BUS objects. + The Python D-Bus bindings require version 2.4 or greater of Python when creating D-Bus objects. @@ -1815,7 +1815,7 @@ mainloop.run() Notice the @ symbol on the line before the hello method. This is a new directive introduced in Python 2.4. It is called a decorator and it "decorates" methods. All you have to know is that it provides metadata that can then be used to alter the behavior of the method being decorated. - In this case we are telling the bindings that the hello method should be exported as a D-BUS method + In this case we are telling the bindings that the hello method should be exported as a D-Bus method over the bus. @@ -1900,7 +1900,7 @@ mainloop.run() Inheriting from HelloWorldObject - One of the cool things you can do in Python is inherit from another D-BUS object. We use this trick in + One of the cool things you can do in Python is inherit from another D-Bus object. We use this trick in the bindings to provide a default implementation for the org.freedesktop.DBus.Introspectable interface. Let's inherit from the HelloWorldObject example above and overide the hello method to say goodbye. @@ -1934,7 +1934,7 @@ print proxy_obj.hello(dbus_interface='org.freedesktop.HelloWorldGoodbyeIFace') Conclusion - As you can see, using D-BUS from Python is an extremely easy proposition. Hopefully + As you can see, using D-Bus from Python is an extremely easy proposition. Hopefully the tutorial has been helpful in getting you started. If you need anymore help please feel free to post on the mailing list. The Python bindings are still in a state of flux and there may be API changes in the future. diff --git a/doc/introspect.dtd b/doc/introspect.dtd index 15d913af..ba263d32 100644 --- a/doc/introspect.dtd +++ b/doc/introspect.dtd @@ -1,8 +1,8 @@ - - + - + -- cgit