/* TODO: check if the 'in' keyword is really required in front of every arg */ /* Notes on the conversion from python to WebIDL: - WebIDL does not have the notion of Iterator, so we use sequences instead. - in python, method arguments can be named, so an optional argument can be skipped while the following one is provided - as a rule, many attributes 'x' in the python implementation are doubled by a 'get_x' where 'x' raises an exception when unset, while 'get_x' returns None. For the sake of brevity, the WebIDL interfaces only declare the attribute. - a number of "shortcut" methods have not been translated, when their result can be achieved by combining other methods of this specification. - all attributs and properties related to TAL have not been translated; the TAL API should probably be described in a separate document. */ /* Notes on the distinction URI/URL : - we use the term URI to denote a stable global identifier for a resource ; - we use the term URL to denote a dereferenceable URI that was actually used to load the data representing the resource. Although they are usually the same, there are some situations when they may differ , for example: - the data has actually been retrieved from a mirror or a local copy, - the stable identifier is not dereferenceable (e.g. URN). If the URL and URI differ, the means to find the correct URL for a given URI is application dependant. */ module cinelab { typedef DOMString uri; typedef DOMString id; interface Package: WithMeta { /// The URL from which this package has been fetched. readonly attribute uri url; /// The URI identifying this package. attribute uri uri; /// the group of elements defined by this package readonly attribute Group own; /// the group of all elements accessible to this package (through links) readonly attribute Group all; /// save the package to disk (if its URL is in the file: scheme) void save(); /// save the package to disk (if its URL is in the file: scheme) void save_as(in uri url, in bool change_url); /** Return whether the package has an element with the given ID-ref and, if provided, the given type. NB: it is not specified how element types are represented. */ bool has_element(DOMString id, optional any type); /** Get the element with the given ID-ref or URI-ref. If the element does not exist, an exception is raised (see below) unless ``default`` is provided, in which case its value is returned. If 'id' contains a '#', it is assumed to be a URI-ref, else it is assumed to be an ID-ref. In both cases, all imported packages are searched for the element An exception is raised if the given id involves an nonexistant or unreachable link, or if the last item of the id-ref is not the id of an element in the corresponding package. */ getter Element get_element (in DOMString id, in optional any default); /** Get the element with the given uri-ref. If the element does not exist, an exception is raised (see below) unless ``default`` is provided, in which case its value is returned. An exception is raised if the given id involves an nonexistant or unreachable importn, or if the last item of the id-ref is not the id of an element in the corresponding package. */ Element get_element_by_uriref(in uri uriref, in optional any default); /* element creation */ /// creates a media element in this package Media create_media(in DOMString id, in uri url, in optional uri frame_of_reference); /// creates an annotation element in this package Annotation create_annotation(in DOMString id, in Media media, in int begin, in int end, in AnnotationType type, in DOMString mimetype, in optional Resource model, in optional uri content_url); /// creates a relation element in this package Relation create_relation(in DOMString id, in RelationType type, in optional DOMString mimetype, in optional Resource model, in optional uri content_url, in Annotation... members); /// creates a view element in this package View create_view(in DOMString id, in DOMString mimetype, in optional Resource model, in optional uri content_url); /// creates a resource element in this package Resource create_view(in DOMString id, in DOMString mimetype, in optional Resource model, in optional uri content_url); /// creates a relation element in this package List create_user_list(in DOMString id, in Element... items); /// creates a relation element in this package Schema create_schema(in DOMString id, in Element... items); /// creates a user tag element in this package Tag create_user_tag(in DOMString id); /// creates an annotation type element in this package AnnotationType create_annotation_type(in DOMString id); /// creates a relation type element in this package RelationType create_relation_type(in DOMString id); /// creates a resource element in this package Query create_query(in DOMString id, in DOMString mimetype, in optional Resource model, in optional uri content_url); /// creates a link element in this package Query create_link(in DOMString id, in Package p); /* tag management */ /// Associate the element to the tag on behalf of this package. void associate_user_tag(Element element, Tag tag); /// Dissociate the element from the tag on behalf of this package. void dissociate_user_tag(Element element, Tag tag); }; interface Element: WithMeta { /** The identifier of this elements in its package. If set, all known references to the element must be updated. An exception is raised if the element id is set to an id already in use in the package. */ attribute DOMString id; /// The package owning this element. readonly attribute Package owner; /// The URI-ref globally identifying this element. readonly attribute uri uriref; /// shortcuts to metadata attribute DOMString _creator; //dc:creator attribute DOMString contributor; //dc:contributor attribute DOMString created; //dc:created attribute DOMString modified; //dc:modified attribute DOMString title; //dc:title attribute DOMString description; //dc:description attribute DOMString seeAlso; //rdfs:seeAlso /** Deletes this element from its package. All known references to the elements must be deleted as well (tagging, lists, etc...). */ void delete(); /** Iter over the tags associated with this element in ``package``. If ``package`` is not set, the session variable ``package`` is used instead. If the latter is not set, a TypeError is raised. If ``inherited`` is set to False, the tags associated by imported packages of ``package`` will not be yielded. If a tag is unreachable, None is yielded. See also `iter_my_tag_ids`. */ sequence iter_my_user_tags(in optional Package package, in optional bool inherited); /** Iter over the id-refs of the user tags associated with this element in ``package``. If ``package`` is not set, the session variable ``package`` is used instead. If the latter is not set, an exception is raised. If ``inherited`` is set to False, the tags associated by linked packages of ``package`` will not be yielded. See also `iter_my_tags`. */ sequence iter_my_user_tag_ids(in optional Package package, in optional bool inherited); /** Iter over all the packages associating this element to ``tag``. If ``package`` is not set, the session variable ``package`` is used instead. If the latter is not set, an exception is raised. */ sequence iter_taggers(in Tag tag, in optional Package package); /** Is this element associated to ``tag`` by ``package``. If ``package`` is not set, the session variable ``package`` is used instead. If the latter is not set, an exception is raised. If ``inherited`` is set to False, only return True if ``package`` itself associates this element to ``tag``; else return True also if the association is inherited from an imported package. */ bool has_tag(in Tag tag, in optional Package package, in optional bool inherited); }; interface Media: Element { /// The URL from which the media can be fetched. attribute uri url; /// The URI identifying the frame of reference of the media. attribute uri frame_of_reference; /** The time-unit of this media if known, elde None. The unit is known if the frame of reference is in the default Advene namespace. */ readonly attribute DOMString unit; /** The time-origin of this media if known, else None. The origin is known if the frame of reference is in the default Advene namespace. */ readonly attribute DOMString origin; /// shortcuts to metadata attribute DOMString duration; //dc:extent attribute DOMString uri; //cam:uri }; interface Annotation: Element,WithContent { /// The annotation type of this annotation. attribute AnnotationType type; /// The media annotated by this annotation. attribute Media media; /// The id-ref of the media annotated by this annotation. readonly attribute DOMString media_id; /// The timecode when the annotation starts. attribute int begin; /// The timecode when the annotation finishes. attribute int end; /** The duration of this annotation. This property is a shortcut for ``self.end - self.begin``. Setting it will update self.end accordingly, leaving self.begin unmodified. return self._end - self._begin. This property will also be modified by setting self.begin or self.end, since each one of these properties leaves the other one unmodified when set. */ attribute int duration; // NB: the python implementation has a bunch of shortcut methods for // managing relations }; interface Relation: Element,Group,WithContent { /// The relation type of this relation. attribute RelationType type; getter Element __getitem__(in int index); setter void __setitem__(in int index, in Annotation e); deleter void __delitem__(in int index); /// insert a new member at the given index void insert(in int index, in Annotation member); /// append a new member at the end of the list void append(in Annotation member); /// extend this list with a sequence of annotations void extend(in sequence members); /// return the id-ref of the member at the given index DOMString get_member_id(in int member); }; interface View: Element,WithContent { /// the mimetype of the output of that view readonly attribute DOMString output_mimetype; /// apply this view to an object (Element or Package) and return the result DOMString apply_to(in any obj); }; interface Resource: Element,WithContent {}; interface Tag: Element { /** Iter over the elements associated with this tag in ``package``. If ``package`` is not provided, the ``package`` session variable is used. If the latter is unset, an exception is raised. If ``inherited`` is set to False, the elements associated by imported packages of ``package`` will not be yielded. If an element is unreachable, None is yielded. See also `iter_element_ids`. */ sequence iter_elements(in optional Package package, in optional bool inherited); /** Iter over the id-refs of the elements associated with this tag in ``package``. If ``package`` is not provided, the ``package`` session variable is used. If the latter is unset, an exception is raised. If ``inherited`` is set to False, the elements associated by imported packages of ``package`` will not be yielded. See also `iter_elements`. */ sequence iter_element_ids(in optional Package package, in optional bool inherited); /** Is this tag associated to ``element`` by ``package``. If ``package`` is not provided, the ``package`` session variable is used. If the latter is unset, an exception is raised. If ``inherited`` is set to False, only returns True if ``package`` itself associates this tag to ``element``; else returns True also if the association is inherited from an imported package. */ bool has_element(in optional Package package, in optional bool inherited); }; interface List: Element,Group { getter Element __getitem__(in int index); setter void __setitem__(in int index, in Element e); deleter void __delitem__(in int index); /// insert a new item at the given index void insert(in int index, in Element item); /// append a new item at the end of the list void append(in Element item); /// extend this list with a sequence of elements void extend(in sequence items); /// return the id-ref of the item at the given index DOMString get_item_id(in int index); }; interface Query: Element,WithContent { /// apply this query to an object (Element or Package) and return the result Element apply_to(in any obj); }; interface Link: Element,Group { /// The URL to which this link fetches the imported package. attribute uri url; /// The URI identifying the imported package. attribute uri uri; /// The package to which this link element links. readonly attribute Package package; /// shortcut to package.get_element getter Element get(in DOMString id, in optional any default); // NB: this interface also inherits the Group interface, // as a shortcut to ``this.package.own`` }; interface Type: Tag { /** Apply the element_constraint to the given element and returns the result. */ bool check_element(in Element e); /** Applies the element_constraint to all the elements in the given package (session.package) if None, and return the aggregated result. */ bool check_all(in Package p); /// shortcuts to metadata attribute DOMString representation; //cam:representation attribute DOMString color; //cam:color attribute DOMString element_color; //cam:element-color attribute View element_constraint; //cam:element-constraint // shortcuts to the properties of element_constraint attribute DOMString mimetype; }; interface AnnotationType: Type {}; interface RelationType: Type {}; interface Schema: List,Group {}; /* * The following are mixin interfaces used in the above "main" interfaces. */ interface WithMeta { /** Iter over all the metadata of this object. Yields (key, value) pairs, where the value is either a string or an element. If the element is unreachable, value is None. See also `iter_meta_ids`. NB: this file does not specify how the (key, value) pairs are represented. */ sequence iter_meta(); /** Iter over all the metadata of this object. Yields (key, value) pairs, where the value is a string with a special attribute ``is_id`` indicating if it represents the id-ref of an element. See also `iter_meta`. NB: this file does not specify how the (key, value) pairs are represented. */ sequence iter_meta_ids(); /** Return the metadata id (string or element) associated to the given key. The returned value is a string with a special attribute ``is_id`` indicating if it represents the id-ref of an element. If no metadata is associated to the given key, a KeyError is raised, unless ``default`` is provideded, in which case its value is returned instead. */ DOMString get_meta_id(in DOMString key, in optional any default); /** Set the metadata. ``val`` can either be an Element or a DOMString. If an element, it must be directly imported by the package of self, or an exception will be raised. */ void set_meta(in DOMString key, in any val); /** Delete the metadata. Note that if the given key is not in use, this will have no effect. */ void del_meta(in DOMString key); }; /** I provide functionality for elements with a content. Note that there are 4 kinds of contents: backend-stored contents: those contents have no URL, and are stored directly in the backend; their data can be modified through this class. external contents: they have a URL at which their data is stored; their data can not be modified through this class. packaged contents: they have a URL in the special ``packaged:`` scheme, meaning that their data is stored in the local filesystem (usually extracted from a zipped package); their data can be modified through this class. empty content: only authorized for relations; they are marked by the special mimetype "x-advene/none"; neither their model, URL nor data can be modified. It follows that content-related properties are not independant from one another. Property `content_mimetype` has higher priority, as it is used to decide whether the content is empty or not (hence whether the other properties can be set or not). Then `content_url` is used to decide between the three other kinds of content, in order to decide whether `content_data` can be set or not. See the documentation of each property for more detail. */ interface WithContent { /** The mimetype of this element's content. If set to "x-advene/none", the other properties are erased and become unsettable. Note that it is only possible for relations. */ attribute DOMString content_mimetype; /** This property holds the URL of the content, or an empty string. Its value determines whether the content is backend-stored, external or packaged. Note that setting a standard URL (i.e. not in the ``packaged:`` scheme) to a backend-stored or packaged URL will discard its data. On the other hand, changing from backend-store to packaged and vice-versa keeps the data. Finally, note that setting the URL to one in the ``packaged:`` model will automatically create a temporary directory and set the PACKAGED_ROOT metadata of the package to that directory. */ attribute uri content_url; /** This property holds the data of the content. It can be read whatever the kind of content (backend-stored, external or packaged). However, only backend-stored and packaged can have their data safely modified. Trying to set the data of an external content will raise a exception. Its `content_url` must first be set to the empty string or a ``packaged:`` URL. */ attribute any content_data; /** This property holds a data structure representing the content data. The type of the data structure depends on the content mimetype. An exception is raised at setting if the structure is invalid or if the `content_data` can not be set. */ attribute any content_parsed; /** The resource used as the model of the content of this element. null if that content has no model. If the model can not be retrieved, an exception is raised. */ attribute Resource content_model; /* TODO: not sure the following should be part of the interface */ /// Return a file-like object giving access to the content data. readonly attribute bool content_is_textual; /// Indicates whether the content can be handled as text. any get_content_as_synced_file(); /// Return the ID-ref of the content model. readonly attribute DOMString content_model_id; }; interface Group { /* In all iter_* method and count_* methods, optional parameters are used to filter the iterated elements based on their properties. The meta filter is not specified here; it is inteded to describe a set of (attribute, value) pairs to be found in the metadata of the elements. NB: count_* methods are provided in addition to iter_* methods, because the implementation may have an efficient way to retrieve the number of elements without having to actually enumerate them. */ sequence iter_medias(in optional any meta); sequence iter_annotation(in optional Media media, in optional int begin, in optional int begin_min, in optional int begin_max, in optional int end, in optional int end_min, in optional int end_max, in optional int at, in optional any meta); // ``at`` is used to keep only annotation including this instant sequence iter_relations(in optional Annotation member, in optional int position, in optional any meta); // ``position`` must be used in conjunction with ``member``; it only // looks for the given member at that position (starting at 0) sequence iter_user_list(in optional Element item, in optional int position, in optional any meta); // ``position`` must be used in conjunction with ``item``; it only // looks for the given item at that position (starting at 0) sequence iter_schemas(in optional Element item, in optional int position, in optional any meta); // ``position`` must be used in conjunction with ``item``; it only // looks for the given item at that position (starting at 0) sequence iter_user_tags(in optional any meta); sequence iter_annotation_types(in optional any meta); sequence iter_relation_types(in optional any meta); sequence iter_links(in optional uri url, in optional uri uri, in optional any meta); sequence iter_queries(in optional any meta); sequence iter_views(in optional any meta); sequence iter_resources(in optional any meta); int count_medias(in optional any meta); int count_annotation(in optional Media media, in optional int begin, in optional int begin_min, in optional int begin_max, in optional int end, in optional int end_min, in optional int end_max, in optional int at, in optional any meta); int count_relations(in optional Annotation member, in optional int position, in optional any meta); int count_user_lists(in optional Element item, in optional int position, in optional any meta); int count_schemas(in optional Element item, in optional int position, in optional any meta); int count_user_tags(in optional any meta); int count_annotation_types(in optional any meta); int count_relation_types(in optional any meta); int count_links(in optional uri url, in optional uri uri, in optional any meta); int count_queries(in optional any meta); int count_views(in optional any meta); int count_resources(in optional any meta); }; };