Soylent: Get and Set Fields API

[Travis Reitter]

I think I like this for the final, main function APIs:

static char*
soylent_get_contact_field(unsigned int spid,
                                SoylentContactField scf,
                                SoylentLocation loc,
                                unsigned int fieldPos);

/*
 * @returns int: number of bytes recorded
 */
unsigned int
soylent_set_contact_field(unsigned int spid,
                                SoylentContactField scf,
                                SoylentLocation loc,
                                unsigned int fieldPos,
                                void* fieldData
                                unsigned int dataSizeBytes);

where the parameters are:

spid: Soylent Person ID; the persistant ID for the person - the primary
key of the Evolution Data Server or Kabc database

scf: the particular data field of the person to get or set

loc: the location associated with the data field (and enum for Home,
Work, Mobile - note this is scalable for additional locations)

fieldPos: the position (ie, starts at 0) of this person-field-location
among what would otherwise be duplicates.

==========

Examples:

To set person 19284's primary (pos 0) work email address to
"badassmother4000@...":

char* addy = "badassmother4000@...";

soylent_set_contact_field(19284, SOYLENT_CONTACT_FIELD_EMAIL,
                                SOYLENT_LOC_WORK, 0,
                                addy, sizeof(addy));

Note: we'd copy the final argument, so the caller can pass a local
variable.

==========

This approach should be relatively easy to use, and scale much better
than the approach used by Evolution-Data-Server (where they have a
limited number of constants which incorporate position (eg,
E_CONTACT_ADDRESS_EMAIL1, ...2, etc)).

Of course, we'd still be limited by the backend (e-d-s, or kabc) (to a
certain extent - depending on whether we end up adding a data table of
our own - certainly no time soon, though), but this makes for a cleaner
interface, and if the backends ever get cleaned up, we're ready.

==========

Thoughts?

-Travis

_______________________________________________
galago-devel mailing list
galago-devel@...
http://lists.freedesktop.org/mailman/listinfo/galago-devel

[Christian Hammond]

On Thu, Jul 14, 2005 at 10:15:36PM -0700, Travis Reitter wrote:

> I think I like this for the final, main function APIs:
>
> static char*
> soylent_get_contact_field(unsigned int spid,
> SoylentContactField scf,
> SoylentLocation loc,
> unsigned int fieldPos);
>
> /*
>  * @returns int: number of bytes recorded
>  */
> unsigned int
> soylent_set_contact_field(unsigned int spid,
> SoylentContactField scf,
> SoylentLocation loc,
> unsigned int fieldPos,
> void* fieldData
> unsigned int dataSizeBytes);

<snip>

A couple comments on the above.

Rather than working with numeric IDs, we should be using an object
system. So:

unsigned int
soylent_person_set_contact_field(SoylentPerson *person, ......);

Also, the fact that we'd need to specify the data size means that
we're perhaps generalizing things too much, which could lead us to
trouble.

I've been jotting down notes on how I'd like to see this done. If you
like the idea, I'll put this all up on the wiki.

And here it is:


Proposed Design
===============

Introduction
------------

The whole API will be GObject-based, which gives us a nice signal and
property system, subclassing, and easy binding to several languages
through existing binding systems.


Object design
-------------

The main object of focus will be SoylentPerson. SoylentPerson is a
first-class object, providing an abstract interface to whatever
backend is in use. More on this later.

Rather than reinventing several wheels, the GObject property system
and signal system will be heavily used in SoylentPerson. Each property
of a person will be a GObject property. This allows for any program
that can introspect any GObject to get all the data about
SoylentPerson and lets us overcome several issues, such as needing to
re-implement marshalling.


Property generation
-------------------

As a lot of code is needed for each property, the whole property
support will be auto-generated from a perl script based on a data
file. The current format of that file that I have looks like this:

name {
    type: SoylentName *
}

nickname {
    type: string
}

emails {
    type: collection
    subtype: string
}

phones {
    type: collection
    subtype: string
}

ims {
    type: collection
    subtype: GalagoAccount *
}

And so on.

This file will be transformed into a .c and .h file that will be
compiled into the library. The type and subtype fields have some magic
values (string, boolean, integer, and collection). Anything
unrecognized is passed through (e.g., GalagoAccount *) and is assumed
to be a valid type.

Properties will be able to be marked as read-only. Otherwise, the
read-only/read-write state of the property will be dependent on the
backend. If a property is marked read-write in SoylentPerson, but the
backend only supports read-only, the read-only state takes precedence.
That is, both SoylentPerson and the backend must both specify
read-write for it to be read-write, otherwise it will be read-only.

The standard data types (string, integer, boolean) are fairly
self-explanatory. However, there is a special type called 'collection'
that should be described.

Collections
-----------

The collection data type represents a collection of data of type
'subtype.' This can be a collection of strings, a collection of
structs, etc. In code, this will be represented by a
SoylentCollection object. A SoylentCollection object maintains a list
of key, value pairs. The key is a human-readable label for the value,
and the value is of whatever type the collection holds. A list of
pairs can be retrieved from a collection, as can a list of labels
(keys) or list of values.

Signals can be attached to a collection to notify on any additions,
removals, or changes.

Many types of data will live in a collection. IM accounts, phone
numbers, and e-mails, to name a few.


Accessing Properties
--------------------

Properties can be accessed the standard GObject way. For example:

SoylentName *name;
SoylentCollection *phones;
char *nickname;

g_object_get(G_OBJECT(person),
             "name", &name,
             "phones", &phones,
             "nickname", &nickname,
             NULL);

g_free(nickname);
g_object_unref(name);
g_object_unref(phones);


