Metadata API for Media Resources 1.0

4.1.1 Methods

createMediaResource

This operation instantiates an object of either AsyncMediaResource or SyncMediaResource interface. Further, it allows to set the specific media resource and metadata sources to which this API is applied.

Parameter	Type	Nullable	Optional	Description
mediaResource	DOMString	✘	✘	This attribute must set the specific media resource that should be processed by the API.
metadataSources	MetadataSource[]	✘	✔	This attribute should specify additional metadata sources.
mode	short	✘	✔	This attribute should specify the desired mode of operation. 1 for asynchronous and 2 for synchronous mode should be used. In the case the mode argument is omitted, and the implementation supports both modes, the asynchronous mode will be used.

No exceptions.

Return type: MediaResource

getSupportedModes

This operation is called to identify the implemented mode. The return codes should be as follows: 1 for asynchronous, 2 for synchronous and 3 for both modes.

No parameters.

No exceptions.

Return type: short

4.1.2 Examples in Javascript

Example for getSupportedModes:

ma = new MediaResource();
var mode = ma.getSupportedModes();

/** Resulting in:
 * { "supportedModes" : 3 }
 */

Example for createMediaResource:

metadataSources = new MetadataSource[2];
metadataSources[0] = new MetadataSource(
                         "http://www.w3.org/2008/WebVideo/Annotations/drafts/metadata_formats/DC_example1.xml","dc");
metadataSources[1] = new MetadataSource(
                         "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG","exif");

mediaResource = new MediaResource();

if (mediaResource.getSupportedModes() == 1 || mediaResource.getSupportedModes() == 3) {
    aSyncObject = mediaResource.createMediaResource(
                         "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG",
                         metadataSources, 1);
                             
} else if (mediaResource.getSupportedModes() == 2 || mediaResource.getSupportedModes() == 3)  {
    syncObject = mediaResource.createMediaResource(
                         "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG",
                         metadataSources, 2);
}

4.2.1 Methods

getMediaProperty

This operation allows retrieval of the value of a specific property, several or all properties in an asynchronous manner. The specific property is passed as an argument and a list of objects is returned that hold the values according to the requested property. These objects implement the MediaAnnotation interface, described in Section 4.4. Depending on the requested property, the returned objects implement a different subtypes (inheriting from the MediaAnnotation interface). For example, requesting "title" gives back an array of objects implementing the Title interface, requesting "creator" results in objects implementing the Creator interface and so on. These interfaces are described in Section 4.5. An example can be found here.

Parameter	Type	Nullable	Optional	Description
propertyNames	DOMString[]	✘	✘	This argument identifies an array containing the properties for which the values need to be retrieved. For an empty array all properties carrying values will be retrieved.
successCallback	PropertyCallback	✘	✘	This argument holds a callback object for asynchronous requests to the property. The successCallback object implements the PropertyCallback interface and holds a handleEvent operation that needs to be called once all data for the requested property is gathered. This handleEvent operation needs to be called with a new MediaAnnotation array.
errorCallback	ErrorCallback	✘	✘	This argument holds a callback object for failure of asynchronous requests to the property. The errorCallback object implements the ErrorCallback interface and holds a handleEvent operation that needs to be called if an attempt fails. This handleEvent operation needs to be called with a new DOMString representing the status code of the error (see Section 4.7 for details).
fragment	DOMString	✘	✔	This argument contains a URI identifying the specific media fragment for which the metadata is requested. The URI must conform to the URI for Media Fragment [MEDIA-FRAGMENTS] specification. This parameter is optional.
sourceFormat	DOMString	✘	✔	This argument identifies a specific metadata format. It should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]. If a metadata format is defined, only the metadata available in the specified metadata format are retrieved. This parameter is optional.
language	DOMString	✘	✔	This argument allows to identify the language of the metadata. Values for the metadata will only be returned if it is available in the specified language. Recommended best practice is to use BCP 47 [BCP47]. This parameter is optional.

No exceptions.

Return type: void

getOriginalMetadata

This operation allows retrieval of the original metadata according to the specified source format in an asynchronous manner. An example can be found here.

Parameter	Type	Nullable	Optional	Description
sourceFormat	DOMString	✘	✘	This argument identifies a specific metadata format. It should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]. If a metadata format is defined, only the metadata available in the specified metadata format are retrieved.
successCallback	MetadataCallback	✘	✘	This argument holds a callback object for asynchronous requests for the original metadata. The successCallback object implements the MetadataCallback interface and holds a handleEvent operation that needs to be called once all properties having values are listed. This handleEvent operation needs to be called with a new DOMString array holding the original metadata.
errorCallback	ErrorCallback	✘	✘	This argument holds a callback object for failure of asynchronous requests for the original metadata. The errorCallback object implements the ErrorCallback interface and holds a handleEvent operation that needs to be called if an attempt fails. This handleEvent operation needs to be called with a new DOMString representing the status code of the error (see Section 4.7 for details).

No exceptions.

Return type: void

4.2.2 Callback interfaces

interface PropertyCallback {
    void handleEvent (MediaAnnotation[] mediaAnnotations);
};

interface MetadataCallback {
    void handleEvent (DOMString[] metadata);
};

4.2.3 Examples in Javascript

Example for asynchronous getMediaProperty:

aSyncMediaResource = mediaResource.createMediaResource("http://www.imdb.com/title/tt0133152/", new Array(), 1);
aSyncMediaResource.getMediaProperty(["title"], successCallback, errorCallback, "", "", "");
                                
function successCallback(MediaAnnotation[] mediaAnnotations) {
    ...
}

