~zeitgeist-project/zeitgeist/ZeitgeistSharp

//
//  Core.cs
//  
//  Author:
//       Randal Barlow <email dot tehk at gmail dot com>
// 
//  Copyright (c) 2010 Randal Barlow
// 
//  This program is free software: you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation, either version 3 of the License, or
//  (at your option) any later version.
// 
//  This program is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//  GNU General Public License for more details.
// 
//  You should have received a copy of the GNU General Public License
//  along with this program.  If not, see <http://www.gnu.org/licenses/>.


using System;

namespace ZeitgeistSharp.DataModel
{
    /// <summary>
    /// The wire representation of a event that a dbus signature of asaasay
    /// It can be transformed into a <see cref="Event"/> using <example>new Event(someEventStruct)</example>
    /// </summary>
    public struct EventStruct {
        /// <summary>
        /// elements defining an event
        /// </summary>
        public string[] structure;
        /// <summary>
        /// each subject array contains elements defining a subjects values
        /// </summary>
        public string[][] subjects;
        /// <summary>
        /// Free form attachment for the event. Transfered over DBus as an array of bytes
        /// </summary>
        public byte[] payload;

        public bool IsEmpty ()
        {
            if (this.structure != null)
                return false;
            else if (this.subjects != null)
                return false;
            else if (this.payload != null)
                return false;
            return true;
        }

        /// <summary>
        /// Creates a new struct with empty string values for all fields.
        /// Used to generate wire representation of event templates
        /// </summary>
        /// <returns>
        /// A <see cref="EventStruct"/> with one empty subject and empty fields
        /// </returns>
        public static EventStruct NewEmptyStruct ()
        {
            EventStruct template = new EventStruct ();
            template.subjects = new string[][] { new string[] { "", "", "", "", "", "", "" } };
            template.payload = new byte[0];
            template.structure = new string[] { "", "", "", "", "", "" };
            return template;
        }

        /// <summary>
        /// Takes a key string and a value string and sets the correct parameter
        /// the EventStruct
        /// </summary>
        /// <param name="key">
        /// A <see cref="System.String"/> key which is one of these accepted keys
        ///
        /// <list type="bullet">
        /// <item><term>timestamp</term></item>
        /// <item><term>interpretaion</term></item>
        /// <item><term>manifestation</term></item>
        /// <item><term>actor</term></item>
        /// <item><term>subjects</term></item>
        /// <item><term>subject_uri</term></item>
        /// <item><term>subject_interpretation</term></item>
        /// <item><term>subject_manifestation</term></item>
        /// <item><term>subject_origin</term></item>
        /// <item><term>subject_mimetype</term></item>
        /// <item><term>subject_text</term></item>
        /// <item><term>subject_storage</term></item>
        /// </list>
        /// </param>
        /// <param name="val">
        /// A <see cref="System.String"/> which is places in the key elements position in the backing struct
        /// </param>
        public void SetValueFromKey (string key, string val)
        {
            switch (key) {
            case "id":
                this.structure[0] = val;
                break;
            case "timestamp":
                this.structure[1] = val;
                break;
            case "interpretation":
                this.structure[2] = val;
                break;
            case "manifestation":
                this.structure[3] = val;
                break;
            case "actor":
                this.structure[4] = val;
                break;
            case "subject_uri":
                this.subjects[0][0] = val;
                break;
            case "subject_interpretation":
                this.subjects[0][1] = val;
                break;
            case "subject_manifestation":
                this.subjects[0][2] = val;
                break;
            case "subject_origin":
                this.subjects[0][3] = val;
                break;
            case "subject_mimetype":
                this.subjects[0][4] = val;
                break;
            case "subject_title":
                this.subjects[0][5] = val;
                break;
            case "subject_storage":
                this.subjects[0][6] = val;
                break;
            }
        }

