diff options
| -rw-r--r-- | Zeitgeist/BlacklistClient.cs | 12 | ||||
| -rw-r--r-- | Zeitgeist/Client/IBlacklist.cs | 19 | ||||
| -rw-r--r-- | Zeitgeist/Client/ILog.cs | 157 | ||||
| -rw-r--r-- | Zeitgeist/DataSourceClient.cs | 4 | ||||
| -rw-r--r-- | Zeitgeist/Datamodel/DataSource.cs | 8 | ||||
| -rw-r--r-- | Zeitgeist/Datamodel/Event.cs | 6 | ||||
| -rw-r--r-- | Zeitgeist/LogClient.cs | 56 |
7 files changed, 218 insertions, 44 deletions
diff --git a/Zeitgeist/BlacklistClient.cs b/Zeitgeist/BlacklistClient.cs index 1facb52..db4f759 100644 --- a/Zeitgeist/BlacklistClient.cs +++ b/Zeitgeist/BlacklistClient.cs @@ -8,16 +8,18 @@ namespace Zeitgeist { /// <summary> /// The Zeitgeist engine maintains a list of event templates that is known as the blacklist. + /// </summary> + /// <remarks> /// When inserting events via LogClient.InsertEvents they will be checked against the blacklist templates /// and if they match they will not be inserted in the log, and any matching monitors will not be signalled. - /// </summary> + /// </remarks> public class BlacklistClient { /// <summary> /// Get the current blacklist templates. /// </summary> /// <returns> - /// A list of Blacklist Event templates <see cref="List<Event>"/> + /// A list of <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event>"/> Blacklist Event templates /// </returns> public static List<Event> GetBlacklist() { @@ -30,11 +32,13 @@ namespace Zeitgeist /// <summary> /// Set the blacklist to event_templates. + /// </summary> /// Events matching any these templates will be blocked from insertion into the log. /// It is still possible to find and look up events matching the blacklist which was inserted before the blacklist banned them. - /// </summary> + /// <remarks> + /// </remarks> /// <param name="eventTemplates"> - /// A List of Event templates <see cref="List<Event>"/> + /// A List of <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event>"/> Event templates /// </param> public static void SetBlacklist(List<Event> eventTemplates) { diff --git a/Zeitgeist/Client/IBlacklist.cs b/Zeitgeist/Client/IBlacklist.cs index ebfd343..e0d3dc3 100644 --- a/Zeitgeist/Client/IBlacklist.cs +++ b/Zeitgeist/Client/IBlacklist.cs @@ -4,11 +4,30 @@ using Zeitgeist; namespace Zeitgeist.Client { + /// <summary> + /// The Zeitgeist engine maintains a list of event templates that is known as the blacklist. + /// When inserting events via LogClient.InsertEvents they will be checked against the blacklist templates + /// and if they match they will not be inserted in the log, and any matching monitors will not be signalled. + /// </summary> [NDesk.DBus.Interface ("org.gnome.zeitgeist.Blacklist")] public interface IBlacklist { + /// <summary> + /// Get the current blacklist templates. + /// </summary> + /// <returns> + /// A list of Blacklist RawEvent templates <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.RawEvent>"/> + /// </returns> RawEvent[] GetBlacklist(); + /// <summary> + /// Set the blacklist to event_templates. + /// Events matching any these templates will be blocked from insertion into the log. + /// It is still possible to find and look up events matching the blacklist which was inserted before the blacklist banned them. + /// </summary> + /// <param name="event_templates"> + /// A List of RawEvent templates <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.RawEvent>"/> + /// </param> void SetBlacklist(RawEvent[] event_templates); } } diff --git a/Zeitgeist/Client/ILog.cs b/Zeitgeist/Client/ILog.cs index 7922624..f52426f 100644 --- a/Zeitgeist/Client/ILog.cs +++ b/Zeitgeist/Client/ILog.cs @@ -5,33 +5,178 @@ using NDesk.DBus; namespace Zeitgeist.Client { + /// <summary> + /// Primary interface to the Zeitgeist engine. + /// Used to update and query the log. + /// It also provides means to listen for events matching certain criteria. + /// All querying is heavily based around an “event template”-concept. + /// </summary> [NDesk.DBus.Interface ("org.gnome.zeitgeist.Log")] public interface ILog { - // Works + /// <summary> + /// Get full event data for a set of event IDs + /// Each event which is not found in the event log is represented by the null in the resulting List. + /// </summary> + /// <param name="eventIds"> + /// An array of event IDs. <see cref="T:System.UInt32[]"/> + /// </param> + /// <returns> + /// Full event data for all the requested IDs <see cref="T:Zeitgeist.Datamodel.RawEvent[]"/> + /// </returns> RawEvent[] GetEvents(UInt32[] eventIds); - + /// <summary> + /// Search for events matching a given set of templates and return the IDs of matching events. + /// Use GetEvents() passing in the returned IDs to look up the full event data. + /// The matching is done where unset fields in the templates are treated as wildcards. + /// If a template has more than one subject then events will match the template if any one of their subjects match any one of the subject templates. + /// The fields uri, interpretation, manifestation, origin, and mimetype can be prepended with an exclamation mark ‘!’ in order to negate the matching. + /// The fields uri, origin, and mimetype can be prepended with an asterisk ‘*’ in order to do truncated matching. + /// NOTE: + /// This method is intended for queries potentially returning a large result set. + /// It is especially useful in cases where only a portion of the results are to be displayed at the same time + /// (eg., by using paging or dynamic scrollbars), as by holding a list of IDs you keep a stable ordering + /// and you can ask for the details associated to them in batches, when you need them. + /// For queries yielding a small amount of results, or where you need the information about all results at once no matter how many of them there are, see FindEvents(). + /// </summary> + /// <param name="range"> + /// The TimeRange for the query <see cref="T:Zeitgeist.Datamodel.TimeRange"/> + /// </param> + /// <param name="eventTemplates"> + /// An array of event templates which the returned events should match at least one of. <see cref="T:Zeitgeist.Datamodel.RawEvent[]"/> + /// </param> + /// <param name="state"> + /// Whether the item is currently known to be available <see cref="T:Zeitgeist.Datamodel.StorageState"/> + /// </param> + /// <param name="maxEvents"> + /// Maximal amount of returned events <see cref="T:Zeitgeist.Datamodel.System.UInt32"/> + /// </param> + /// <param name="resType"> + /// The Order in which the result should be made available <see cref="T:Zeitgeist.Datamodel.ResultType"/> + /// </param> + /// <returns> + /// An array containing the IDs of all matching events, up to a maximum of num_events events. + /// Sorted and grouped as defined by the result_type parameter. <see cref="T:System.UInt32[]"/> + /// </returns> UInt32[] FindEventIds(TimeRange range, RawEvent[] eventTemplates, UInt32 state, UInt32 maxEvents, UInt32 resType); + /// <summary> + /// Get events matching a given set of templates. + /// The matching is done where unset fields in the templates are treated as wildcards. + /// If a template has more than one subject then events will match the template if any one of their subjects match any one of the subject templates. + /// The fields uri, interpretation, manifestation, origin, and mimetype can be prepended with an exclamation mark ‘!’ in order to negate the matching. + /// The fields uri, origin, and mimetype can be prepended with an asterisk ‘*’ in order to do truncated matching. + /// In case you need to do a query yielding a large (or unpredictable) result set and you only want to show some of the results at the same time (eg., by paging them), use FindEventIds(). + /// </summary> + /// <param name="range"> + /// The TimeRange for the query <see cref="T:Zeitgeist.Datamodel.TimeRange"/> + /// </param> + /// <param name="eventTemplates"> + /// An array of event templates which the returned events should match at least one of <see cref="T:Zeitgeist.Datamodel.RawEvent[]"/> + /// </param> + /// <param name="state"> + /// Whether the item is currently known to be available <see cref="T:Zeitgeist.Datamodel.StorageState"/> + /// </param> + /// <param name="maxEvents"> + /// Maximal amount of returned events <see cref="System.UInt32"/> + /// </param> + /// <param name="resType"> + /// The Order in which the result should be made available <see cref="T:Zeitgeist.Datamodel.ResultType"/> + /// </param> + /// <returns> + /// Full event data for all the requested IDs, up to a maximum of num_events events, sorted and grouped as defined by the result_type parameter. <see cref="T:Zeitgeist.Datamodel.RawEvent[]"/> + /// </returns> RawEvent[] FindEvents(TimeRange range, RawEvent[] eventTemplates, UInt32 state, UInt32 maxEvents, UInt32 resType); + /// <summary> + /// Warning: This API is EXPERIMENTAL and is not fully supported yet. + /// Get a list of URIs of subjects which frequently occur together with events matching event_templates within time_range. + /// The resulting URIs must occur as subjects of events matching result_event_templates and have storage state storage_state. + /// </summary> + /// <param name="range"> + /// The TimeRange for the query <see cref="T:Zeitgeist.Datamodel.TimeRange"/> + /// </param> + /// <param name="eventTemplates"> + /// An array of event templates which you want URIs that relate to. <see cref="T:Zeitgeist.Datamodel.RawEvent[]"/> + /// </param> + /// <param name="resultEventTemplates"> + /// An array of event templates which the returned URIs must occur as subjects of. <see cref="T:Zeitgeist.Datamodel.RawEvent[]"/> + /// </param> + /// <param name="state"> + /// Whether the item is currently known to be available <see cref="T:Zeitgeist.Datamodel.StorageState"/> + /// </param> + /// <param name="maxEvents"> + /// Maximal amount of returned events <see cref="System.UInt32"/> + /// </param> + /// <param name="resType"> + /// The Order in which the result should be made available <see cref="T:Zeitgeist.Datamodel.ResultType"/> + /// </param> + /// <returns> + /// A list of URIs matching the described criteria <see cref="T:System.String[]"/> + /// </returns> string[] FindRelatedUris(TimeRange range, RawEvent[] eventTemplates, RawEvent[] resultEventTemplates, UInt32 state, UInt32 maxEvents, UInt32 resType); - // Works + /// <summary> + /// Inserts events into the log. Returns an array containing the IDs of the inserted events + /// Each event which failed to be inserted into the log (either by being blocked or because of an error) will be represented by 0 in the resulting array. + /// One way events may end up being blocked is if they match any of the blacklist templates. + /// Any monitors with matching templates will get notified about the insertion. + /// Note that the monitors are notified after the events have been inserted. + /// </summary> + /// <param name="events"> + /// List of events to be inserted in the log <see cref="T:Zeitgeist.Datamodel.RawEvent[]"/> + /// </param> + /// <returns> + /// An array containing the event IDs of the inserted events. 0 as ID means failed to insert <see cref="T:System.UInt32[]"/> + /// </returns> UInt32[] InsertEvents(RawEvent[] events); + /// <summary> + /// Register a client side monitor object to receive callbacks when events matching time_range and event_templates are inserted or deleted. + /// </summary> + /// <param name="monitorPath"> + /// The path to be monitored <see cref="NDesk.DBus.ObjectPath"/> + /// </param> + /// <param name="range"> + /// The time range under which Monitored events must fall within <see cref="TimeRange"/> + /// </param> + /// <param name="eventTemplates"> + /// RawEvent templates that events must match in order to trigger the monitor <see cref="T:Zeitgeist.Datamodel.RawEvent[]"/> + /// </param> void InstallMonitor(ObjectPath monitorPath, TimeRange range, RawEvent[] eventTemplates); + /// <summary> + /// Remove a monitor installed with InstallMonitor() + /// </summary> + /// <param name="monitorPath"> + /// The path of the monitor to be removed <see cref="NDesk.DBus.ObjectPath"/> + /// </param> void RemoveMonitor(ObjectPath monitorPath); - // Works + /// <summary> + /// Delete a set of events from the log given their IDs + /// </summary> + /// <param name="eventIds"> + /// The eventId of the Events to be deleted <see cref="T:System.UInt32[]"/> + /// </param> + /// <returns> + /// The TimeRange <see cref="T:Zeitgeist.Datamodel.TimeRange"/> + /// </returns> TimeRange DeleteEvents(UInt32[] eventIds); - // Didn't try but should work. Cant invoke. Will delete everything + /// <summary> + /// Delete the log file and all its content + /// This method is used to delete the entire log file and all its content in one go. + /// To delete specific subsets use FindEventIds() combined with DeleteEvents(). + /// </summary> void DeleteLog(); - // Works + /// <summary> + /// Terminate the running Zeitgeist engine process; + /// use with caution, this action must only be triggered with the user’s explicit consent, + /// as it will affect all applications using Zeitgeist + /// </summary> void Quit(); } } diff --git a/Zeitgeist/DataSourceClient.cs b/Zeitgeist/DataSourceClient.cs index f1756e0..5318fbc 100644 --- a/Zeitgeist/DataSourceClient.cs +++ b/Zeitgeist/DataSourceClient.cs @@ -16,7 +16,7 @@ namespace Zeitgeist /// Get the list of known data-sources. /// </summary> /// <returns> - /// A list of DataSource <see cref="List<DataSource>"/> + /// A list of DataSource <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </returns> public static List<DataSource> GetDataSources() { @@ -50,7 +50,7 @@ namespace Zeitgeist /// Description of DataSource <see cref="System.String"/> /// </param> /// <param name="events"> - /// A list of Event templates <see cref="List<Event>"/> + /// A list of Event templates <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </param> /// <returns> /// true is successful, false otherwise <see cref="System.Boolean"/> diff --git a/Zeitgeist/Datamodel/DataSource.cs b/Zeitgeist/Datamodel/DataSource.cs index fe26866..ddbdd0f 100644 --- a/Zeitgeist/Datamodel/DataSource.cs +++ b/Zeitgeist/Datamodel/DataSource.cs @@ -102,13 +102,13 @@ namespace Zeitgeist.Datamodel /// <summary> /// Convert an object of type DataSource to RawDataSource /// </summary> - /// <param name="raw"> - /// An instance of DataSource <see cref="DataSource"/> + /// <param name="src"> + /// An instance of DataSource <see cref="Zeitgeist.Datamodel.DataSource"/> /// </param> /// <returns> - /// An instance of RawDataSource <see cref="RawDataSource"/> + /// An instance of RawDataSource <see cref="Zeitgeist.Datamodel.RawDataSource"/> /// </returns> - public static RawDataSource ToRaw(DataSource src) + public static RawDataSource ToRaw(DataSource src) { RawDataSource raw = new RawDataSource(); diff --git a/Zeitgeist/Datamodel/Event.cs b/Zeitgeist/Datamodel/Event.cs index 5339598..90fcd91 100644 --- a/Zeitgeist/Datamodel/Event.cs +++ b/Zeitgeist/Datamodel/Event.cs @@ -209,13 +209,13 @@ namespace Zeitgeist.Datamodel /// Create an Event and then use Event.GetRawEvent() /// </summary> /// <param name="metadata"> - /// The metadata string array <see cref="System.String[]"/> + /// The metadata string array <see cref="T:System.String[]"/> /// </param> /// <param name="subjects"> - /// The subject of this RawEvent <see cref="System.String[][]"/> + /// The subject of this RawEvent <see cref="T:System.String[][]"/> /// </param> /// <param name="payload"> - /// The payload associated with the RawEvent <see cref="System.Byte[]"/> + /// The payload associated with the RawEvent <see cref="T:System.Byte[]"/> /// </param> public RawEvent(string[] metadata, string[][] subjects, byte[] payload) { diff --git a/Zeitgeist/LogClient.cs b/Zeitgeist/LogClient.cs index bd74a17..44656c0 100644 --- a/Zeitgeist/LogClient.cs +++ b/Zeitgeist/LogClient.cs @@ -7,6 +7,12 @@ using System.Linq; namespace Zeitgeist { + /// <summary> + /// Primary interface to the Zeitgeist engine. + /// Used to update and query the log. + /// It also provides means to listen for events matching certain criteria. + /// All querying is heavily based around an “event template”-concept. + /// </summary> public class LogClient { #region Fetch, Insert and Delete Events @@ -16,10 +22,10 @@ namespace Zeitgeist /// Each event which is not found in the event log is represented by the null in the resulting List. /// </summary> /// <param name="eventIds"> - /// An array of event IDs. <see cref="List<System.UInt32>"/> + /// An array of event IDs. <see cref="T:System.Collection.Generic.List{System.UInt32}"/> /// </param> /// <returns> - /// Full event data for all the requested IDs <see cref="List<Event>"/> + /// Full event data for all the requested IDs <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </returns> public static List<Event> GetEvents(List<uint> eventIds) { @@ -39,10 +45,10 @@ namespace Zeitgeist /// Note that the monitors are notified after the events have been inserted. /// </summary> /// <param name="events"> - /// List of events to be inserted in the log <see cref="List<Event>"/> + /// List of events to be inserted in the log <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </param> /// <returns> - /// An array containing the event IDs of the inserted events. 0 as ID means failed to insert <see cref="List<System.UInt32>"/> + /// An array containing the event IDs of the inserted events. 0 as ID means failed to insert <see cref="T:System.Collection.Generic.List{System.UInt32}"/> /// </returns> public static List<uint> InsertEvents(List<Event> events) { @@ -60,10 +66,10 @@ namespace Zeitgeist /// Delete a set of events from the log given their IDs /// </summary> /// <param name="eventIds"> - /// The eventId of the Events to be deleted <see cref="List<System.UInt32>"/> + /// The eventId of the Events to be deleted <see cref="T:System.Collection.Generic.List{System.UInt32}"/> /// </param> /// <returns> - /// The TimeRange <see cref="TimeRange"/> + /// The TimeRange <see cref="T:Zeitgeist.Datamodel.TimeRange"/> /// </returns> public static TimeRange DeleteEvents(List<uint> eventIds) { @@ -92,23 +98,23 @@ namespace Zeitgeist /// For queries yielding a small amount of results, or where you need the information about all results at once no matter how many of them there are, see FindEvents(). /// </summary> /// <param name="range"> - /// The TimeRange for the query <see cref="TimeRange"/> + /// The TimeRange for the query <see cref="T:Zeitgeist.Datamodel.TimeRange"/> /// </param> /// <param name="eventTemplates"> - /// An array of event templates which the returned events should match at least one of. <see cref="List<Event>"/> + /// An array of event templates which the returned events should match at least one of. <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </param> /// <param name="state"> - /// Whether the item is currently known to be available <see cref="StorageState"/> + /// Whether the item is currently known to be available <see cref="T:Zeitgeist.Datamodel.StorageState"/> /// </param> /// <param name="maxEvents"> - /// Maximal amount of returned events <see cref="System.UInt32"/> + /// Maximal amount of returned events <see cref="T:Zeitgeist.Datamodel.System.UInt32"/> /// </param> /// <param name="resType"> - /// The Order in which the result should be made available <see cref="ResultType"/> + /// The Order in which the result should be made available <see cref="T:Zeitgeist.Datamodel.ResultType"/> /// </param> /// <returns> /// An array containing the IDs of all matching events, up to a maximum of num_events events. - /// Sorted and grouped as defined by the result_type parameter. <see cref="List<System.UInt32>"/> + /// Sorted and grouped as defined by the result_type parameter. <see cref="T:System.Collection.Generic.List{System.UInt32}"/> /// </returns> public static List<uint> FindEventIds(TimeRange range, List<Event> eventTemplates, StorageState state, uint maxEvents, ResultType resType) { @@ -131,22 +137,22 @@ namespace Zeitgeist /// In case you need to do a query yielding a large (or unpredictable) result set and you only want to show some of the results at the same time (eg., by paging them), use FindEventIds(). /// </summary> /// <param name="range"> - /// The TimeRange for the query <see cref="TimeRange"/> + /// The TimeRange for the query <see cref="T:Zeitgeist.Datamodel.TimeRange"/> /// </param> /// <param name="eventTemplates"> - /// An array of event templates which the returned events should match at least one of <see cref="List<Event>"/> + /// An array of event templates which the returned events should match at least one of <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </param> /// <param name="state"> - /// Whether the item is currently known to be available <see cref="StorageState"/> + /// Whether the item is currently known to be available <see cref="T:Zeitgeist.Datamodel.StorageState"/> /// </param> /// <param name="maxEvents"> /// Maximal amount of returned events <see cref="System.UInt32"/> /// </param> /// <param name="resType"> - /// The Order in which the result should be made available <see cref="ResultType"/> + /// The Order in which the result should be made available <see cref="T:Zeitgeist.Datamodel.ResultType"/> /// </param> /// <returns> - /// Full event data for all the requested IDs, up to a maximum of num_events events, sorted and grouped as defined by the result_type parameter. <see cref="List<Event>"/> + /// Full event data for all the requested IDs, up to a maximum of num_events events, sorted and grouped as defined by the result_type parameter. <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </returns> public static List<Event> FindEvents(TimeRange range, List<Event> eventTemplates, StorageState state, uint maxEvents, ResultType resType) { @@ -166,25 +172,25 @@ namespace Zeitgeist /// The resulting URIs must occur as subjects of events matching result_event_templates and have storage state storage_state. /// </summary> /// <param name="range"> - /// The TimeRange for the query <see cref="TimeRange"/> + /// The TimeRange for the query <see cref="T:Zeitgeist.Datamodel.TimeRange"/> /// </param> /// <param name="eventTemplates"> - /// An array of event templates which you want URIs that relate to. <see cref="List<Event>"/> + /// An array of event templates which you want URIs that relate to. <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </param> /// <param name="resultEventTemplates"> - /// An array of event templates which the returned URIs must occur as subjects of. <see cref="List<Event>"/> + /// An array of event templates which the returned URIs must occur as subjects of. <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </param> /// <param name="state"> - /// Whether the item is currently known to be available <see cref="StorageState"/> + /// Whether the item is currently known to be available <see cref="T:Zeitgeist.Datamodel.StorageState"/> /// </param> /// <param name="maxEvents"> /// Maximal amount of returned events <see cref="System.UInt32"/> /// </param> /// <param name="resType"> - /// The Order in which the result should be made available <see cref="ResultType"/> + /// The Order in which the result should be made available <see cref="T:Zeitgeist.Datamodel.ResultType"/> /// </param> /// <returns> - /// A list of URIs matching the described criteria <see cref="List<System.String>"/> + /// A list of URIs matching the described criteria <see cref="T:System.Collection.Generic.List{System.String}"/> /// </returns> public static List<string> FindRelatedUris(TimeRange range, List<Event> eventTemplates, List<Event> resultEventTemplates, StorageState state, uint maxEvents, ResultType resType) { @@ -210,10 +216,10 @@ namespace Zeitgeist /// The path to be monitored <see cref="System.String"/> /// </param> /// <param name="range"> - /// The time range under which Monitored events must fall within <see cref="TimeRange"/> + /// The time range under which Monitored events must fall within <see cref="T:Zeitgeist.Datamodel.TimeRange"/> /// </param> /// <param name="eventTemplates"> - /// Event templates that events must match in order to trigger the monitor <see cref="List<Event>"/> + /// Event templates that events must match in order to trigger the monitor <see cref="T:System.Collection.Generic.List{Zeitgeist.Datamodel.Event}"/> /// </param> public static void InstallMonitor(string monitorPath, TimeRange range, List<Event> eventTemplates) { |