Superseded in favor of Log Based API.

Initial proposal

For an updated proposal taking general annotation handling into account see the bottom of the page.

The proposal is to change the FindEvents method to return a list containing

• a) a list of event dicts, and

• b) a dict of item dicts, as seen below (example from https://lists.launchpad.net/zeitgeist/msg00081.html, modified to eg. add "uri" to the events):

Sample return value:

(
  #EventInfo
  [
    {
      "timestamp": 1234567890,
      "uri": "zeitgeist://event/http://gnome.org/zeitgeist/schema/1.0/core#VisitEvent/%s/1234567890#85",
      "source": "http://gnome.org/zeitgeist/schema/1.0/core#UserActivity",
      "content": "http://gnome.org/zeitgeist/schema/1.0/core#VisitEvent",
      "subject": "http://www.youtube.com",
      "app": "firefox.desktop",
      "tags": 
        {
          "UserTags": [],
          "AutoTags": [],
          "ExpriringTags": ["Simpsons","LOL Catz"]
        },
      "bookmark": False
    },
    {
      "timestamp": 1234567899,
      "uri": "zeitgeist://event/http://gnome.org/zeitgeist/schema/1.0/core#VisitEvent/%s/1234567899#90",
      "source": "http://gnome.org/zeitgeist/schema/1.0/core#UserActivity",
      "content": "http://gnome.org/zeitgeist/schema/1.0/core#VisitEvent",
      "subject": "http://www.youtube.com",
      "app": "firefox.desktop",
      "tags": 
        {
          "UserTags": [],
          "AutoTags": [],
          "ExpriringTags": []
        },
      "bookmark": True
    },
    {
      "timestamp": 1234567999,
      "uri": "zeitgeist://event/http://gnome.org/zeitgeist/schema/1.0/core#VisitEvent/%s/1234567999#100",
      "source": "http://gnome.org/zeitgeist/schema/1.0/core#UserActivity",
      "content": "http://gnome.org/zeitgeist/schema/1.0/core#VisitEvent",
      "subject": "http://www.google.com/search?hl=en&client=firefox-a&rls=com.ubuntu:en-US:unofficial&hs=5K6&as_q=gnome+zeitgeist&as_epq=&as_oq=&as_eq=&num=10&lr=&as_filetype=&ft=i&as_sitesearch=&  as_qdr=m&as_rights=&as_occt=any&cr=&as_nlo=&as_nhi=&safe=images"
      "app": "firefox.desktop",
      "tags": 
        {
          "UserTags": ["Dinner"],
          "AutoTags": [],
          "ExpriringTags": []
        },
      "bookmark": False
    }
  ],

  #ItemInfo
  {
  "http://www.youtube.com": 
    {
      "content": http://gnome.org/zeitgeist/schema/1.0/core#WebHistory,
      "source": http://gnome.org/zeitgeist/schema/1.0/core#Internet,
      "origin":  http://youtube.com,
      "text": "Youtube - Broadcast Yourself",
      "mimetype": "text/html",
      "icon": "",
      "Tags": 
        {
          "UserTags": ["LOL Catz"],
          "AutoTags": [],
          "ExpriringTags": ["Simpsons"]
        },
      "Bookmark": True
    },
  "http://www.google.com/search?hl=en&client=firefox-a&rls=com.ubuntu:en-US:unofficial&hs=5K6&as_q=gnome+zeitgeist&as_epq=&as_oq=&as_eq=&num=10&lr=&as_filetype=&ft=i&as_sitesearch=&as_qdr=m&as_rights=&as_occt=any&cr=&as_nlo=&as_nhi=&safe=images":
    {
      "content": http://gnome.org/zeitgeist/schema/1.0/core#WebHistory
      "source": http://gnome.org/zeitgeist/schema/1.0/core#Internet
      "origin":  http://google.com
      "text": "Youtube - Broadcast Yourself"
      "mimetype": "text/html"
      "icon": "",
      "Tags": 
        {
          "UserTags": ["Simpsons"],
          "AutoTags": [],
          "ExpriringTags": ["LOL Catz"]
        },
      "Bookmark": True
    }
  }
)

Additional annotations (eg. comments) as well as more detailed information about the annotations already send out in FindEvents (eg., to know when an item got a particular tag, or when it was bookmarked) will be available using a new FindAnnotations function, with a syntax as follows:

FindAnnotations([{"subject": "http://www.youtube.com", 
                  "content": "http://freedesktop.org/standards/xesam/1.0/core#Tag",
                  "min_timestamp": 1234567899,
                  "max_timestamp": 1234567999}])

The "subject" filter can of course also take the URI of an event (eg. "zeitgeist://event/http://gnome.org/zeitgeist/schema/1.0/core#VisitEvent/%s/1234567999#100").

Updated Proposal With Annotations

Merged Proposal of Mikkel and Markus

Basic ideas:

• Harmonize data structures to use dicts keyed by uris for both items, events, and annotations

• We return a DBus struct with (event_dict,item_dict,annotation_dict) - various alternative methods can return only two of these three members

• Events have one actor and multiple subjects, actors are not confined to applications - we want to be able to track stuff like "when was tag X was assigned to Y"

Event list:

[   
    {
       "uri": "zeitgeist://event/2009-10-08T20:30:00.543#27"

       "actor": "application://firefox.desktop", 
       "subjects": ["http://uri/to/item1"],
       "annotations": [],
       "content": Content.VISITED_EVENT,
       "source":  Source.USER_ACTIVITY,
    },
    {
       "uri": "zeitgeist://event/2009-10-08T20:32:20.946#1",

       "actor": "application://gedit.desktop",
       "subjects": ["file:///stupid.txt"],
       "annotations": [],
       "content": Content.CREATE_EVENT,
       "source":  Source.USER_ACTIVITY,

    },    
    # Bookmark http://uri/to/item1 and file:///stupid.txt simultaneously
    {
       "uri": "zeitgeist://event/2009-10-08T20:32:45.467#1" 

       "actor": "http://annotation3",
       "subjects": ["http://uri/to/item1", "file:///stupid.txt"],
       "annotations": [],
       "content": Content.MODIFY_EVENT,
       "source":  Source.USER_ACTIVITY,
    }
 
]

Annotation dict:

  {
    "http://annotation1": {
        "content": Content.TAG,
        "sourse": Source.USER,
        "text": "random user tag",
    },
    "http://annotation2" {
        "content": Content.COMMENT,
        "source": Source.USER,
        "text": "I think this is stupid"
    },
    "http://annotation3" {
        "content": Content.BOOKMARK,
        "source": Source.ENGINE,
    }
  }

Items dict

  {
    "http://uri/to/item1": {
        "content": Content.IMAGE,
        "source": Source.SOMETHING,
        "annotations": ["http://annotation1", "http://annotation3"]
     },
     "file:///stupid.txt": {
        "content": Content.DOCUMENT,
        "source": Source.FILE,
        "annotations": ["http://annotation2", "http://annotation3"]
     },
     ...
  }