        /// <summary>
        /// Takes a number of arguments and calls <see cref="SetValueFromKey"/> for every key, value pair
        /// </summary>
        /// <param name="parameters">
        /// A <see cref="System.String[]"/> with even length where every pair of arguments represents a key and a value
        /// </param>
        /// <returns>
        /// A <see cref="EventStruct"/> with those new values
        /// </returns>
        public static EventStruct NewForValueParams (params string[] parameters)
        {
            if (parameters.Length % 2 != 0)
                throw new ArgumentException("The number or parameters must be even, representing key, value pairs");
            EventStruct template = NewEmptyStruct();
            for (int o = 0; o < parameters.Length; o+=2) {
                template.SetValueFromKey(parameters[o], parameters[o+1]);
            }
            return template;
        }
    }

    /// <summary>
    /// A convenient representation of a <see cref="EventStruct"/>, its wire representation
    /// can be retrieved for sending over DBus with <see cref="Event.GetStruct"/>
    /// </summary>
    public class Event
    {
        /// <summary>
        /// The backing storage structure for this event object. It can be accessed using <see cref="GetStruct"/>
        /// </summary>
        private EventStruct event_struct;

        /// <summary>
        /// The id of the event
        /// </summary>
        public UInt32 Id {
            get {
                return System.Convert.ToUInt32 (this.event_struct.structure[0]); }
            set { this.event_struct.structure[0] = System.Convert.ToString(value);}
        }
        /// <summary>
        /// The events id in milliseconds since epoch
        /// </summary>
        public string Timestamp {
            get { return this.event_struct.structure[1]; }
            set { this.event_struct.structure[1] = value;}
        }
        /// <summary>
        /// A string representing the interpretation uri of a event
        /// </summary>
        public string Interpretation {
            get { return this.event_struct.structure[2]; }
            set { this.event_struct.structure[2] = value; }
        }
        /// <summary>
        /// A string representing the manifestation uri of a event
        /// </summary>
        public string Manifestation {
            get { return this.event_struct.structure[3]; }
            set { this.event_struct.structure[3] = value; }
        }
        /// <summary>
        /// A events actor or acting application
        /// </summary>
        public string Actor {
            get { return this.event_struct.structure[4]; }
            set { this.event_struct.structure[4] = value; }
        }

        /// <summary>
        /// The subjects of this event
        /// </summary>
        public Subject[] Subjects;

        /// <summary>
        /// Free form attachment for the event. Transfered over DBus as an array of bytes
        /// </summary>
        public byte[] Payload {
            get { return this.event_struct.payload;}
            set {
                this.event_struct.payload = new byte[value.Length];
                Array.Copy(value, this.event_struct.payload, value.Length);
                }
        }

        /// <summary>
        /// Constructs a new event backed by a empty struct
        /// </summary>
        public Event ()
        {
            this.event_struct = EventStruct.NewEmptyStruct();
        }

        /// <summary>
        /// Constructs a event using the given <see cref="EventStruct"/>
        /// </summary>
        /// <param name="event_struct">
        /// A <see cref="EventStruct"/> which is used by the new events properties
        /// </param>
        public Event (EventStruct event_struct)
        {
            this.event_struct = event_struct;
            this.Subjects = new Subject[event_struct.subjects.Length];
            for (int i = 0; i < event_struct.subjects.Length; i++) {
                this.Subjects[i] = new Subject (event_struct.subjects[i]);
            }
        }

        /// <summary>
        /// Magically collects all an events fields and places them into a
        /// <see cref="EventStruct"/> to be sent over DBus
        /// </summary>
        /// <returns>
        /// A <see cref="EventStruct"/> which
        /// </returns>
        public EventStruct GetStruct ()
        {
            this.event_struct.subjects = new String[this.Subjects.Length][];
            for (int i = 0; i < this.Subjects.Length; i++) {
            this.event_struct.subjects[i] = this.Subjects[i].GetStruct();
            }
            return this.event_struct;
        }

        /// <summary>
        /// Takes a number of arguments and calls <see cref="EventStruct.SetValueFromKey"/> for every key, value pair
        /// </summary>
        /// <param name="parameters">
        /// A <see cref="System.String[]"/> with even length where every pair of arguments represents a key and a value
        /// </param>
        /// <returns>
        /// A <see cref="Event"/> set with the given values
        /// </returns>
        public static Event NewForValueParams (params string[] parameters)
        {
            EventStruct event_struct = EventStruct.NewForValueParams (parameters);
            Event new_event = new Event (event_struct);
            return new_event;
        }