or:


SoylentName *name = g_object_get_data(G_OBJECT(person), "name");


It's a fairly easy, standard API, with notifications on properties.
However, this could also be wrapped a bit more, in two ways (both of
which can be used). The first is a set of type-specific generic API
functions, such as:

SoylentName *name = soylent_person_get_struct(person, "name");
const char *soylent_person_get_string(person, "nickname");

and:

SoylentName *name = soylent_person_get_name(person);
const char *soylent_person_get_nickname(person);


The specific set of functions could be automatically created by the
generator script.


Property names won't actually have to be specified as literal strings.
The generator script will generate a set of #defines to map a constant
name to the literal string.


I'm tired, so that's all I'm writing up tonight :)

Christian

--
Christian Hammond         <>  The Galago Project
chipx86@...      <>  http://www.galago.info/
   Best file compression around:  "DEL *.*" = 100% compression


_______________________________________________
galago-devel mailing list
galago-devel@...
http://lists.freedesktop.org/mailman/listinfo/galago-devel

[Kalle Vahlman]

On 7/15/05, Christian Hammond <chipx86@...> wrote:
> Rather than working with numeric IDs, we should be using an object
> system.

YES please, I don't think people in general appreciate the value of
using object systems and so tend to do lots of unneccesary work. For
example, in my project I didn't make decent objects of my components,
just some structs that "were enough". It took me several weeks to make
it somewhat working and still it had some issues plus extending it was
a pain.

Then I did a smart move by throwing the structs away, making proper
objects and it took me half the time and work to make it work better
than it did before. And the system is easily extendable.

Plus you get the easy bindings.

[...]
> Collections
> -----------

These are also on the top of my list of Good Ideas(tm).

Again, in my project I'm using hashtables to pass argument data
(strings) through dbus and it's extendable to the end of the world
(=memory+swap) without breaking comaptibility. It doesn't work for all
things of  course.

But the collection scheme sounds very good IMO.

Well, actually, I liked the whole proposal :)

Is this on the wiki?

--
Kalle Vahlman, zuh@...
_______________________________________________
galago-devel mailing list
galago-devel@...
http://lists.freedesktop.org/mailman/listinfo/galago-devel

[Christian Hammond]

On Sat, Jul 16, 2005 at 11:53:14AM +0300, Kalle Vahlman wrote:

> On 7/15/05, Christian Hammond <chipx86@...> wrote:
> > Rather than working with numeric IDs, we should be using an object
> > system.
>
> YES please, I don't think people in general appreciate the value of
> using object systems and so tend to do lots of unneccesary work. For
> example, in my project I didn't make decent objects of my components,
> just some structs that "were enough". It took me several weeks to make
> it somewhat working and still it had some issues plus extending it was
> a pain.

Yeah, objects are definitely a plus. A lot of painful code can go away
when using a decent object system, and it often allows others to do
more with your code than you first expected.

> Then I did a smart move by throwing the structs away, making proper
> objects and it took me half the time and work to make it work better
> than it did before. And the system is easily extendable.
>
> Plus you get the easy bindings.

Yep.

> [...]
> > Collections
> > -----------
>
> These are also on the top of my list of Good Ideas(tm).
>
> Again, in my project I'm using hashtables to pass argument data
> (strings) through dbus and it's extendable to the end of the world
> (=memory+swap) without breaking comaptibility. It doesn't work for all
> things of  course.
>
> But the collection scheme sounds very good IMO.
>
> Well, actually, I liked the whole proposal :)
>
> Is this on the wiki?

Not yet. Need to hear from Travis first.

Christian
 
--
Christian Hammond         <>  The Galago Project
chipx86@...      <>  http://www.galago.info/
   Every 10 seconds, somewhere on this earth, there is a woman
   giving birth to a child. She must be found and stopped.


_______________________________________________
galago-devel mailing list
galago-devel@...
http://lists.freedesktop.org/mailman/listinfo/galago-devel

[Travis Reitter]

> A couple comments on the above.
>
> Rather than working with numeric IDs, we should be using an object
> system. So:

Ah. I misinterpreted our earlier discussion about only providing
accessors/mutators - of course you can do that with objects, too. That
works for me.

> unsigned int
> soylent_person_set_contact_field(SoylentPerson *person, ......);
>
> Also, the fact that we'd need to specify the data size means that
> we're perhaps generalizing things too much, which could lead us to
> trouble.

Yes - I was going to comment on that, but I figured it'd be obvious one
way or another.

> I've been jotting down notes on how I'd like to see this done. If you
> like the idea, I'll put this all up on the wiki.

<snip>

Definitely. The whole proposal sounds good.

Just for a little background - the last large amounts of code I've dealt
with has been embedded C and OS-level (Minix) - so I haven't touched OO
design for a while (got 3 courses in Java my freshman year). Perhaps
more significantly, I'm not (yet) familiar with GObjects, so just
correct me if I try to make anything too arcane. This is part of the
reason I put this off a little :)

I'll try to read up a little on Glib/GObjects.

-Travis

_______________________________________________
galago-devel mailing list
galago-devel@...
http://lists.freedesktop.org/mailman/listinfo/galago-devel

[Nicolas Trangez]

On Sat, 2005-07-16 at 16:35 -0700, Travis Reitter wrote:
> I'll try to read up a little on Glib/GObjects.

http://www.le-hacker.org/papers/gobject/ gives you everything you need.

Ikke
http://www.eikke.com

_______________________________________________
galago-devel mailing list
galago-devel@...
http://lists.freedesktop.org/mailman/listinfo/galago-devel