D-BUS 0.30 in my yum repository - porting guide attached

[John (J5) Palmieri]

I have D-BUS version 0.30 in my yum repository at 

[j5utopia]
name=J5's Experimental Project Utopia Repository
baseurl=http://people.redhat.com/johnp/redhat/experimental/utopia

You will have to --force --nodeps the packages for now until all the
packages are updated to use the new dbus.

Attached is a short porting guide.  Ask me if you have any more
complicated questions about the new API's.

Please patch your rpm's to reflect the new API. We will make the
switchover in a couple of weeks or whenever all the packages are done.
Send me the srpm's so I can add packages to the repository as they are
done.  Here is a list of packages in core that need to be updated:

gnome-volume-manager - me 
hal - davidz
NetworkManager - dcbw
NetworkManager-gnome - dcbw
desktop-printing - walters
cups - twaugh

I'm posting this to fedora-devel so that packagers outside of core can
consider themselves warned.  Massive API breakage for anything that uses
D-BUS is on the horizon as we move closer to 1.0.  The 0.30 series
should mark the biggest change moving to 1.0 and I don't expect anymore
API breakage other than the glib bindings in the future.  If there is
I'll let you know.

Thanks

-- 
John (J5) Palmieri
Associate Software Engineer
Desktop Group
Red Hat, Inc.
Blog: http://martianrock.com
-------------- next part --------------
C API Changes:
	- s/dbus_bus_acquire_service/dbus_bus_request_name
	- s/dbus_bus_activate_service/dbus_bus_start_service_by_name
	- s/dbus_bus_get_base_service/dbus_bus_get_unique_name
	- s/dbus_bus_service_exists/dbus_bus_name_has_owner
	- s/DBUS_ACTIVATION_REPLY_ACTIVATED/DBUS_START_REPLY_SUCCESS 
        - s/DBUS_ACTIVATION_REPLY_ALREADY_ACTIVE/DBUS_START_REPLY_ALREADY_RUNNING
	- s/DBUS_BUS_ACTIVATION/DBUS_BUS_STARTER
	- If you wish to append to an itterator you must now initalize it with dbus_message_iter_init_append

DBUS API Changes:
	* Methods
	- s/org.freedesktop.DBus.AquireService/org.freedesktop.DBus.RequestName
	- s/org.freedesktop.DBus.ListServices/org.freedesktop.DBus.ListNames
	- s/org.freedesktop.DBus.ServiceExists/org.freedesktop.DBus.NameHasOwner
	- s/org.freedesktop.DBus.ActivateService/org.freedesktop.DBus.StartServiceByName
	- s/org.freedesktop.DBus.GetServiceOwner/org.freedesktop.DBus.GetNameOwner
	* Signals
	- s/org.freedesktop.DBus.ServiceAcquired/org.freedesktop.DBus.NameAcquired
	- s/org.freedesktop.DBus.ServiceLost/org.freedesktop.DBus.NameLost
	- s/org.freedesktop.DBus.ServiceOwnerChanged/org.freedesktop.DBus.NameOwnerChanged


	
Changes to Defaults:
	- DBUS_HEADER_FLAG_AUTO_START - auto starting(activation) is on by default
	
Types: 
	* New
	- DBUS_TYPE_INT16       - 16bit integer
	- DBUS_TYPE_UINT16      - 16bit unsigned integer
	- DBUS_TYPE_DICT_ENTRY  - Dictionaries (array of key value pair structs)
	- DBUS_TYPE_SIGNATURE   - dbus type signature string
	- DBUS_TYPE_VARIENT     - a value that has its signature embeded
	- DBUS_TYPE_STRUCT      - an array of different types 

	* Removed
	- DBUS_TYPE_NIL
	- DBUS_TYPE_DICT
	- DBUS_TYPE_CUSTOM

Type Iterator Changes:

	- All specific type API's have been removed. Use dbus_message_get_basic
	instead. 
	Example:
		dbus_int32_t i;
		.
		.
		.
		/* i = dbus_message_iter_get_int32 (&iter); */
		dbus_message_iter_get_basic (&iter, &i);

	This goes for writting too.
	Example:
		dbus_int32_t i;
		i = 10
		.
		.
		.
		/* dbus_message_iter_append_int32 (&iter, i); */
		dbus_message_iter_append_basic (&iter, DBUS_TYPE_INT32, &i);

	- When appending to a message use dbus_message_iter_init_append to 
	get an iterator that can be written to.
	
	- Use dbus_message_iter_recurse to read values in a container type such
	as an array, varient, dict or struct.
	Example:
		int arg_type;
		DBusMessageIter main_iter;
		.
		.
		.
		arg_type = dbus_message_iter_get_arg_type (&main_iter);
		/* you should use a switch here */
		if (arg_type == DBUS_TYPE_ARRAY) 
		  {
		    DBusMessageIter array_iter;
		    /* assuming that we know the array is an array
		       of strings*/
		    gchar *item;

		    assert (dbus_message_iter_get_element_type (&main_iter) 
		             == DBUS_TYPE_STRING);

		    dbus_message_iter_recurse (&main_iter, &array_iter);

		    do {
		      const char *value;
		      char *str;
		      
		      dbus_message_iter_get_basic (&array_iter, &value);
		      str = g_strdup (value);
		      g_print ("The value of the array element is: %s\n", str);
		      g_free (str);

		    } while (dbus_message_iter_next(&array_iter));
		  }

	One may also use the convinience function for fixed length arrays:
	
	void 	
	dbus_message_iter_get_fixed_array (DBusMessageIter *iter, 
	                                   void *value, 
					   int *n_elements);

	- When appending container types to iterators use the 
	dbus_message_iter_open_container and it's complement
	dbus_message_iter_close_container.
	Example:
		DBusMessageIter main_iter, array_iter;
		int i;
		.
		.
		.
		/* open an array of strings container */
		arg_type = dbus_message_iter_open_container (&main_iter,
		                                  DBUS_TYPE_ARRAY,
		                                  DBUS_TYPE_STRING_TO_STRING, 
						  &array_iter);

		for (i = 0; i < 10; i++)
		{
		  gchar buffer[255];

		  g_sprintf (buffer, "Array element %i", i);
		  dbus_message_iter_append_basic (&array_iter, 
		                                  DBUS_TYPE_STRING,
		                                  &buffer);
		}
		
		dbus_message_iter_close_container (&main_iter, &array_iter);
	
	One may also use the convinience function for fixed length arrays:
	
	void 	
	dbus_message_iter_append_fixed_array (DBusMessageIter *iter,
	                                      int element_type,
	                                      void *value, 
				 	      int *n_elements);