        // Map Function to get the backing structs from multiple events
        /// <summary>
        /// Performs <see cref="GetStruct"/> for each element of a <see cref="Event[]"/>
        /// </summary>
        /// <param name="events">
        /// A <see cref="Event[]"/> whos backing structs will be gathered
        /// </param>
        /// <returns>
        /// A <see cref="EventStruct[]"/> for each element
        /// </returns>
        public static EventStruct[] GetStructForEach (Event[] events)
        {
            EventStruct[] structs = new EventStruct[events.Length];
            for (int i = 0; i < events.Length; i++) {
                structs[i] = events[i].GetStruct();
            }
            return structs;
        }

        /// <summary>
        /// Returns an event array that is the same size as the given wire event array.
        /// Making up the lack of a map function in c#. Though you could use Select instead.
        /// </summary>
        /// <param name="structs">
        /// A <see cref="EventStruct[]"/> of structs you would like to me turned into events
        /// </param>
        /// <returns>
        /// A <see cref="Event[]"/> of events matching the given struct
        /// </returns>
        public static Event[] GetEventsFromStructs (EventStruct[] structs)
        {
            Event[] events = new Event[structs.Length];

            for (int i = 0; i < structs.Length; i++) {
                events[i] = new Event (structs[i]);
            }
            return events;
        }
    }

    /// <summary>
    /// Represents a subject of an Event. This class is both used to represent
    /// actual subjects, but also create subject templates to match other subjects against.
    /// </summary>
    public class Subject
    {
        private string[] subject_struct;

        /// <summary>
        /// The Uri of the subject
        /// </summary>
        public string Uri {
            get { return this.subject_struct[0];}
            set { this.subject_struct[0] = value;}
        }
        /// <summary>
        /// The Interpretation Uri of the subject
        /// A Interpretation symbol can be retrieved using <example>SymbolCollection.InterpretationCollection.GetFromUri(subject.Interpretation)</example>
        /// </summary>
        public string Interpretation {
            get { return this.subject_struct[1]; }
            set { this.subject_struct[1] = value; }
        }
        /// <summary>
        /// The Manifestation Uri of the subject
        /// A Manifestation symbol can be retrieved using <example>SymbolCollection.ManifestationCollection.GetFromUri(subject.Manifestation)</example>
        /// </summary>
        public string Manifestation {
            get { return this.subject_struct[2]; }
            set { this.subject_struct[2] = value; }
        }
        /// <summary>
        /// Read/write property with the URI of the location where the subject resides or where it can be said to originate from
        /// </summary>
        public string Origin {
            get { return this.subject_struct[3]; }
            set { this.subject_struct[3] = value; }
        }
        /// <summary>
        /// The subjects mime-type
        /// </summary>
        public string Mimetype {
            get { return this.subject_struct[4]; }
            set { this.subject_struct[4] = value; }
        }
        /// <summary>
        /// The Text representation of the subject, like a file name
        /// </summary>
        public string Text {
            get { return this.subject_struct[5]; }
            set { this.subject_struct[5] = value; }
        }
        /// <summary>
        /// Read/write property with a string id of the storage medium where the subject is stored.
        /// Fx. the UUID of the disk partition or just the string inet for items requiring general connectivity to be available
        /// </summary>
        public string Storage {
            get { return this.subject_struct[6]; }
            set { this.subject_struct[6] = value; }
        }

        /// <summary>
        /// Represents a subject of an Event. This class is both used to represent actual subjects,
        /// but also create subject templates to match other subjects against.
        /// </summary>
        public Subject ()
        {
            this.subject_struct = new string[] { "", "", "", "", "", "", "" };
        }

        /// <summary>
        /// Creates a new Subject backed by a given array
        /// </summary>
        /// <param name="subject_struct">
        /// A <see cref="System.String[]"/> with a length of 7 where each element is used by a specific Property
        /// </param>
        public Subject (string[] subject_struct)
        {
            this.subject_struct = subject_struct;
        }
        /// <summary>
        /// Returns the array backing a subject
        /// </summary>
        /// <returns>
        /// A <see cref="System.String[]"/>
        /// </returns>
        public string[] GetStruct ()
        {
            return this.subject_struct;
        }
    }

}