/** Resulting in:
 * [ { "Title" : {
 *         "propertyName" : "title",
 *         "value" : "Planet of the apes",
 *         "language" : en-us",
 *         ...
 *         "statusCode" : 200
 *         }
 * },
 * { "Title" : {
 *         "propertyName" : "title",
 *         "value" : "Monkey Planet",
 *         "language" : en-us",
 *         ...,
 *         "statusCode" : 200
 *         }
 * },
 * { ...
 * } ]
 */
                
function errorCallback(DOMString error) {
    ...
}

/** Resulting in:
 * { error: { "statusCode" : 200 } }
 */

Example for asynchronous getOriginalMetadata :

aSyncMediaResource = mediaResource.createMediaResource(
                         "http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG",
                          new Array(), 1);
aSyncMediaResource.getOriginalMetadata("dc", successCallback, errorCallback);

function successCallback(DOMString[] metadata) {
    ...
}

/** Resulting in:
 * [ { "statusCode" : 200
 * },
 * {"originalMetadata" : "<metadata xmlns='http://example.org/myapp/'
 *                                        xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 *                                        xsi:schemaLocation='http://example.org/myapp/ http://example.org/myapp/schema.xsd'
 *                                        xmlns:dc='http://purl.org/dc/elements/1.1/'>
 *                                          <dc:title>DC title</dc:title>
 *                                  </metadata>"
 * } ]
 */

                                                
function errorCallback(DOMString error) {
   ...
}

/** Resulting in:
 * { error: { "statusCode" : 200 } }
 */

4.3.1 Methods

getMediaProperty

This operation allows retrieval of the metadata of a specific property, several or all properties in a synchronous manner. The passed array holds the requested properties and an array of objects is returned. If the array is empty, every property holding values will be requested and returned. The returned objects implement the MediaAnnotation interface (see Section 4.3). Depending on the requested property, the returned objects implement different subtypes (inheriting from the MediaAnnotation interface). For example, requesting "title" gives back an array of objects implementing the Title interface, requesting "creator" results in objects implementing the Creator interface and so on. These subtypes are described in Section 4.4. The operation returns a MediaAnnotation array holding the requested properties. If an error occurs during retrieval, a MediaAnnotation object with the corresponding status code (e.g., 400, 404 or 415) will be generated and inserted at the first position of the array. An example can be found here.

In this section the MediaAnnotations interface is used in the interface definitions. It serves as a container to hold general values about properties enabling an iteration over a set of different properties. Its explanation can be found in Section 4.4

Parameter	Type	Nullable	Optional	Description
propertyNames	DOMString[]	✘	✘	This argument holds the requested properties as an array. If the array is empty, each property holding values will be returned.
fragment	DOMString	✘	✔	This argument contains a URI identifying the specific media fragment for which the metadata is requested. The URI must conform to the URI for Media Fragment [MEDIA-FRAGMENTS] specification. This parameter is optional.
sourceFormat	DOMString	✘	✔	This argument identifies a specific metadata format. It should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]. If a metadata format is defined, only the metadata available in the specified metadata format is retrieved. This parameter is optional.
language	DOMString	✘	✔	This argument allows to identify the language of the metadata. Values for the metadata will only be returned if it is available in the specified language. Recommended best practice is to use BCP 47 [BCP47]. This parameter is optional.

No exceptions.

Return type: MediaAnnotation[]

getOriginalMetadata

This operation allows retrieval of the original metadata according to the specified source format in a synchronous manner. The operation returns a DOMString array holding the status code of the request at the first and the original metadata at the second position. An example can be found here.

Parameter	Type	Nullable	Optional	Description
sourceFormat	DOMString	✘	✘	This argument identifies a specific metadata format. It should use the metadata format identifiers defined in the Ontology for Media Resources 1.0 specification [MEDIA-ONTOLOGY]. If a metadata format is defined, only the metadata available in the specified metadata format is retrieved.

No exceptions.

Return type: DOMString[]

4.3.2 Examples in Javascript

The examples in this section use getMediaProperty() to get an object implementing the MediaAnnotation interface. The noErrorStatus function ensures that no error is present and the requested properties carry values.

We give some JavaScript examples on how to use the synchronous MediaResource interface and it's operations.

Example for synchronous getMediaProperty:

syncMediaResource = mediaResource.createMediaResource("http://www.imdb.com/title/tt0133152/",
                          new Array(), 2);
title = syncMediaResource.getMediaProperty(["title"], "", "", "");

if (noErrorStatus(title[0].statusCode) == true) {
   ...
}                                                

/** Resulting in:
 * [ { "Title" : {
 *         "propertyName" : "title",
 *         "value" : "Planet of the apes",
 *         "language" : en-us",
 *         ...,
 *         "statusCode" : 200
 *         }
 * },
 * { "Title" : {
 *         "propertyName" : "title",
 *         "value" : "Planet der Affen",
 *         "language" : "de-de",
 *         ...,
 *         "statusCode" : 200
 *         }
 * },
 * { ...
 * } ]
 */

Example for synchronous getOriginalMetadata:

syncMediaResource = mediaResource.createMediaResource("http://www.w3.org/2008/WebVideo/Annotations/wiki/images/9/93/MAWG-Stockholm-20090626.JPG",
                         new Array(), 2);
dcMetadata = syncMediaResource.getOriginalMetadata("DC");

if (noErrorStatus(dcMetadata[0].statusCode) == true) {
    ...
}

/** Resulting in:
 * [ { "statusCode" : 200
 * },
 * {"originalMetadata" : "<metadata xmlns='http://example.org/myapp/'
 *                                        xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 *                                        xsi:schemaLocation='http://example.org/myapp/ http://example.org/myapp/schema.xsd'
 *                                        xmlns:dc='http://purl.org/dc/elements/1.1/'>
 *                                          <dc:title>DC title</dc:title>
 *                                  </metadata>"
 * } ]
 */