Documentation/Maemo 5 Developer Guide/DBus/DBus Basics - Revision history

imported_>amigadave: /* Programming Directly with libdbus */ reformat image

2010-11-26T14:09:11Z

Programming Directly with libdbus: reformat image

← Older revision		Revision as of 14:09, 26 November 2010
Line 426:		Line 426:
	The error message (about <code>/dev/dsp</code>) printed to the same terminal where AF was started is normal behavior (in SDK). Displaying the Note dialog normally also causes an "Alert" sound to be played. The sound system has not been setup in the SDK, so the notification component complains about failing to open the sound device.		The error message (about <code>/dev/dsp</code>) printed to the same terminal where AF was started is normal behavior (in SDK). Displaying the Note dialog normally also causes an "Alert" sound to be played. The sound system has not been setup in the SDK, so the notification component complains about failing to open the sound device.

	[[Image:libdbus-example.png\|~~Image libdbus-example]]~~The friendly error message, using low-level D-Bus		[[Image:libdbus-example.png\|frame\|center\|alt=Screenshot of message ‘Hello World!’\|The friendly error message, using low-level D-Bus]]

	To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section [[Documentation/Maemo 5 Developer Guide/GNU Build System#GNU Make and Makefiles\|GNU Make and Makefiles]] in chapter [[Documentation/Maemo 5 Developer Guide/GNU Build System\|GNU Build System]], if necessary): [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/Makefile libdbus-example/Makefile]		To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section [[Documentation/Maemo 5 Developer Guide/GNU Build System#GNU Make and Makefiles\|GNU Make and Makefiles]] in chapter [[Documentation/Maemo 5 Developer Guide/GNU Build System\|GNU Build System]], if necessary): [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/Makefile libdbus-example/Makefile]

imported_>amigadave: /* Role of D-Bus in Maemo */ reformat image

2010-11-25T12:07:06Z

Role of D-Bus in Maemo: reformat image

← Older revision		Revision as of 12:07, 25 November 2010
Line 140:		Line 140:
	Assuming that the above command is run while the application framework is already running, the end result looks like this:		Assuming that the above command is run while the application framework is already running, the end result looks like this:

	[[Image:dbus-send-SystemNoteDialog.png\|~~Image dbus-send-SystemNoteDialog~~]]		[[Image:dbus-send-SystemNoteDialog.png\|frame\|center\|alt=Screenshot of Note dialog showing text ‘Hello, world!’\|System note dialog]]

	If the command is repeated multiple times, the notification service is capable of displaying only one dialog at a time. This makes sense because the dialog is modal. Furthermore, the method calls are queued, not lost; the notification service displays all of the requested dialogs. The service also acknowledges the RPC method call without delay (which is not always the obvious thing to do), giving a different return value each time (incrementing by one each time).		If the command is repeated multiple times, the notification service is capable of displaying only one dialog at a time. This makes sense because the dialog is modal. Furthermore, the method calls are queued, not lost; the notification service displays all of the requested dialogs. The service also acknowledges the RPC method call without delay (which is not always the obvious thing to do), giving a different return value each time (incrementing by one each time).

imported_>amigadave: /* Programming Directly with libdbus */ correct example links

2010-09-07T09:28:19Z

Programming Directly with libdbus: correct example links

← Older revision		Revision as of 09:28, 7 September 2010
Line 160:		Line 160:
	At this point, this example ignores the warnings, and uses the library to implement a simple program that replicates the earlier <code>dbus-send</code> example. To do this with the minimum amount of code, the code does not process (or expect) any responses to the method call. However, the code demonstrates the bare minimum function calls that are needed to send messages on the bus.		At this point, this example ignores the warnings, and uses the library to implement a simple program that replicates the earlier <code>dbus-send</code> example. To do this with the minimum amount of code, the code does not process (or expect) any responses to the method call. However, the code demonstrates the bare minimum function calls that are needed to send messages on the bus.

	The first step is to introduce the necessary header files. [~~http~~://~~dbus~~.~~freedesktop~~.org/~~doc~~/~~dbus~~/dbus-example.c libdbus-example/dbus-example.c]		The first step is to introduce the necessary header files. [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 177:		Line 177:
	Unlike the rest of the code in this material, the dbus example does not use GLib or other support libraries (other than libdbus). This explains why the example uses printf and other functions that are normally replaced with GLib equivalents.		Unlike the rest of the code in this material, the dbus example does not use GLib or other support libraries (other than libdbus). This explains why the example uses printf and other functions that are normally replaced with GLib equivalents.

	Connecting to the session bus yields a <code>DBusConnection</code> structure: [~~http~~://~~dbus~~.~~freedesktop~~.org/~~doc~~/~~dbus~~/dbus-example.c libdbus-example/dbus-example.c]		Connecting to the session bus yields a <code>DBusConnection</code> structure: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 217:		Line 217:
	Libdbus attempts to share the existing connection structures when the same process is connecting to the same bus. This is done to avoid the costly connection set-up time. Sharing connections is beneficial when the program is using libraries that would also open their own connections to the same buses.		Libdbus attempts to share the existing connection structures when the same process is connecting to the same bus. This is done to avoid the costly connection set-up time. Sharing connections is beneficial when the program is using libraries that would also open their own connections to the same buses.

	To communicate errors, libdbus uses <code>DBusError</code> structures, whose contents are simple. The dbus_error_init is used for guaranteeing that the error structure contains a non-error state before connecting to the bus. If there is an error, it is handled in <code>terminateOnError</code>: [~~http~~://~~dbus~~.~~freedesktop~~.org/~~doc~~/~~dbus~~/dbus-example.c libdbus-example/dbus-example.c]		To communicate errors, libdbus uses <code>DBusError</code> structures, whose contents are simple. The dbus_error_init is used for guaranteeing that the error structure contains a non-error state before connecting to the bus. If there is an error, it is handled in <code>terminateOnError</code>: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 256:		Line 256:
	</source>		</source>

	libdbus also contains some utility functions so that everything does not have to be coded manually. One such utility is <code>dbus_bus_name_has_owner</code>, that checks whether there is at least some process that owns the given well-known name at that moment: [~~http~~://~~dbus~~.~~freedesktop~~.org/~~doc~~/~~dbus~~/dbus-example.c libdbus-example/dbus-example.c]		libdbus also contains some utility functions so that everything does not have to be coded manually. One such utility is <code>dbus_bus_name_has_owner</code>, that checks whether there is at least some process that owns the given well-known name at that moment: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 288:		Line 288:
	</source>		</source>

	Creating a method call using libdbus is slightly more tedious than using the higher-level interfaces. The process is separated into two steps: creating a message structure, and appending the arguments to the message: [~~http~~://~~dbus~~.~~freedesktop~~.org/~~doc~~/~~dbus~~/dbus-example.c libdbus-example/dbus-example.c]		Creating a method call using libdbus is slightly more tedious than using the higher-level interfaces. The process is separated into two steps: creating a message structure, and appending the arguments to the message: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 335:		Line 335:
	When arguments are appended to the message, their content is copied, and possibly converted into a format that is sent over the connection to the daemon. This process is called marshaling, and is a common feature to most RPC systems. The method call requires two parameters (as before), the first being the text to be displayed, and the second being the style of the icon to be used. Parameters passed to libdbus are always passed by address. This is different from the higher level libraries.		When arguments are appended to the message, their content is copied, and possibly converted into a format that is sent over the connection to the daemon. This process is called marshaling, and is a common feature to most RPC systems. The method call requires two parameters (as before), the first being the text to be displayed, and the second being the style of the icon to be used. Parameters passed to libdbus are always passed by address. This is different from the higher level libraries.

	The arguments are encoded, so that their type code is followed by the pointer where the marshaling functions can find the content. The argument list is terminated with <code>DBUS_TYPE_INVALID</code>, so that the function knows where the argument list ends (since the function prototype ends with an ellipsis, ...). [~~http~~://~~dbus~~.~~freedesktop~~.org/~~doc~~/~~dbus~~/dbus-example.c libdbus-example/dbus-example.c]		The arguments are encoded, so that their type code is followed by the pointer where the marshaling functions can find the content. The argument list is terminated with <code>DBUS_TYPE_INVALID</code>, so that the function knows where the argument list ends (since the function prototype ends with an ellipsis, ...). [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 350:		Line 350:
	Setting the no-reply-flag effectively tells the bus daemon that even if there is a reply coming back for this RPC method, it is not wanted. In this case, the daemon does not send a reply.		Setting the no-reply-flag effectively tells the bus daemon that even if there is a reply coming back for this RPC method, it is not wanted. In this case, the daemon does not send a reply.

	Once the message is fully constructed, it can be added to the sending queue of the program. Messages are not sent immediately by libdbus. Normally this allows the message queue to accumulate to more than one message, and all of the messages are sent at once to the daemon. This in turn cuts down the number of the necessary context switches. In this case, this message is the only message that the program ever sends, so the send queue is instructed to be flushed immediately, which in turn instructs the library to send all messages to the daemon without a delay: [~~http~~://~~dbus~~.~~freedesktop~~.org/~~doc~~/~~dbus~~/dbus-example.c libdbus-example/dbus-example.c]		Once the message is fully constructed, it can be added to the sending queue of the program. Messages are not sent immediately by libdbus. Normally this allows the message queue to accumulate to more than one message, and all of the messages are sent at once to the daemon. This in turn cuts down the number of the necessary context switches. In this case, this message is the only message that the program ever sends, so the send queue is instructed to be flushed immediately, which in turn instructs the library to send all messages to the daemon without a delay: [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 369:		Line 369:
	</source>		</source>

	After the message is sent, the reserved resources must be freed. Here, the first one to be freed is the message, and then the connection structure. [~~http~~://~~dbus~~.~~freedesktop~~.org/~~doc~~/~~dbus~~/dbus-example.c libdbus-example/dbus-example.c]		After the message is sent, the reserved resources must be freed. Here, the first one to be freed is the message, and then the connection structure. [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 428:		Line 428:
	[[Image:libdbus-example.png\|Image libdbus-example]]The friendly error message, using low-level D-Bus		[[Image:libdbus-example.png\|Image libdbus-example]]The friendly error message, using low-level D-Bus

	To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section [[Documentation/Maemo 5 Developer Guide/GNU Build System#GNU Make and Makefiles\|GNU Make and Makefiles]] in chapter [[Documentation/Maemo 5 Developer Guide/GNU Build System\|GNU Build System]], if necessary): libdbus-example/Makefile		To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section [[Documentation/Maemo 5 Developer Guide/GNU Build System#GNU Make and Makefiles\|GNU Make and Makefiles]] in chapter [[Documentation/Maemo 5 Developer Guide/GNU Build System\|GNU Build System]], if necessary): [https://vcs.maemo.org/svn/maemoexamples/trunk/libdbus-example/Makefile libdbus-example/Makefile]

	<source lang="make">		<source lang="make">

imported_>amigadave: add example links

2010-09-06T11:48:58Z

add example links

← Older revision		Revision as of 11:48, 6 September 2010
Line 32:		Line 32:
	In addition to the single system bus, a separate session bus for each desktop session can exist. Because all user applications in a Maemo-compatible device run with the same user ID, the device only has one session bus as well.		In addition to the single system bus, a separate session bus for each desktop session can exist. Because all user applications in a Maemo-compatible device run with the same user ID, the device only has one session bus as well.

	A bus exists in the system in the form of a ''bus daemon'', a process that specializes in passing messages from one process to another. The daemon also forwards notifications to all applications on the bus. At the lowest level, D-Bus only supports point-to-point communication, normally using the local domain sockets (AF_UNIX) between the application and the bus daemon. The point-to-point aspect of D-Bus is, however, abstracted by the bus daemon, which implements the addressing and message passing functionality. This means that applications do not need to care about which specific process receives each method call or notification.		A bus exists in the system in the form of a ''bus daemon'', a process that specializes in passing messages from one process to another. The daemon also forwards notifications to all applications on the bus. At the lowest level, D-Bus only supports point-to-point communication, normally using the local domain sockets (<code>AF_UNIX</code>) between the application and the bus daemon. The point-to-point aspect of D-Bus is, however, abstracted by the bus daemon, which implements the addressing and message passing functionality. This means that applications do not need to care about which specific process receives each method call or notification.

	According to the above-mentioned details, sending a message using D-Bus always involves the following steps (under normal conditions):		According to the above-mentioned details, sending a message using D-Bus always involves the following steps (under normal conditions):
Line 54:		Line 54:
	** Examples: <code>org.maemo.Alert</code> and <code>org.freedesktop.Notifications</code>.		** Examples: <code>org.maemo.Alert</code> and <code>org.freedesktop.Notifications</code>.
	* Each service can contain multiple different objects, each of which provides a different (or the same) service. In order to separate one object from another, ''object paths'' are used. A personal information manager (PIM) information store, for example, might include separate objects to manage the contact information and synchronization.		* Each service can contain multiple different objects, each of which provides a different (or the same) service. In order to separate one object from another, ''object paths'' are used. A personal information manager (PIM) information store, for example, might include separate objects to manage the contact information and synchronization.
	** Object paths look like file paths (elements separated with the '/' character).		** Object paths look like file paths (elements separated with the '<code>/</code>' character).
	** In D-Bus, "lazy binding" can also be made, so that a specific function in the recipient is called on all remote method calls, irrespective of the object paths in the calls. This allows the on-demand targeting of method calls, so that the user can remove a specific object in an address book service (using an object path similar to <code>/org/maemo/AddressBook/Contacts/ShortName</code>). Due to the limitations on characters that can be put into the object path, this is not recommended. A better way is to supply the ShortName as a method call argument instead (as a UTF-8 formatted string).		** In D-Bus, "lazy binding" can also be made, so that a specific function in the recipient is called on all remote method calls, irrespective of the object paths in the calls. This allows the on-demand targeting of method calls, so that the user can remove a specific object in an address book service (using an object path similar to <code>/org/maemo/AddressBook/Contacts/ShortName</code>). Due to the limitations on characters that can be put into the object path, this is not recommended. A better way is to supply the ShortName as a method call argument instead (as a UTF-8 formatted string).
	** The object path is usually formed using the same elements as in the well-known name, but replacing the dots with slashes, and appending a specific object name to the end. For example: <code>/org/maemo/Alert/Alerter</code>. This is the common convention, but it also solves a specific problem if a process could re-use an existing D-Bus connection without explicitly knowing about it (using a library that encapsulates D-Bus functionality). In such cases, using short names increases the risk of name-space collisions within that process.		** The object path is usually formed using the same elements as in the well-known name, but replacing the dots with slashes, and appending a specific object name to the end. For example: <code>/org/maemo/Alert/Alerter</code>. This is the common convention, but it also solves a specific problem if a process could re-use an existing D-Bus connection without explicitly knowing about it (using a library that encapsulates D-Bus functionality). In such cases, using short names increases the risk of name-space collisions within that process.
Line 128:		Line 128:

	<pre>		<pre>
	[sbox-DIABLO_X86: ~] > run-standalone.sh dbus-send --print-reply \		[sbox-DIABLO_X86: ~] > run-standalone.sh dbus-send --print-reply \
	--type=method_call --dest=org.freedesktop.Notifications \		--type=method_call --dest=org.freedesktop.Notifications \
	/org/freedesktop/Notifications org.freedesktop.Notifications.SystemNoteDialog \		/org/freedesktop/Notifications org.freedesktop.Notifications.SystemNoteDialog \
	string:'Hello, world!' uint32:0 string:'NAO OK!'		string:'Hello, world!' uint32:0 string:'NAO OK!'
	method return sender=:1.1 -> dest=:1.15		method return sender=:1.1 -> dest=:1.15
	uint32 4		uint32 4
	</pre>		</pre>

Line 160:		Line 160:
	At this point, this example ignores the warnings, and uses the library to implement a simple program that replicates the earlier <code>dbus-send</code> example. To do this with the minimum amount of code, the code does not process (or expect) any responses to the method call. However, the code demonstrates the bare minimum function calls that are needed to send messages on the bus.		At this point, this example ignores the warnings, and uses the library to implement a simple program that replicates the earlier <code>dbus-send</code> example. To do this with the minimum amount of code, the code does not process (or expect) any responses to the method call. However, the code demonstrates the bare minimum function calls that are needed to send messages on the bus.

	The first step is to introduce the necessary header files. libdbus-example/dbus-example.c		The first step is to introduce the necessary header files. [http://dbus.freedesktop.org/doc/dbus/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 177:		Line 177:
	Unlike the rest of the code in this material, the dbus example does not use GLib or other support libraries (other than libdbus). This explains why the example uses printf and other functions that are normally replaced with GLib equivalents.		Unlike the rest of the code in this material, the dbus example does not use GLib or other support libraries (other than libdbus). This explains why the example uses printf and other functions that are normally replaced with GLib equivalents.

	Connecting to the session bus yields a <code>DBusConnection</code> structure: libdbus-example/dbus-example.c		Connecting to the session bus yields a <code>DBusConnection</code> structure: [http://dbus.freedesktop.org/doc/dbus/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 217:		Line 217:
	Libdbus attempts to share the existing connection structures when the same process is connecting to the same bus. This is done to avoid the costly connection set-up time. Sharing connections is beneficial when the program is using libraries that would also open their own connections to the same buses.		Libdbus attempts to share the existing connection structures when the same process is connecting to the same bus. This is done to avoid the costly connection set-up time. Sharing connections is beneficial when the program is using libraries that would also open their own connections to the same buses.

	To communicate errors, libdbus uses <code>DBusError</code> structures, whose contents are simple. The dbus_error_init is used for guaranteeing that the error structure contains a non-error state before connecting to the bus. If there is an error, it is handled in <code>terminateOnError</code>: libdbus-example/dbus-example.c		To communicate errors, libdbus uses <code>DBusError</code> structures, whose contents are simple. The dbus_error_init is used for guaranteeing that the error structure contains a non-error state before connecting to the bus. If there is an error, it is handled in <code>terminateOnError</code>: [http://dbus.freedesktop.org/doc/dbus/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 256:		Line 256:
	</source>		</source>

	libdbus also contains some utility functions so that everything does not have to be coded manually. One such utility is <code>dbus_bus_name_has_owner</code>, that checks whether there is at least some process that owns the given well-known name at that moment: libdbus-example/dbus-example.c		libdbus also contains some utility functions so that everything does not have to be coded manually. One such utility is <code>dbus_bus_name_has_owner</code>, that checks whether there is at least some process that owns the given well-known name at that moment: [http://dbus.freedesktop.org/doc/dbus/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 288:		Line 288:
	</source>		</source>

	Creating a method call using libdbus is slightly more tedious than using the higher-level interfaces. The process is separated into two steps: creating a message structure, and appending the arguments to the message: libdbus-example/dbus-example.c		Creating a method call using libdbus is slightly more tedious than using the higher-level interfaces. The process is separated into two steps: creating a message structure, and appending the arguments to the message: [http://dbus.freedesktop.org/doc/dbus/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 335:		Line 335:
	When arguments are appended to the message, their content is copied, and possibly converted into a format that is sent over the connection to the daemon. This process is called marshaling, and is a common feature to most RPC systems. The method call requires two parameters (as before), the first being the text to be displayed, and the second being the style of the icon to be used. Parameters passed to libdbus are always passed by address. This is different from the higher level libraries.		When arguments are appended to the message, their content is copied, and possibly converted into a format that is sent over the connection to the daemon. This process is called marshaling, and is a common feature to most RPC systems. The method call requires two parameters (as before), the first being the text to be displayed, and the second being the style of the icon to be used. Parameters passed to libdbus are always passed by address. This is different from the higher level libraries.

	The arguments are encoded, so that their type code is followed by the pointer where the marshaling functions can find the content. The argument list is terminated with <code>DBUS_TYPE_INVALID</code>, so that the function knows where the argument list ends (since the function prototype ends with an ellipsis, ...). libdbus-example/dbus-example.c		The arguments are encoded, so that their type code is followed by the pointer where the marshaling functions can find the content. The argument list is terminated with <code>DBUS_TYPE_INVALID</code>, so that the function knows where the argument list ends (since the function prototype ends with an ellipsis, ...). [http://dbus.freedesktop.org/doc/dbus/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 350:		Line 350:
	Setting the no-reply-flag effectively tells the bus daemon that even if there is a reply coming back for this RPC method, it is not wanted. In this case, the daemon does not send a reply.		Setting the no-reply-flag effectively tells the bus daemon that even if there is a reply coming back for this RPC method, it is not wanted. In this case, the daemon does not send a reply.

	Once the message is fully constructed, it can be added to the sending queue of the program. Messages are not sent immediately by libdbus. Normally this allows the message queue to accumulate to more than one message, and all of the messages are sent at once to the daemon. This in turn cuts down the number of the necessary context switches. In this case, this message is the only message that the program ever sends, so the send queue is instructed to be flushed immediately, which in turn instructs the library to send all messages to the daemon without a delay: libdbus-example/dbus-example.c		Once the message is fully constructed, it can be added to the sending queue of the program. Messages are not sent immediately by libdbus. Normally this allows the message queue to accumulate to more than one message, and all of the messages are sent at once to the daemon. This in turn cuts down the number of the necessary context switches. In this case, this message is the only message that the program ever sends, so the send queue is instructed to be flushed immediately, which in turn instructs the library to send all messages to the daemon without a delay: [http://dbus.freedesktop.org/doc/dbus/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">
Line 369:		Line 369:
	</source>		</source>

	After the message is sent, the reserved resources must be freed. Here, the first one to be freed is the message, and then the connection structure. libdbus-example/dbus-example.c		After the message is sent, the reserved resources must be freed. Here, the first one to be freed is the message, and then the connection structure. [http://dbus.freedesktop.org/doc/dbus/dbus-example.c libdbus-example/dbus-example.c]

	<source lang="c">		<source lang="c">

imported_>amigadave: /* Programming Directly with libdbus */ use

2010-07-21T14:23:20Z

Programming Directly with libdbus: use <source>

Show changes

imported_>amigadave: /* Addressing and Names in D-Bus */ use

2010-07-21T14:09:16Z

Addressing and Names in D-Bus: use <source>

← Older revision		Revision as of 14:09, 21 July 2010
Line 67:		Line 67:
	Examples of all four components that are used for sending a simple message (a method call) in the [[Documentation/Maemo 5 Final SDK\|SDK]] can be found below:		Examples of all four components that are used for sending a simple message (a method call) in the [[Documentation/Maemo 5 Final SDK\|SDK]] can be found below:

	~~<tt><span>'''<span>~~<~~font color~~="~~#000080~~">~~<nowiki>~~#define~~</nowiki></font></span>'''</span>~~ SYSNOTE_NAME ~~<span><font color="#FF0000">~~"org.freedesktop.Notifications"~~</font></span>~~		<source lang="c">
	~~<span>'''<span><font color="#000080"><nowiki>~~#define~~</nowiki></font></span>'''</span>~~ SYSNOTE_OPATH ~~<span><font color="#FF0000">~~"/org/freedesktop/Notifications"~~</font></span>~~		#define SYSNOTE_NAME "org.freedesktop.Notifications"
	~~<span>'''<span><font color="#000080"><nowiki>~~#define~~</nowiki></font></span>'''</span>~~ SYSNOTE_IFACE ~~<span><font color="#FF0000">~~"org.freedesktop.Notifications"~~</font></span>~~		#define SYSNOTE_OPATH "/org/freedesktop/Notifications"
	~~<span>'''<span><font color="#000080"><nowiki>~~#define~~</nowiki></font></span>'''</span>~~ SYSNOTE_NOTE ~~<span><font color="#FF0000">~~"SystemNoteDialog"</~~font></span></tt~~>		#define SYSNOTE_IFACE "org.freedesktop.Notifications"
			#define SYSNOTE_NOTE "SystemNoteDialog"
			</source>

	When switching to the LibOSSO RPC functions (which encapsulate a lot of the D-Bus machinery), operations are still performed with all of the D-Bus naming components.		When switching to the LibOSSO RPC functions (which encapsulate a lot of the D-Bus machinery), operations are still performed with all of the D-Bus naming components.

imported_>amigadave: wikify slightly, use


2010-07-21T14:03:19Z
wikify slightly, use <code>
Show changes



imported_>amigadave: /* Programming Directly with Libdbus */ fix link
2010-04-12T09:26:26Z
Programming Directly with Libdbus:  fix link

				
				
				
				
				
				← Older revision
				Revision as of 09:26, 12 April 2010
				
Line 166:
Line 166:
The lowest level library to be used for D-Bus programming is libdbus. Using this library directly is discouraged, mostly because it contains a lot of specific code to integrate into various main-loop designs that the higher level language bindings use. The lowest level library to be used for D-Bus programming is libdbus. Using this library directly is discouraged, mostly because it contains a lot of specific code to integrate into various main-loop designs that the higher level language bindings use.



The libdbus API reference documentation [[/node19.html#maemoapi 52]] contains a helpful note: The [http://maemo.org/api_refs/5.0/5.0-final/dbus/api/ libdbus API reference] documentation contains a helpful note:



  <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>   <tt><span>''<span><font color="#9A1900">/**</font></span>''</span>



imported_>amigadave: /* Programming Directly with Libdbus */ fix some links
2010-04-12T09:21:03Z
Programming Directly with Libdbus:  fix some links

				
				
				
				
				
				← Older revision
				Revision as of 09:21, 12 April 2010
				
Line 431:
Line 431:
<div align="CENTER">[[Image:libdbus-example.png|Image libdbus-example]]</div><div align="CENTER"><font size="-1">The friendly error message, using low-level D-Bus</font></div> <div align="CENTER">[[Image:libdbus-example.png|Image libdbus-example]]</div><div align="CENTER"><font size="-1">The friendly error message, using low-level D-Bus</font></div>



To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section ''GNU Make and Makefiles'' [[/node5.html#sec:gnu_make_makefiles 4.2]] in chapter ''GNU Build System'', if necessary): libdbus-example/Makefile To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section [[Documentation/Maemo_5_Developer_Guide/GNU_Build_System#GNU_Make_and_Makefiles|GNU Make and Makefiles]] in chapter [[Documentation/Maemo 5 Developer Guide/GNU Build System|GNU Build System]], if necessary): libdbus-example/Makefile



  <tt><span>''<span><font color="#9A1900"><nowiki># Define a list of pkg-config packages we want to use</nowiki></font></span>''</span>   <tt><span>''<span><font color="#9A1900"><nowiki># Define a list of pkg-config packages we want to use</nowiki></font></span>''</span>



imported_>amigadave: fix some links
2010-04-12T08:56:47Z
fix some links

				
				
				
				
				
				← Older revision
				Revision as of 08:56, 12 April 2010
				
Line 1:
Line 1:
= D-Bus = = D-Bus =



For interprocess communications (IPC), [[Maemo]] relies heavily on [[D-Bus]]. D-Bus makes it possible for programs to export their programming interfaces, so that other processes can call them in a consistent manner, without having to define a custom IPC protocol. Using these exported [[API]]s is also language agnostic, which means that as long as a programming language supports D-Bus, it can also access the interfaces. For interprocess communications (IPC), [[Maemo]] relies heavily on [http://www.freedesktop.org/wiki/Software/dbus D-Bus]. D-Bus makes it possible for programs to export their programming interfaces, so that other processes can call them in a consistent manner, without having to define a custom IPC protocol. Using these exported APIs is also language agnostic, which means that as long as a programming language supports D-Bus, it can also access the interfaces.



A Maemo-specific library called ''[[libOSSO]]'' provides helpful wrappers for D-BUS communication. It also contains the required functionality for every Maemo application, and applications must be initialized using the library. With the library, applications can connect to listen to system hardware state messages, for example the "battery low" message. The library is also used for application state-saving and the auto-save functionality. Section ''LibOSSO Library'' [[/node7.html#sec:libosso_library 6.18.2]] of the chapter ''[[Application Development]]'' of [[Maemo Reference Manual]] provides a good introduction to libOSSO. A Maemo-specific library called [[../../Application Development/LibOSSO library|libOSSO]] provides helpful wrappers for D-BUS communication. It also contains the required functionality for every Maemo application, and applications must be initialized using the library. With the library, applications can connect to listen to system hardware state messages, for example the "battery low" message. The library is also used for application state-saving and the auto-save functionality. Section [[../../Application Development/LibOSSO library|LibOSSO Library]] of the chapter [[../../Application Development|Application Development]] of [[Documentation/Maemo 5 Developer Guide|Maemo Reference Manual]] provides a good introduction to libOSSO.



== Introduction == == Introduction ==



D-Bus (the D originally stood for "Desktop") is a relatively new interprocess communication (IPC) mechanism designed to be used as a unified middleware layer in free desktop environments. Example projects where D-Bus is used are [[GNOME]] and [[Hildon]]. Compared to other middleware layers for IPC, D-Bus lacks many of the more refined (and complicated) features, which makes it faster and simpler. D-Bus (the D originally stood for "Desktop") is a relatively new interprocess communication (IPC) mechanism designed to be used as a unified middleware layer in free desktop environments. Example projects where D-Bus is used are [http://www.gnome.org/ GNOME] and [[Hildon]]. Compared to other middleware layers for IPC, D-Bus lacks many of the more refined (and complicated) features, which makes it faster and simpler.



D-Bus does not directly compete with low-level IPC mechanisms, such as sockets, shared memory or message queues. Each of these mechanisms have their uses, which normally do not overlap the ones in D-Bus. Instead, D-Bus aims to provide higher level functionality, for example: D-Bus does not directly compete with low-level IPC mechanisms, such as sockets, shared memory or message queues. Each of these mechanisms have their uses, which normally do not overlap the ones in D-Bus. Instead, D-Bus aims to provide higher level functionality, for example:
Line 61:
Line 61:
** Examples: org.maemo.Alert and org.freedesktop.Notifications. ** Examples: org.maemo.Alert and org.freedesktop.Notifications.



* Each service can contain multiple different objects, each of which provides a different (or the same) service. In order to separate one object from another, ''object paths'' are used. A [[PIM]] information store, for example, might include separate objects to manage the contact information and synchronization. * Each service can contain multiple different objects, each of which provides a different (or the same) service. In order to separate one object from another, ''object paths'' are used. A personal information manager (PIM) information store, for example, might include separate objects to manage the contact information and synchronization.



** Object paths look like file paths (elements separated with the '/' character). ** Object paths look like file paths (elements separated with the '/' character).
Line 83:
Line 83:
* For more information, see the [http://www.freedesktop.org/wiki/IntroductionToDBus Introduction to D-Bus] page. * For more information, see the [http://www.freedesktop.org/wiki/IntroductionToDBus Introduction to D-Bus] page.



Examples of all four components that are used for sending a simple message (a method call) in the [[SDK]] can be found below: Examples of all four components that are used for sending a simple message (a method call) in the [[Documentation/Maemo 5 Final SDK|SDK]] can be found below:



  <tt><span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> SYSNOTE_NAME  <span><font color="#FF0000">"org.freedesktop.Notifications"</font></span>   <tt><span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> SYSNOTE_NAME  <span><font color="#FF0000">"org.freedesktop.Notifications"</font></span>

← Older revision		Revision as of 09:26, 12 April 2010
Line 166:		Line 166:
	The lowest level library to be used for D-Bus programming is libdbus. Using this library directly is discouraged, mostly because it contains a lot of specific code to integrate into various main-loop designs that the higher level language bindings use.		The lowest level library to be used for D-Bus programming is libdbus. Using this library directly is discouraged, mostly because it contains a lot of specific code to integrate into various main-loop designs that the higher level language bindings use.

	The libdbus API reference documentation ~~[[/node19.html#maemoapi 52]]~~ contains a helpful note:		The [http://maemo.org/api_refs/5.0/5.0-final/dbus/api/ libdbus API reference] documentation contains a helpful note:

	<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>		<tt><span>''<span><font color="#9A1900">/**</font></span>''</span>

← Older revision		Revision as of 09:21, 12 April 2010
Line 431:		Line 431:
	<div align="CENTER">[[Image:libdbus-example.png\|Image libdbus-example]]</div><div align="CENTER"><font size="-1">The friendly error message, using low-level D-Bus</font></div>		<div align="CENTER">[[Image:libdbus-example.png\|Image libdbus-example]]</div><div align="CENTER"><font size="-1">The friendly error message, using low-level D-Bus</font></div>

	To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section ''GNU Make and Makefiles~~'' [[/node5.html#sec:gnu_make_makefiles 4.2~~]] in chapter ''GNU Build System'', if necessary): libdbus-example/Makefile		To get libdbus integrated into makefiles, use pkg-config. One possible solution is presented below (see section [[Documentation/Maemo_5_Developer_Guide/GNU_Build_System#GNU_Make_and_Makefiles\|GNU Make and Makefiles]] in chapter [[Documentation/Maemo 5 Developer Guide/GNU Build System\|GNU Build System]], if necessary): libdbus-example/Makefile

	<tt><span>''<span><font color="#9A1900"><nowiki># Define a list of pkg-config packages we want to use</nowiki></font></span>''</span>		<tt><span>''<span><font color="#9A1900"><nowiki># Define a list of pkg-config packages we want to use</nowiki></font></span>''</span>

← Older revision		Revision as of 08:56, 12 April 2010
Line 1:		Line 1:
	= D-Bus =		= D-Bus =

	For interprocess communications (IPC), [[Maemo]] relies heavily on [[D-Bus]]. D-Bus makes it possible for programs to export their programming interfaces, so that other processes can call them in a consistent manner, without having to define a custom IPC protocol. Using these exported ~~[[API]]s~~ is also language agnostic, which means that as long as a programming language supports D-Bus, it can also access the interfaces.		For interprocess communications (IPC), [[Maemo]] relies heavily on [http://www.freedesktop.org/wiki/Software/dbus D-Bus]. D-Bus makes it possible for programs to export their programming interfaces, so that other processes can call them in a consistent manner, without having to define a custom IPC protocol. Using these exported APIs is also language agnostic, which means that as long as a programming language supports D-Bus, it can also access the interfaces.

	A Maemo-specific library called ''[[libOSSO]]'' provides helpful wrappers for D-BUS communication. It also contains the required functionality for every Maemo application, and applications must be initialized using the library. With the library, applications can connect to listen to system hardware state messages, for example the "battery low" message. The library is also used for application state-saving and the auto-save functionality. Section ~~''LibOSSO Library''~~ [[/~~node7~~.~~html#sec:libosso_library 6~~.~~18.2~~]] of the chapter ''[[Application Development]]'' of [[Maemo Reference Manual]] provides a good introduction to libOSSO.		A Maemo-specific library called [[../../Application Development/LibOSSO library\|libOSSO]] provides helpful wrappers for D-BUS communication. It also contains the required functionality for every Maemo application, and applications must be initialized using the library. With the library, applications can connect to listen to system hardware state messages, for example the "battery low" message. The library is also used for application state-saving and the auto-save functionality. Section [[../../Application Development/LibOSSO library\|LibOSSO Library]] of the chapter [[../../Application Development\|Application Development]] of [[Documentation/Maemo 5 Developer Guide\|Maemo Reference Manual]] provides a good introduction to libOSSO.

	== Introduction ==		== Introduction ==

	D-Bus (the D originally stood for "Desktop") is a relatively new interprocess communication (IPC) mechanism designed to be used as a unified middleware layer in free desktop environments. Example projects where D-Bus is used are [[GNOME]] and [[Hildon]]. Compared to other middleware layers for IPC, D-Bus lacks many of the more refined (and complicated) features, which makes it faster and simpler.		D-Bus (the D originally stood for "Desktop") is a relatively new interprocess communication (IPC) mechanism designed to be used as a unified middleware layer in free desktop environments. Example projects where D-Bus is used are [http://www.gnome.org/ GNOME] and [[Hildon]]. Compared to other middleware layers for IPC, D-Bus lacks many of the more refined (and complicated) features, which makes it faster and simpler.

	D-Bus does not directly compete with low-level IPC mechanisms, such as sockets, shared memory or message queues. Each of these mechanisms have their uses, which normally do not overlap the ones in D-Bus. Instead, D-Bus aims to provide higher level functionality, for example:		D-Bus does not directly compete with low-level IPC mechanisms, such as sockets, shared memory or message queues. Each of these mechanisms have their uses, which normally do not overlap the ones in D-Bus. Instead, D-Bus aims to provide higher level functionality, for example:
Line 61:		Line 61:
	** Examples: org.maemo.Alert and org.freedesktop.Notifications.		** Examples: org.maemo.Alert and org.freedesktop.Notifications.

	* Each service can contain multiple different objects, each of which provides a different (or the same) service. In order to separate one object from another, ''object paths'' are used. A [[PIM]] information store, for example, might include separate objects to manage the contact information and synchronization.		* Each service can contain multiple different objects, each of which provides a different (or the same) service. In order to separate one object from another, ''object paths'' are used. A personal information manager (PIM) information store, for example, might include separate objects to manage the contact information and synchronization.

	** Object paths look like file paths (elements separated with the '/' character).		** Object paths look like file paths (elements separated with the '/' character).
Line 83:		Line 83:
	* For more information, see the [http://www.freedesktop.org/wiki/IntroductionToDBus Introduction to D-Bus] page.		* For more information, see the [http://www.freedesktop.org/wiki/IntroductionToDBus Introduction to D-Bus] page.

	Examples of all four components that are used for sending a simple message (a method call) in the [[SDK]] can be found below:		Examples of all four components that are used for sending a simple message (a method call) in the [[Documentation/Maemo 5 Final SDK\|SDK]] can be found below:

	<tt><span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> SYSNOTE_NAME <span><font color="#FF0000">"org.freedesktop.Notifications"</font></span>		<tt><span>'''<span><font color="#000080"><nowiki>#define</nowiki></font></span>'''</span> SYSNOTE_NAME <span><font color="#FF0000">"org.freedesktop.Notifications"</font></span>