Iso/Iec Jtc 1/Sc 29/Wg 11 N 9420

INTERNATIONAL ORGANISATION FOR STANDARDISATION

ORGANISATION INTERNATIONALE DE NORMALISATION

ISO/IEC JTC 1/SC 29/WG 11

CODING OF MOVING PICTURES AND AUDIO

ISO/IEC JTC 1/SC 29/WG 11 N10471

Lausanne, CH – February 2009

Source: Systems

Title: Text of ISO/IEC 23006-1 CD MXM APIs

Status Work in progress (Editing period)

Source Filippo Chiariglione (CEDEO.net)

Marius Preda (TELECOM SudParis)

Christian Timmerer (Klagenfurt University)

Wonsuk Lee (ETRI)

Text of ISO/IEC 23006-1 CD MXM APIs

Document type: Document subtype: Document stage: Document language:

ISO/IEC JTC 1/SC 29 N

Date: 2009-02-6

ISO/IEC CD 23006-2

ISO/IEC JTC 1/SC 29/WG 11

Secretariat: ANSI

Information technology — MPEG-M (MPEG eXtensible Middleware) — Part 2: MXM API

Élément introductif — Élément central — Partie 2: Titre de la partie

Warning

This document is not an ISO International Standard. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an International Standard.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Document type: International Standard Document subtype: Document stage: (30) Committee Document language: E

STD Version 2.0 ISO/IEC CD 23006-2 Copyright notice

This ISO document is a working draft or committee draft and is copyright-protected by ISO. While the reproduction of working drafts or committee drafts in any form for use by participants in the ISO standards development process is permitted without prior permission from ISO, neither this document nor any extract from it may be reproduced, stored or transmitted in any form for any other purpose without prior written permission from ISO.

Requests for permission to reproduce this document for the purpose of selling it should be addressed as shown below or to ISO's member body in the country of the requester: [Indicate the full address, telephone number, fax number, telex number, and electronic mail address, as appropriate, of the Copyright Manger of the ISO member body responsible for the secretariat of the TC or SC within the framework of which the working document has been prepared.]

Reproduction for sales purposes may be subject to royalty payments or a licensing agreement.

Violators may be prosecuted.

Contents Page

Foreword...... ix Introduction...... x 1 Scope...... 1 2 Normative references...... 1 3 Terms and definitions...... 2 4 Symbols and abbreviated terms...... 4 5 Namespace conventions...... 4 6 MXM Engine APIs...... 6 6.1 Digital Item Engine APIs...... 6 6.1.1 DI Creation...... 6 6.1.1.1 Specify metadata for a Content Item...... 6 6.1.1.2 Add an inner item to the digital item to be created...... 7 6.1.1.3 Creating a Digital Item...... 8 6.1.2 DI Editing...... 9 6.1.2.1 InsertContentInDIDElement...... 10 6.1.2.2 RemoveContentFromDIDElement...... 11 6.1.2.3 InsertAttributeInDIDElement...... 11 6.1.2.4 RemoveAttributeFromDIDElement...... 11 6.1.2.5 InsertDIDElementInDIDElement...... 12 6.1.2.6 RemoveDIDElementFromDIDElement...... 12 6.1.2.7 ReplaceDIDElement...... 12 6.1.2.8 ReplaceDIDElementAttribute...... 13 6.1.3 DI Access...... 13 6.1.3.1 GetArrayOfContentLicenses...... 13 6.1.3.2 GetArrayOfContentLicenseRefs...... 14 6.1.3.3 GetArrayOfLicenses...... 15 6.1.3.4 GetArrayOfLicenseRefs...... 15 6.1.3.5 Other methods...... 16 6.1.4 DI Presentation...... 20 6.2 MPEG-21 File Engine APIs...... 21 6.2.1 MP21 File Creation...... 21 6.2.1.1 Creating a DCF using ContentBuilder...... 21 6.2.1.2 Set the DI of an MPEG-21 file...... 22 6.2.1.3 Add a resource to an MPEG-21 file...... 22 6.2.1.4 Creating the MPEG-21 File...... 23 6.2.2 MP21 File Access...... 24 6.2.2.1 Extract a DI from an MPEG-21 file...... 24 6.2.2.2 Extract a resource from an MPEG-21 file...... 24 6.3 REL Engine APIs...... 24 6.3.1 License creation...... 24 6.3.1.1 Add a Grant to a License...... 24 6.3.1.2 Add an Issuer to a license...... 24 6.3.1.3 Create a Grant given the Principal, the Right, etc...... 24 6.3.1.4 Create a License...... 24 6.3.1.5 Create an ORC License using ContentBuilder...... 25 6.3.1.6 Create an ORC License using ORCLicenseBuilder...... 26 6.3.2 License Access...... 27 6.3.2.1 Getting the LicenseId...... 27 6.3.2.2 Operation to retrieve the license title...... 28 6.3.2.3 Operation to retrieve the inventory...... 29 6.3.2.4 Operation to retrieve the list of grants...... 29 6.3.2.5 Operation to retrieve the license issuer...... 30

IV © ISO/IEC 2009 — All rights reserved ISO/IEC CD 23006-2 6.3.2.6 Operation to retrieve other information...... 30 6.3.3 License validation...... 31 6.3.3.1 Validate if a License is Issued by a specific Issuer...... 31 6.3.4 License authorisation...... 31 6.3.4.1 Authorise an REL query against an REL License given a Context...... 31 6.4 IPMP Engine APIs...... 32 6.4.1 IPMP Information Creation...... 32 6.4.1.1 AddIPMPTool...... 33 6.4.1.2 SetMasterKey...... 34 6.4.1.3 Method to add a rigths descriptor to an IPMPInfoDescriptor...... 34 6.4.1.4 Method to add an element to an IPMPInfoDescriptor...... 35 6.4.1.5 Method to add an element to an IPMPGeneralInfoDescriptor...... 36 6.4.2 IPMP Information access...... 36 6.4.2.1 Parse an XML IPMP Message...... 36 6.4.2.2 Method to access IPMP Tool information from an IPMPInfoDescriptor...... 36 6.5 Access RightsDescriptor from an IPMPInfoDescriptor...... 37 6.5.1.1 Method to access RightsDescriptor from an IPMPInfoDescriptor...... 37 6.5.1.2 Method to access any information from any IPMP element...... 38 6.5.1.3 Create an XML IPMP Message...... 38 6.5.2 Resource Protection...... 38 6.5.2.1 ProtectResource...... 38 6.5.2.2 IdentifyProtectedResource...... 39 6.6 IPMP Tool instantiation...... 40 6.6.1.1 Method to instantiate a specific IPMP Tool having specific characteristics in a specific Control Point...... 40 6.6.1.2 Method to Initialise a specific IPMP Tool already instantiated with specific initialisation data...... 41 6.7 Media Framework Engine APIs...... 41 6.7.1 Generic Elementary Stream...... 41 6.7.1.1 Creation...... 41 6.7.1.2 Editing...... 43 6.7.1.3 Decoding...... 43 6.7.1.4 Rendering...... 43 6.7.1.5 Adaptation...... 43 6.7.2 Image APIs...... 45 6.7.2.1 Creation...... 45 6.7.2.2 Editing...... 45 6.7.2.3 Decoding...... 45 6.7.2.4 Rendering...... 45 6.7.3 Audio APIs...... 45 6.7.3.1 Creation...... 45 6.7.3.2 Editing...... 45 6.7.3.3 Decoding...... 45 6.7.3.4 Rendering...... 45 6.7.4 Video APIs...... 45 6.7.4.1 Creation...... 45 6.7.4.2 Editing...... 45 6.7.4.3 Decoding...... 45 6.7.4.4 Rendering...... 45 6.7.5 Reconfigurable Video APIs...... 45 6.7.5.1 Creation...... 45 6.7.5.2 Decoding...... 45 6.7.5.3 Engine-specific APIs...... 45 6.7.6 Muxed Content APIs...... 47 6.7.6.1 Creation...... 47 6.7.6.2 Editing...... 47 6.7.6.3 Access...... 47 6.7.6.4 Rendering...... 50 6.7.6.5 Engine-specific APIs...... 52 6.7.7 2D Layout APIs...... 60 6.7.7.1 Creation...... 60 6.7.7.2 Editing...... 60 6.7.7.3 Decoding...... 60

© ISO/IEC 2009 — All rights reserved V ISO/IEC CD 23006-2 6.7.8 2D Graphics Primitives APIs...... 61 6.7.8.1 Creation...... 61 6.7.8.2 Editing...... 61 6.7.8.3 Decoding...... 61 6.7.8.4 Rendering...... 61 6.7.8.5 CreateDIPresentation...... 61 6.7.8.6 Init...... 61 6.7.8.7 SetPresentationPanel...... 62 6.7.8.8 showNotify...... 63 6.7.9 3D Scene Graph APIs...... 63 6.7.9.1 Creation...... 63 6.7.9.2 Editing...... 63 6.7.9.3 Decoding...... 63 6.7.10 3D graphics primitives APIs...... 63 6.7.10.1 Geometry related API...... 63 6.7.10.2 Appearance related API...... 70 6.7.10.3 Texture-related API...... 73 6.7.10.4 Animation related API...... 76 6.7.10.5 Creation...... 83 6.7.10.6 Editing...... 83 6.7.10.7 Decoding...... 83 6.7.10.8 Rendering...... 83 6.8 Image Metadata Engine APIs...... 83 6.8.1 Image Metadata Creation...... 87 6.8.2 Image Metadata Editing...... 87 6.8.3 Image Metadata Access...... 87 6.8.4 Image Metadata Presentation...... 87 6.9 Audio Metadata Engine APIs...... 87 6.9.1 Audio Metadata Creation...... 87 6.9.2 Audio Metadata Editing...... 87 6.9.3 Audio Metadata Access...... 87 6.9.4 Audio Metadata Presentation...... 88 6.10 Video Metadata Engine APIs...... 88 6.10.1 Video Metadata Creation...... 88 6.10.2 Video Metadata Editing...... 89 6.10.3 Video Metadata Access...... 89 6.10.4 Video Metadata Presentation...... 89 6.11 Content Metadata Engine APIs...... 89 6.11.1 Content Metadata Creation...... 89 6.11.2 Content Metadata Editing...... 94 6.11.3 Content Metadata Access...... 94 6.11.4 Content Metadata Presentation...... 100 6.12 Digital Item Streaming Engine APIs...... 100 6.12.1 Digital Item Streaming Creation...... 100 6.12.2 Digital Item Streaming Editing...... 100 6.12.3 Digital Item Streaming Access...... 100 6.13 Digital Item Adaptation Engine APIs...... 100 6.13.1 Usage Environment Description Creation...... 100 6.13.2 Digital Item Adaptation Editing...... 101 6.13.3 Digital Item Adaptation Access...... 101 6.14 Digital Item Processing Engine APIs...... 103 6.14.1 Digital Item Processing Creation...... 103 6.14.2 Digital Item Processing Access...... 103 6.15 Event Reporting Engine APIs...... 103 6.15.1 Event Report Request Creation...... 103 6.16 Event Report Request Creation...... 103 6.16.1 Method to generate an ISO/IEC 21000-15 conformant Event Report Request...... 103 6.17 Event Report Creation...... 105 6.17.1 Method to generate an ISO/IEC 21000-15 conformant Event Report...... 105 6.18 Event Report Request Access...... 107 6.18.1 Method to obtain form a Digital Item all the Event Report Requests within it...... 107 6.18.2 Method is used to obtain Event Report Request fields from and ERR conformant to ISO/IEC 21000-15...... 107

VI © ISO/IEC 2009 — All rights reserved ISO/IEC CD 23006-2 6.18.3 Event Registration...... 108 6.18.4 Event Report Transmission...... 108 6.19 Content Protocol Engine APIs...... 108 6.19.1 Content Identification Protocol...... 108 6.19.1.1 Identify Content Item...... 109 6.19.1.2 Identify Content Element...... 111 6.19.2 Content Authentication Protocol...... 113 6.19.2.1 Authenticate Content Item...... 113 6.19.2.2 Authenticate Content Element...... 114 6.19.3 Content Access Protocol...... 115 6.19.3.1 AccessContentElement...... 115 6.19.4 Content Storage Protocol...... 116 6.19.4.1 Store a DCF...... 116 6.19.4.2 Store a DCS...... 117 6.20 License Protocol Engine APIs...... 118 6.20.1 License Access...... 118 6.20.1.1 Operation to retrieve a license given the id...... 119 6.20.2 License Storage...... 120 6.20.3 Operation to revoke a license...... 121 6.21 IPMP Tool Protocol Engine APIs...... 122 6.21.1 IPMP Tool Access...... 122 6.21.2 IPMP Tool List Access...... 122 6.22 Content Search Engine APIs...... 123 6.22.1 Content Store...... 123 6.22.2 Content Search...... 124 6.23 Security Engine APIs...... 125 6.23.1 Key Generation...... 125 6.23.1.1 Random key generation...... 125 6.23.1.2 Random key-pair generation...... 125 6.23.2 Encryption...... 126 6.23.2.1 Encrypt an array of bytes using asymmetric encryption...... 126 6.23.2.2 Encrypt an array of bytes using symmetric encryption...... 127 6.23.3 Decryption...... 128 6.23.3.1 Asymmetric decrypt an array of bytes...... 128 6.23.3.2 Symmetric decrypt an array of bytes...... 129 6.23.4 Hash calculation...... 129 6.23.4.1 Generate a hash value of an array of bytes...... 129 6.23.4.2 Generate a hash value of the contents of a file...... 130 6.23.5 Hash verification...... 131 6.23.5.1 Verify the hash value of the contents of an array of bytes...... 131 6.23.6 Digital Signature generation...... 131 6.23.6.1 Generate the digital signature for an array of bytes...... 131 6.23.7 Digital Signature verification...... 132 6.23.7.1 Verify the digital signature for an array of bytes...... 132 6.23.8 Security Information Access...... 133 6.23.8.1 Get a certificate from the secure repository as an X.509 Certificate...... 133 6.23.8.2 Get a certificate from the secure repository as an REL Principal...... 134 6.23.8.3 Get a certificate from the secure repository as a DeviceID...... 135 6.23.8.4 Export a certificate to a file...... 135 6.23.8.5 Get an array of licenses from the secure repository...... 136 6.23.8.6 Get a list of licenses from the secure repository...... 137 6.23.8.7 Get user information from the secure repository...... 138 6.23.8.8 Get domain information from the secure repository...... 138 6.23.9 Authentication...... 139 6.23.10 Trust verification...... 139 6.23.10.1 Digital Signature verification...... 139 6.23.11 Secure information storage...... 139 6.23.11.1 Store a license...... 139 6.23.11.2 Store usser information...... 140 6.23.11.3 Store a key into the secure repository...... 141 6.23.11.4 Create a Private Key for a new user and store it into the secure repository...... 141 6.23.11.5 Store a certificate from a file in the secure repository...... 143 6.23.11.6 Store a certificate from a KeyInfo in the secure repository...... 143

© ISO/IEC 2009 — All rights reserved VII ISO/IEC CD 23006-2 6.23.11.7 Store domain information in the secure repository...... 144 6.23.12 Security Information deletion...... 145 6.23.12.1 Delete a trusted certificate from the secure repository...... 145 6.23.12.2 Delete a license from the secure repository...... 146 6.23.12.3 Delete user information from the secure repository...... 147 6.23.12.4 Delete domain information from the secure repository...... 147 6.23.13 Miscellanea...... 148 6.23.13.1 Verify a REL Principal...... 148 6.23.13.2 Method to generate and embed the digital signature for an XML document...... 149 6.23.13.3 Method to verify the digital signature for an XML document...... 149 6.23.13.4 Method to authenticate a User with Password...... 150 6.23.13.5 Method to authenticate user with password and user certificate...... 151 6.23.13.6 Method to estimate the fingerprint of a tool...... 152 6.23.13.7 Method to enable or certify the operation of a tool...... 152 6.23.13.8 Method to verify locally the integrity of a tool...... 153 6.23.13.9 Method to verify remotely the integrity of a tool...... 153 6.23.13.10 Method to disable to operation of a tool...... 154 6.24 MVCO Engine APIs...... 155 6.24.1.1 Operation to load a data set from a given location...... 155 6.24.1.2 Operation to save the current data set in a given location...... 156 6.24.1.3 Operation to unload the current data set...... 156 6.24.1.4 Operation to create a user in the ontology...... 157 6.24.1.5 Operation to delete a user in the ontology...... 158 6.24.1.6 Operation for the execution of an action by a User...... 159 6.24.1.7 Operation to create a permission...... 159 6.24.1.8 Operation to launch a query...... 161 6.24.1.9 Operation to validate an action...... 162 6.24.1.10 Operation to get the list of registered users...... 163 6.24.1.11 Operation to get the list of registered IPEntities...... 163 6.24.1.12 Operation to get the rights owner of a given IPEntity...... 164 6.24.1.13 Operation to geg the IPEntity origin of a given IPEntity...... 165 6.25 Domain Engine APIs...... 166 6.25.1 Domain Management...... 166 6.25.1.1 Create Domain...... 166 6.25.1.2 Renew Domain...... 167 6.25.1.3 Delete Domain...... 168 6.25.1.4 Add Device...... 169 6.25.1.5 Add User...... 170 6.25.1.6 Renew Device...... 171 6.25.1.7 Renew User...... 171 6.25.1.8 Leave Device...... 172 6.25.1.9 Leave User...... 173 6.25.1.10 RequestLocalDomainID...... 174 6.25.2 Domain Access...... 174 6.25.2.1 RequestDomainPublicInfo...... 174 6.25.3 Domain Usage...... 175 6.25.3.1 Get Domain License...... 176 6.25.3.2 Store Domain License...... 177 6.25.3.3 Delete Domain License...... 177 6.25.3.4 Update Domain License...... 178 6.25.3.5 Start Domain Use...... 178 6.25.3.6 End Domain Use...... 179 6.25.4 UnlicensedSimultaneousUseNotice...... 180 6.26 Rendering Engine APIs...... 181 6.26.1 getNumberOfScreens...... 181 6.26.2 getScreen...... 181 6.26.3 getAspectRatio...... 182 6.26.4 getNativeResolution...... 183 6.26.5 setResolution...... 183 6.26.6 setPixelFormat...... 184 6.26.7 setPosition...... 185 6.26.8 setSize...... 185 6.26.9 initialize...... 186

VIII © ISO/IEC 2009 — All rights reserved ISO/IEC CD 23006-2 6.26.10 setEventHandler...... 186 6.26.11 setSource...... 187 6.26.12 renderGeometry...... 188 6.26.13 showAnimation...... 188 6.26.14 showBBAAnimation...... 189 7 MXM Application APIs...... 190 7.1.1 Open...... 190 7.1.2 CanAccessContentElement...... 191 7.1.3 Play...... 192 7.1.4 PresentDigitalItem...... 192 7.1.5 Adapt(namespaceURI:string, ued:string, resourceURI:string)...... 192 7.1.6 ProcessDigitalItem...... 192 Annex A (normativ) MXM Interfaces...... 193 A.1 ContentMetadataEngine...... 193 A.2 Mpeg7...... 193 A.3 Mpeg7Parser...... 193 A.4 MXMEngineResponse...... 193 A.5 MXMUseEnvDescr...... 193 Annex B (normativ) MXM Exceptions...... 194 B.1 ContentMetadataEngineException...... 194 B.2 MXMDescrException...... 194 Bibliography...... 195

Foreword

ISO (the International Organization for Standardization) and IEC (the International Electrotechnical Commission) form the specialized system for worldwide standardization. National bodies that are members of ISO or IEC participate in the development of International Standards through technical committees established by the respective organization to deal with particular fields of technical activity. ISO and IEC technical committees collaborate in fields of mutual interest. Other international organizations, governmental and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.

International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 3.

The main task of the joint technical committee is to prepare International Standards. Draft International Standards adopted by the joint technical committee are circulated to national bodies for voting. Publication as an International Standard requires approval by at least 75 % of the national bodies casting a vote.

Attention is drawn to the possibility that some of the elements of this part of ISO/IEC 23006 may be the subject of patent rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights.

ISO/IEC 23006-2 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology, Subcommittee SC 29, Coding of audio, picture, multimedia and hypermedia information.

This second/third/... edition cancels and replaces the first/second/... edition (), [clause(s) / subclause(s) / table(s) / figure(s) / annex(es)] of which [has / have] been technically revised.

ISO/IEC 23006 consists of the following parts, under the general title Information technology — MPEG-M (MPEG eXtensible Middleware):

 Part 1: MXM Architecture and Technologies

 Part 2: MXM API

 Part 3: MXM Conformance and Reference Software

Introduction

ISO/IEC 23006 is a suite of standards that has been developed for the purpose of enabling the easy design and implementation of media-handling value chains whose devices interoperate because they are all based on the same set of technologies, especially technologies standardised by MPEG, accessible from the MXM middleware.

This will enable the development of a global market of:

 MXM applications that can run on MXM devices thanks to the existence of a standard MXM application API

 MXM devices hosting MXM applications thanks to the existence of a standard MXM architecture

 MXM components thanks to the existence of standard MXM components APIs

 Innovative business models because of the ease to design and implement media-handling value chains whose devices interoperate because they are all based on the same set of technologies, especially MPEG technologies.

Information technology — MPEG-M (MPEG eXtensible Middleware) — Part 2: MXM API

1 Scope This international standard specifies a set of Application Programming Interfaces (APIs) enabling applications to access standard multimedia technologies.

NOTE The purpose of this international standard is to promote the extended use of digital media content through increased interoperability and accelerated development of components, solutions and applications.

This is achieved by specifying

 The MXM architecture (ISO/IECC 23006-1);

 The MXM components (by reference – ISO/IEC 23006-1);

 The MXM components APIs (ISO/IEC 23006-2);

 The MXM applications API (ISO/IEC 23006-2);

 The inter-MXM communication protocols (ISO/IEC 29116-1).

The scope of this international standard is solely the APIs whereas the actual MXM engines are deliberately out of scope and left open for industry competition.

NOTE The APIs are made available to applications by means of MXM Engines. Each Engine (e.g. the MediaFramework Engine) provides access to a single MPEG technology (e.g. video coding) or to a group of MPEG technologies where this is convenient.

2 Normative references The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.

ISO/IEC 13818 (all parts) Information technology -- Generic coding of moving pictures and associated audio

ISO/IEC 14496 (all parts) Information technology -- Coding of audio-visual objects

ISO/IEC 15938 (all parts) Information technology -- Multimedia Content Description Interface

ISO/IEC 21000 (all parts) Information technology -- Multimedia Framework

ISO/IEC 23000 (all parts) Information technology -- Multimedia Application Formats

ISO/IEC 23001 (all parts) Information technology -- MPEG Systems Technologies

ISO/IEC 23002 (all parts) Information technology -- MPEG Video Technologies

ISO/IEC 23003 (all parts) Information technology -- MPEG Audio Technologies

ISO/IEC 23004 (all parts) Information technology -- MPEG Multimedia Middleware

ISO/IEC 29116 Information technology:2007/Amd 2:2009 -- Supplemental Media Technologies – Multimedia eXtensible Middleware Protocols

ISO/IEC YYYYY-1, Information technology – MPEG-M (MPEG eXtensible Middleware) -- Part 1: MXM Architecture and Technologies

3 Terms and definitions For the purposes of this document, the following terms and definitions apply.

3.1 Content Creation Device a device enabling the creation of content possibly including audio-visual resources, rights information, metadata, etc.

3.2 Content Identification Device a device providing content identification and authentication services to another device

3.3 Content Provider Device a device on which content may be stored and delivering content to another device

3.4 Device a combination of hardware and software or just an instance of software that allows a user to perform actions

3.5 Domain Administrator a user creating and administering a domain by means of a Domain Management Device

3.6 Domain Management Device a device managing the lifecycle of a domain and the membership of devices and users part of it.

3.7 Inter-MXM Protocol a protocol that enable communication between MXM Devices.

3.8 IPMP Processor a module in a Media Streaming Player in charge of retrieving, instantiating, initialising and managing the IPMP Tools required to perform actions on content.

3.9 IPMP Tool a module performing (one or more) IPMP functions such as authentication, decryption, watermarking, etc.

3.10 IPMP Tool Agent a module instantiating, initialising, authenticating, and supervising any operation performed between IPMP Tools within an IPMP Tool Group

3.11 IPMP Tool Body executable code implementing either a Single IPMP Tool or an IPMP Tool Pack

3.12 IPMP Tool Group a combination of several IPMP Tools

3.14 IPMP Tool Provider Device a device delivering IPMP Tools to another device

3.15 Licence Provider Device a device delivering licenses to another device according to a License Template previously stored

3.16 Licence Template a license granting rights to issue licenses to a device

3.17 MXM Application an application that runs on an MXM device and make calls to the MXM Application and MXM Engine APIs

3.18 MXM Application API the API of the MXM Orchestrator Engine.

3.19 MXM Device a device equipped with MXM

3.20 MXM Engine a homogeneous set of MXM Technologies

3.21 MXM Engine API the API of a single MXM Engine

3.22 MXM Orchestrator Engine a special MXM Engine capable of creating chains of MXM engines to execute a high-level application call such as Play

3.23 MXM Technology a technology that is supported by (a profile of) MXM

3.24 User any identified entity interacting in a media streaming environment using a media streaming device.

4 Symbols and abbreviated terms BBL Bitstream Binding Language

CCD Content Creation Device

CID Content Identification Device

CPD Content Provider Device

DIA Digital Item Adaptation

DID Digital Item Declaration

DIDL Digital Item Declaration Language

DII Digital Item Identification

DIS Digital Item Streaming

DMD Domain Management Device

ER Event Report

ERR Event Report Request

IPMP Intellectual Property Management and Protection

LPD License Provider Device

LLAP Local License Access Protocol

MXMD Media Streaming Device

MSP Media Streaming Player

REL Rights Expression Language

RTP Real Time Protocol

RTSP Real Time Streaming Protocol

URI Uniform Resource Identifier

5 Namespace conventions Throughout this part of ISO/IEC YYYYY, Qualified Names are written with a namespace prefix followed by a colon followed by the local part of the Qualified Name.

For clarity, throughout this part of ISO/IEC YYYYY, consistent namespace prefixes are used. Table 1 gives these prefixes and the corresponding namespace.

Table 1 — Namespaces and prefixes

Prefix Corresponding namespace ipmpdidl urn:mpeg:mpeg21:2004:01-IPMPDIDL-NS ipmpmsg urn:mpeg:mpeg21:2006:07-IPMPMESSAGES-NS ipmpinfo urn:mpeg:mpeg21:2004:01-IPMPINFO-NS didl urn:mpeg:mpeg21:2002:02-DIDL-NS didmodel urn:mpeg:mpeg21:2002:02-DIDMODEL-NS didl-msx urn:mpeg:maf:schema:mediastreaming:DIDLextensions dii urn:mpeg:mpeg21:2002:01-DII-NS r urn:mpeg:mpeg21:2003:01-REL-R-NS sx urn:mpeg:mpeg21:2003:01-REL-SX-NS m1x urn:mpeg:mpeg21:2005:01-REL-M1X-NS

4 © ISO/IEC 2009 — All rights reserved xsd http://www.w3.org/2001/XMLSchema xsi http://www.w3.org/2001/XMLSchema-instance dsig http://www.w3.org/2000/09/xmldsig# mxmacp urn:mpeg:mpeg-m:schema:accesscontentprotocol:2009 mxmaitp urn:mpeg:mpeg-m:schema:accessipmptoolprotocol:2009 mxmalp urn:mpeg:mpeg-m:schema:accesslicenseprotocol:2009 mxmaucp urn:mpeg:mpeg-m:schema:authenticatecontentprotocol:2009 mxmbp urn:mpeg:mpeg-m:schema:baseprotocol:2009 mxmd urn:mpeg:mpeg-m:schema:domain:2009 mxmdp urn:mpeg:mpeg-m:schema:domainprotocol:2009 mxmicp urn:mpeg:mpeg-m:schema:identifycontentprotocol:2009 mxmscp urn:mpeg:mpeg-m:schema:storecontentprotocol:2009 mxmslp urn:mpeg:mpeg-m:schema:storelicenseprotocol:2009

The MXM APIs are specified using UML 1.4.2 (ISO/IEC 19501) in order to allow implementations of MXM APIs in multiple programming languages.

Methods are defined in the following way:

 Each method is shown with at least its name, and optionally also with its parameters and return type.

 Access modifier as follows:

 "+" for public

 "#" for protected

 "-" for private

 "~" for package

 Then we can have other optional modifier (for example final) and then the name of the method followed by parentheses "( )".

 After that we a colon ":" between the closed parenthesis and the returned type.

 If the method has parameters, they are expressed with the reference name, a colon and the related object type.

 If the method is static it will be underlined and if it is abstract all the sentence is written in Italic style.

 This is an example of a login method expressed in UML:

 + login(name:String, password:String):boolean

6 MXM Engine APIs

Replace the text below with a Class-Responsibility-Collaboration-like model description.

Generate the API definition and documentation with automatic tools (e.g. Doxygen) to be included as an annex with normative value

6.1.1 DI Creation

The APIs in this section are used to create a Digital Item having the following characteristics: a top-level didl:Item, child of the didl:DIDL element contains all the information describing the content item as a whole (e.g. the content identifier, content metadata, etc.). A content item may include a number of content elements (e.g. a resource) each represented in the Digital Item by a didl:Item child of the top-level didl:Item which also contains all the information describing the content element (e.g. the content element identifier, content element metadata, content element protection information, etc.). The methods described in this section are used to create a content item having such characteristics, and are made available by an instance of ContentBuilder (see A.2).

6.1.1.1 Specify metadata for a Content Item

Interface ContentBuilder (see Error: Reference source not found)

Method Syntax

+ setContentMetadata (contentitemMetadata : ContentItemMetadata):void

Java sample code public interface ContentBuilder { public void setContentMetadata(ContentItemMetadata contentItemMetadata); } Method description

This method is used to specify content metadata in order to be added to the Digital item when the content is created

Parameters contentItemMetadata An instance of ContentItemMetadata (see Error: Reference source not found) containing all metadata elements for the content item. This information will be inserted into the didl:Descriptor -> didl:Statement -> didl-msx:metadata -> didl-msx:StructuredData child of the top-level didl:Item

Return value void

Exceptions

6.1.1.2 Add an inner item to the digital item to be created

Method Syntax

+ addContentElement (contentElement: ContentElementInterface):boolean

Java sample code public interface ContentBuilder { public boolean addContentElement (ContentElementInterface contentElement) throws MalformedContentElementException, UnsupportedFeatureException, SecurityManagerException,

This method is used to specify that content element has to be added to a content item when the content item is created

Parameters contentElement An instance of ContentElementInterface (see Error: Reference source not found) containing all the information related to the content element (e.g. the content element identifier, metadata, protection information, resource location etc).

Return value

True if the content element was successfully added to the content item.

Exceptions

MalformedContentElementException If the content element added was malformed, its contents not complete or leading to misinterpretation.

UnsupportedFeatureException If the information contained in the content element require any processing which MXM does not support.

SecurityManagerException If an error occurred while accessing the data from the SecurityManager (in case a ProtectedContentElement (see Error: Reference source not found) was added).

DCIGenerationException If an error occurs while generating the XML elements forming the Digital Item.

6.1.1.3 Creating a Digital Item

Method Syntax

+ createDCI (cidServiceURL : string, identifyBySendingDCI : boolean): DIDL

Java sample code public interface ContentBuilder { public DIDL createDCI(String cidServiceURL, boolean identifyBySendingDCI) throws DCIGenerationException, LicenseGenerationException, MalformedContentElementException, SecurityManagerException, BadPropertyException, UnsupportedFeatureException, ContentIdentificationException, StoreLicenseTemplateException; } Method description

This method is used to generate a Digital Item conforming to MS AF restrictions to ISO/IEC 21000-2. After ContentItemMetadata and all objects of type ContentElementInterface have been set, by calling this method MXM will perform the following steps:

 Generate all licenses for all GovernedContentElements in the case any of the GovernedContentElements had requested this operation to be performed by setting specific properties (see Error: Reference source not found). Note that a license can be already included in a GovernedContentElement, or a license reference, so in this case this step will not performed.  Create a Digital Item including all the information previously set

© ISO/IEC 2009 — All rights reserved 7 ISO/IEC CD 23006-2  Identify the Digital Item from the Content Identification Service specified by the cidServiceURL parameter and using one of the two Content Identification Protocols specified in Error: Reference source not found  Store License Templates in case any of the GovernedContentElements had requested this operation to be performed by setting specific properties (see Error: Reference source not found) Parameters cidServiceURL The Content Identification Service where a new Content Identifier has to be requested using one of the two Content Identification Protocols specified in Error: Reference source not found identifyBySendingDCI A Boolean value indicating whether the Content Identification shall be made using Error: Reference source not found (if true) of Error: Reference source not found if false.

Return value

An object of type DIDL (see Error: Reference source not found) representing the Digital Item that was created, which can be converted in the most common formats, e.g. stored in an xml file, returned as an xml string of characters, etc..

Exceptions

UnsupportedFeatureException If the information contained in the content element require any processing which MXM does not support (e.g. an encryption algorithm which is not supported).

SecurityManagerException If an error occurred while accessing the data from the SecurityManager (in case one or more ProtectedContentElement (see Error: Reference source not found) were added to the content item).

LicenseGenerationException This exception is thrown if a problem occurs during the generation of licenses for any of the GovernedContentElement or ProtectedContentElements requesting this operation

StoreLicenseTemplateException If an exception occurred while storing a License Template on a License service, in the case any of the GovernedContentElements had requested this operation to be performed by setting specific properties (see Error: Reference source not found).

ContentIdentificationException If an error occurred while a Content Identifier was requested to the Content Identification Service

BadPropertyException If any of the properties used to configure the ContentBuilder were corrupted or incorrectly set.

DCIGenerationException If an error occurs while generating the XML elements forming the Digital Item.

6.1.2 DI Editing

The API provided by MXM for the manipulation of Digital Items (DIs) should enable the calling applications to build and manipulate DIs at any level of granularity.

The view behind this specification is that the DID construction process begins from the finest level of granularity up.

Method syntax for interface DigitalItemManagement

+insertContentInDIDElement(didElement : string, didElementContent : Object, contentType : string) : string

+removeContentFromDIDElement(didElement : string) : string

+insertAttributeInDIDElement(didElement : string, attributeName : string, attributeValue : string) : string

+removeAttributeFromDIDElement(didElement : string, attributeName : string) : string

+insertDIDElementInDIDElement(parentDIDElemt : string, childDIDElement : string) : string

+removeDIDElementFromDIDElement(parentDIDElemt : string, childDIDElementName : string, childElementPosition : int) : string

+replaceDIDElement( parentDIDElemt : string, newChildDIDElement : string, oldChildDIDElementName : string, oldChildDIDElementPosition : int) : string

+replaceDIDElementAttribute(didElement : string, attributeName : string, attributeValue : string) : string

Class Diagram

public interface DigitalItemManagement

String insertContentInDIDElement(String didElement, Object didElementContent, String contentType) throws MXMDIDAccessException;

String removeContentFromDIDElement(String didElement)throws MXMDIDAccessException;

String insertAttributeInDIDElement(String didElement, String attributeName, String attributeValue) throws MXMDIDAccessException;

String removeAttributeFromDIDElement(String didElement, String attributeName) throws MXMDIDAccessException;

String insertDIDElementInDIDElement(String parentDIDElemt, String childDIDElement) throws MXMDIDAccessException;

String removeDIDElementFromDIDElement(String parentDIDElemt, String childDIDElementName, int childElementPosition) throws MXMDIDAccessException;

String replaceDIDElement(String parentDIDElemt, String newChildDIDElement,

String oldChildDIDElementName, int oldChildDIDElementPosition) throws MXMDIDAccessException;

6.1.2.1 InsertContentInDIDElement

This method inserts the given (non-xml) text or binary content into the given DID element. The element should be a Resource, Statement or a Fragment.

The didElement parameter is a String which carries a DID element.

The didElementContent parameter is the content to be inserted into the DID.

The contentType parameter is the type of content which is to be inserted into the DID element. The possible values for this parameter are TXTCONTENT and BINCONTENT.

The return value is an XML String containing the given DID element with the given content placed inside.

This method may raise the following exceptions:

MXMDIDAccessException with error INVALID_DIDPORTION_ERROR if the given DID portion (or DID element) is for some reason invalid.

MXMDIDAccessException with error INVALID_CONTENT_ERROR if the given content is for some reason invalid or inappropriate.

MXMDIDAccessException with error INVALID_CONTENT_TYPE_ERROR if the specified type of content is invalid.

6.1.2.2 RemoveContentFromDIDElement

This method removes the text or binary content contained within the given DID element.

The return value is an XML String containing the given DID element without the previously contained content.

MXMDIDAccessException with error NO_CONTENT_PRESENT_ERROR if no content is present in the given DID element.

6.1.2.3 InsertAttributeInDIDElement

This method inserts the given attribute with the specified value in the given DID element. If the insertion of the specified attribute, or its value, is not in accordance with the MPEG-21 DID standard, exceptions will be thrown.

The attributeName parameter is the name of the attribute to be inserted. If the specified attribute is present, it will be overwritten.

The attributeValue element is the value of the attribute to be inserted.

The return value is an XML String containing the given DID element with the specified attribute added.

MXMDIDAccessException with error INVALID_ATTRIBUTE_INSERTION_ERROR if the attribute specified to be inserted is not appropriate or in accordance with the standard.

MXMDIDAccessException with error INVALID_ATTRIBUTE_VALUE_ERROR if the specified value for the attribute to be inserted is invalid or inappropriate.

6.1.2.4 RemoveAttributeFromDIDElement

This method removes the specified attribute from the given DID element.

The attributeName parameter is the name of the attribute to be removed.

The return value is an XML String containing the given DID element without the specified attribute.

MXMDIDAccessException with error NO_ATTRIBUTE_PRESENT_ERROR if the attribute specified to be removed is not present.

6.1.2.5 InsertDIDElementInDIDElement

This method inserts the given child DID element within the given DID element, in the appropriate position. If the insertion of the specified DID element, is not in accordance with the MPEG-21 DID standard, an exception will be thrown.

The childDIDElement parameter is an XML string carrying the DID element to be inserted.

The return value is an XML String containing the given DID element with the given child DID element added inside.

MXMDIDAccessException with error INVALID_DIDPORTION_ERROR ERROR if the given DID portion (or DID element) is for some reason invalid.

MXMDIDAccessException with error INVALID_ELEMENT_INSERTION_ERROR if the insertion of the specified element is against the MPEG-21 DID standard.

6.1.2.6 RemoveDIDElementFromDIDElement

This method removes the given child DID element from within the given DID element.

The childDIDElementName parameter is the name of the child DID element to be removed.

The childDIDElementPosition parameter is the position of the DID child element to be removed (in case more than one of such elements exist). The first position (top to bottom) is zero.

MXMDIDAccessException with error NO_ELEMENT_FOUND_ERROR if the element specified to be removed is not present.

6.1.2.7 ReplaceDIDElement

This method replaces a specified old child DID element with a new DID element, inside the given parent DID element. The new and old DID elements must be of the same type.

The newChildDIDElement parameter is an XML string with the new DID child element to be inserted.

The oldChildDIDElementName parameter is the name of the child DID element to be replaced.

The oldChildDIDElementPosition parameter is the position of the DID child element to be replaced (in case more than one of such elements exist). The first position (to bottom) is zero.

The return value is an XML String containing the given DID element with the specified child DID element replaced by the given new DID child.

MXMDIDAccessException with error NO_ELEMENT_FOUND_ERROR ERROR if the element specified to be removed is not present.

MXMDIDAccessException with error INVALID_ELEMENT_INSERTION_ERROR if the insertion of the new specified element is against the MPEG-21 DID standard.

6.1.2.8 ReplaceDIDElementAttribute

This method replaces the specified attribute value with the new given value. If the specified value is not in accordance with the MPEG-21 DID standard an error is thrown

The attributeName parameter is the name of the attribute whose value is to be altered.

The attributeValue parameter is the new value to be attributed to the specified attribute.

The return value is an XML String containing the given DID element with the specified new value attributed to the specified attribute.

MXMDIDAccessException with error INVALID_DIDPORTION_ERROR ERROR if the given DID portion (or DID element) is for some reason invalid.

MXMDIDAccessException with error NO_ATTRIBUTE_FOUND_ERROR if the attribute specified to be replaced is not present.

MXMDIDAccessException with error INVALID_ATTRIBUTE_VALUE_ERROR id the value of the attribute to be inserted is invalid or not in accordance with the MPEG-21 DID standard.

6.1.3.1 GetArrayOfContentLicenses

In order to extract from a Digital Item all the licenses governing the content item as a whole (i.e. present in the ipmpinfo:IPMPInfoDescriptor associated to the top-level didl:Item described in it, an instance of DCIParser (see Error: Reference source not found) has to be created and initialised by requesting the DCIParser to parse the Digital Item.

Interface DCIParser (see Error: Reference source not found)

Method Syntax

+ getArrayOfContentLicenses (): RELLicense[]

Java sample code public interface DCIParser { public RELLicense[] getArrayOfContentLicenses(); } Method description

This method is used to obtain all the licenses governing a content item as a whole. This method supposes that an object of type DCIParser has been instantiated and requested to parse the Digital Item containing the content element whose licenses are sought.

Parameters

Return value

An array containing all the Licenses (see Error: Reference source not found) found in the Digital Item for the content item.

Exceptions

6.1.3.2 GetArrayOfContentLicenseRefs

License References are URLs of services providing a license upon request if certain conditions are satisfied.

In order to extract from a Digital Item all the license references for the whole content item, an instance of DCIParser (see Error: Reference source not found) has to be created and initialised by requesting the DCIParser to parse the Digital Item.

Method Syntax

+ getArrayOfContentLicenseRefs (): string[]

Java sample code public interface DCIParser { public String[] getArrayOfLicenseRefs(); }

This method is used to obtain all the license references available for a content element (e.g. a resource) described in it. This method supposes that an object of type DCIParser has been instantiated and requested to parse the Digital Item containing the content element whose licenses are sought.

Parameters

Return value

An array containing all the license references found in the Digital Item for the whole content item.

Exceptions

6.1.3.3 GetArrayOfLicenses

In order to extract from a Digital Item all the licenses governing a specific content element described in it, an instance of DCIParser (see Error: Reference source not found) has to be created and initialised by requesting the DCIParser to parse the Digital Item.

Method Syntax

+ getArrayOfLicenses (contentElementID:String): RELLicense[]

Java sample code public interface DCIParser { public RELLicense[] getArrayOfLicenses(String contentElementID); } Method description

This method is used to obtain all the licenses available for a content element (e.g. a resource) described in it. This method supposes that an object of type DCIParser has been instantiated and requested to parse the Digital Item containing the content element whose licenses are sought.

Parameters contentElementID The identifier of the content element whose licenses are sought.

Return value

An array containing all the Licenses (see Error: Reference source not found) found in the Digital Item for the content element whose identifier was specified in input.

Exceptions

6.1.3.4 GetArrayOfLicenseRefs

License References are URLs of services providing a license upon request if certain conditions are satisfied.

14 © ISO/IEC 2009 — All rights reserved In order to extract from a Digital Item all the license references for a specific content element described in it, an instance of DCIParser (see Error: Reference source not found) has to be created and initialised by requesting the DCIParser to parse the Digital Item.

Method Syntax

+ getArrayOfLicenseRefs (contentElementID:String): string[]

Java sample code public interface DCIParser { public String[] getArrayOfLicenseRefs(String contentElementID); } Method description

This method is used to obtain all the license references available for a content element (e.g. a resource) described in it. This method supposes that an object of type DCIParser has been instantiated and requested to parse the Digital Item containing the content element whose licenses are sought.

Parameters contentElementID The identifier of the content element whose licenses are sought.

Return value

An array containing all the license references found in the Digital Item for the content element whose identifier was specified in input.

Exceptions

6.1.3.5 Other methods

[Editor's note: use one table for each method, make consistent with the rest of the document]

The specification of this API assumes that Digital Items and respective DIDs are correctly formed, that DIDs are syntactically in agreement with the MPEG-21 DID standard and that valid unique identifiers have been inserted in each Item element.

The API provided by MXM for the access to Digital Items (DIs) should enable the calling applications to access any portion of the metadata contained in a DID, to any level of granularity, within the element tree. The extracted data portion must either be a well formed XML (MPEG-21) fragment, or a contextualized textual or binary block of data.

Individual Item elements within the DID XML tree should be directly accessible through DID-wide unique Digital Item Identifiers (DIIs). All DID elements should be accessible via a request for some specific content (element) of an ancestor Item node.

Non-element data must be accessible, in a context dependent manner, via the identifier of an ancestor Item node.

The API should also be able to deliver a listing of the top Items in a DID or in an Item, and also a listing of their IDs.

UML Specifications

Method syntax for interface DigitalItemAccess

+getItem(didPortion : string, itemID : string) : string

+getItemID(didPortion : string) : string

+getItemChildren(didPortion : string, elementPath : string) : ArrayList

+getElements( didPortion : string, itemID : string, elementPath : string) : ArrayList

+getDIDElements(didElement : string, desiredElementName : string) : ArrayList

+getElementContent(didElement : string) : HashTable

Class Diagram

Java sample code implementation public interface DigitalItemAccess

Hashtable getTopItems(String didPortion) throws MXMDIDAccessException;

String getItem(String didPortion, String itemID) throws MXMDIDAccessException;

String getItemID (String didPortion) throws MXMDIDAccessException;

ArrayList getItemChildren(String didPortion, String elementPath) throws MXMDIDAccessException;

ArrayList getElements(String didPortion, String itemID, String elementPath) throws MXMDIDAccessException;

ArrayList getDIDElements(String didElement, String desiredElementName) throws MXMDIDAccessException;

Hashtable getElementContent(String didElement) throws MXMDIDAccessException;

6.1.3.5.1 GetTopItems

This method returns a Hashtable containing the IDs of the top level Items of the given DID tree, as the keys, and XML strings containing the corresponding Item elements (and their contents) as the values.

16 © ISO/IEC 2009 — All rights reserved The given tree may consist of an entire DID, or only of an Item element (and its content). In the later case, the top child Items of the given Item will be returned.

The didPortion input parameter is a String which consists of either an entire DID or a properly formatted subset of it.

The return value is a Hashtable containing the IDs of the top level Items of the given DID tree as the keys, and XML strings containing the corresponding Item elements (ant their contents) as the values.

MXMDIDAccessException with error INVALID_DIDPORTION_ERROR if the given DID portion is for some reason invalid.

MXMDIDAccessException with error NO_ITEMS_PRESENT_ERROR if no Items exist within the given DID portion.

6.1.3.5.2 GetItem

This method retrieves from the supplied DID portion the Item element identified by the given identifier.

The didPortion parameter is a String which consists of either an entire DID or a properly formatted subset of it.

The itemID parameter is the DID wise unique identifier (a URI), of the desired Item element.

The return value is an XML String containing the requested Item element.

MXMDIDAccessException with error INVALID_ITEMID_ERROR if the given Item id is invalid.

MXMDIDAccessException with error ITEM_NOT_PRESENT_ERROR if no Items with the given Item id exist within the given DID portion.

6.1.3.5.3 GetItemID

This method returns the identifier of the first Item element encountered in the given DID portion. Logically the given DID portion should consist of an Item element (and its contents).

The return value is a String containing the ID of the first Item element encountered in the given did portion.

MXMDIDAccessException with error ITEM_NOT_PRESENT_ERROR if no Items exist within the given DID portion.

MXMDIDAccessException with error ID_NOT_PRESENT_ERROR if the id attribute is not present in the Item in scope.

This method returns all of DID elements which conform to the given element path and are contained inside the first Item found inside the given did portion. Logically the did portion should consist of an Item (and its contents), or contain only one Item, even if contained within another element.

The elementPath parameter is a String with a comma separated list which specifies the path to the target element(s). For instance, the path “Component;Descriptor” will lead to the retrieval of all the Descriptor elements found inside Component elements (where the components are the direct children of the first Item in the given did portion)

The return value is an ArrayList containing XML strings. Each XML string is one of the matching elements.

MXMDIDAccessException with error NO_ELEMENT_PRESENT_ERROR if no element exists which is located at the specified path.

6.1.3.5.5 GetElements

This method returns all of DID elements which conform to the given element path and are contained inside the Item identified by the given item ID, located inside the given did portion.

The itemID parameter is the DID wise unique identifier (a URI), of the target Item element.

The elementPath parameter is a String with a comma separated list which specifies the path to the target element(s). For instance, the path “Component;Descriptor” will lead to the retrieval of all the Descriptor elements found inside Component elements, which in their turn are inside the identified Item element.

The return value is an ArrayList containing XML strings. Each XML string is one of the matching elements.

This method may raise the following exceptions.

MXMDIDAccessException with error ITEM_NOT_PRESENT_ERROR if no Item with the specified id exists within the given DID portion.

6.1.3.5.6 GetDIDElements

This method returns an ArrayList with all the child elements with a name equal to the specified element name, from the given DID element XML string.

The desiredElementName parameter is the name of the desired did element. It may be, for instance, “Component”, “Resource”, etc.

The return value is an XML String containing the specified target did element.

MXMDIDAccessException with error INVALID_ELEMENT_NAME_ERROR of the given DID element name is invalid.

6.1.3.5.7 GetElementContent

This method returns a Hashtable with one single entry where the value is the text or binary content of the given did element, if it is inline, or the reference to the location of such content, if it is not carried in the DID. The key of Hashtable’s entry is a String specifying the type of value that is stored.

The possible values for the key are REFERENCE, TXTCONTENT and BINCONTENT.

The didElement parameter is a String which carries a DID element. That element should be a Resource, a Statement or a Fragment.

The return value a Hashtable with one single entry where the value is the text or binary content of the given did element, if it is inline, or the reference to the location of such content, if it is not carried in the DID. The key of HashTable’s entry is a String specifying the type of value that is stored.

The possible values for the key are REFERENCE, TXTCONTENT and BINCONTENT.

MXMDIDAccessException with error INVALID_DIDPORTION_ERROR ERROR if the given DID portion is for some reason invalid.

6.1.4 DI Presentation

Interface LaserObjectProcessor{

String createDIPresentation(String laserFile, ItemMetadata metadata, String ORCLicense) raises(Exceptions);

}; createDIPresentation():

This method is used to insert content(resource) metadata and OAC license information into an “empty” scene description file, then the recreated scene description file and the OAC license will be packaged into a binary file.

Parameter: laserFile

This parameter is the path of the an “empty” scene description file. It defines the scene description about the metadata elements and OAC license element, but these elements have not real values.

Metadata

This parameter is an ItemMedata object(see A.1). It contains the metadata of a content(or resource), such as title, author, data, description, genre and content ID(or resource ID) and so on. Some values of this metadata will be inserted into the laserFile

ORCLicense

This parameter is the information of the OAC license. It is the path of the OAC license file.

Return value:

Exceptions:

This method will raise the following exceptions:

IOException if occurs error while writing data into file

DocumentException if occurs error while parse the laserFile.

6.2 MPEG-21 File Engine APIs

6.2.1 MP21 File Creation

6.2.1.1 Creating a DCF using ContentBuilder

This method is employed to create an MPEG-21 File (DCF) using an instance of ContentBuilder which has already created a DCI and the information about all the resources in it.

Method Syntax

+ createDCF (): boolean

Java sample code public interface ContentBuilder { public boolean createDCF () throws DCFGenerationException, DCIParsingException, MalformedContentElementException, BadPropertyException; } Method description

This method is used to generate MPEF-21 File (DCF) using an instance of ContentBuilder which has already created a DCI and the information about all the resources in it. The DCF is stored in the file system as a file whose filename is specified as an attribute of class ContentItemMetadata (see Error: Reference source not found), or if this parameter has not been specified, then in the application temporary folder and named as a substring of the Content ID.

Parameters void

Return value

A Boolean value set to true if the DCF was successfully created, false otherwise.

Exceptions

DCFGenerationException If an error occurred while the DCF was created, such as impossible to write to the specified file etc.

BadPropertyException If any of the properties used to configure the ContentBuilder were corrupted or incorrectly set.

DCIParsingException If an error occurs while parsing the Digital Item in order to

6.2.1.2 Set the DI of an MPEG-21 file

Interface DCFMaker

Method Syntax

+ setDCI (dciPath:String):boolean

Java sample code public interface DCFMaker { public boolean setDCI (String dciPath); } Method description

This method is used to add the digital content information(DCI) when create content file. This information is stored in a file.

Parameters dciPath the path of the dci file.

Return value boolean, If the information is added successfully, return true else false.

Exceptions

6.2.1.3 Add a resource to an MPEG-21 file

Interface DCFMaker

Method Syntax

+ addResource (resourcePath:String, itemID:String):boolean

Java sample code public interface DCFMaker { public boolean addResource (String resourcePath, String itemID); } Method description

This method is used to add a resource when create content file. Each resource is specified with an identification.

Parameters resourcePath the path of the resource file which will be added. itemID the identification of the resource when the resource is added to the content file.

Exceptions

6.2.1.4 Creating the MPEG-21 File

Interface DCFMaker

Method Syntax

+ makeFile (dcfPath:String):boolean

Java sample code public interface DCFMaker { public boolean makeFile (String dcfPath); } Method description

This method is used to create a content file using the information and resources in a specified format.

Parameters dcfPath the path of the created content file.

Return value boolean, If the content file is added successfully, return true else false.

Exceptions

6.2.2.1 Extract a DI from an MPEG-21 file

6.2.2.2 Extract a resource from an MPEG-21 file

6.3 REL Engine APIs

6.3.1 License creation

6.3.1.1 Add a Grant to a License

6.3.1.2 Add an Issuer to a license

6.3.1.3 Create a Grant given the Principal, the Right, etc.

6.3.1.4 Create a License

This method is used to generate an ISO/IEC 21000-5-conformant license.

[Editors' note: Need to make this method for creating a Grant, then we need another method, e.g. addGrant() to add more grants to a License]

Method Syntax

+ buildCustomLicense (keyAlias:string, rightElement: RightElement, resource:GovernedContentElement, allConditions:AllConditions):RELLicense

Java sample code public interface ContentBuilder { public RELLicense buildCustomLicense(String keyAlias, RightElement rightElement, GovernedContentElement resource, AllConditions allConditions) throws LicenseGenerationException, SecurityManagerException, BadPropertyException, MalformedContentElementException, UnsupportedFeatureException; } Method description

This method is used to generate a license conformant to ISO/IEC 21000-5. The “issuer” element in the license is automatically generated by the ContentBuilder class by retrieving it from the SecurityManager (See Error: Reference source not found) object passed in the constructor of the ContentBuilder class. The same applies for the “principal”, whose certificate is retrieved from the SecurityManager too using the keyAlias input parameter. If the license is for a ProtectedContentElement, the MasterKey contained in the ProtectedContentElement will be encrypted using the principal’s public key and inserted in the License in the rel-m1x:ProtectedResource element.

Parameters keyAlias An alias for the certificate of the “principal” of the license to be issued, which will be fetched in the SecurityManager (See Error: Reference source not found) object passed in the constructor of the ContentBuilder class. If the keyAlias is null, the issued license will not specify any principal, meaning that the right is granted to everyone. rightElement An object conveying the right to be granted in the license (see Error: Reference source not found). resource An object of class GovernedContentElement (see Error: Reference source

© ISO/IEC 2009 — All rights reserved 23 ISO/IEC CD 23006-2 not found). As ProtectedContentElement (see Error: Reference source not found) extends GovernedContentElement, in case resource is an instance of ProtectedContentElement, the MasterKey contained in the ProtectedContentElement will be encrypted using the principal’s public key and inserted in the License in the rel-m1x:ProtectedResource element. allConditions An object of class AllConditions (see Error: Reference source not found) containing all the conditions to be specified in the license..

Return value

RELLicense (See Error: Reference source not found), a license conformant to ISO/IEC 21000-5 containing one rel-r:grant and the issuer.

Exceptions

LicenseGenerationException (see Error: This exception is thrown if an error occurred while Reference source not found) instantiating the classes involved in the creation of XML data.

SecurityManagerException (see Error: This exception is thrown if the digital certificate of either the Reference source not found) license issuer or the license principal could not be retrieved from the SecurityManager because it does not exist.

BadPropertyException (see Error: This exception is thrown if one or more properties required Reference source not found) by the SecurityManager (e.g. the location of the secure repository where digital certificates reside) were corrupted.

MalformedContentElementException This exception is thrown if the data contained in the resource (see Error: Reference source not found) passed as a parameter was not complete or corrupted (e.g. the Master key for a ProtectedContentElement is missing).

UnsupportedFeatureException (see This exception is thrown if one or more properties required Error: Reference source not found) by the SecurityManager (e.g. the encryption algorithm for encrypting the Master Key with the principal’s public key) is not supported by MXM.

6.3.1.5 Create an ORC License using ContentBuilder

ORC licenses are ISO/IEC 21000-5 Amd 3 licenses equivalent to Creative Commons Error: Reference source not found licenses. This is a high-level method to create an OAC license. It supposes that an object implementing the ContentBuilder interface (see Error: Reference source not found) was initialised with the information required to retrieve the digital certificate of the issuer of the license to be issued.

Method Syntax

+buildORCLicense(resourceID:string, licenseName:string):RELLicense

Java sample code public interface ContentBuilder { public RELLicense buildORCLicense(String resourceID, String licenseName) throws LicenseGenerationException, SecurityManagerException, BadPropertyException, DeviceContextException; } Method description

This method is used to generate a license conformant to ISO/IEC 21000-5 Amd 3 and semantically

24 © ISO/IEC 2009 — All rights reserved equivalent to a Creative Commons Error: Reference source not found license. As the number of Creative Common licenses is a finite number, in order to create an OAC license it is only sufficient to specify the identifier of the governed resource to be inserted in the license, and the specific Creative Commons license name. The “issuer” element in the license is automatically generated by the ContentBuilder class by retrieving it from the SecurityManager (See Error: Reference source not found) object passed in the constructor of the ContentBuilder class.

Parameters resourceID The identifier of the resource to which the Grant in the license applies. licenseName The name of the specific OAC license to be created. All possible names for OAC licenses are defined in the RELLicense (see Error: Reference source not found) interface.

Return value

RELLicense (See Error: Reference source not found), a license conformant to ISO/IEC 21000-5 Amd 3 and semantically equivalent to a Creative Commons Error: Reference source not found license.

Exceptions

LicenseGenerationException (see Error: This exception is thrown if an error occurred while instantiating Reference source not found) the classes involved in the creation of XML data.

SecurityManagerException (see Error: This exception is thrown if the digital certificate of the license Reference source not found) issuer could not be retrieved from the SecurityManager because it does not exist.

BadPropertyException (see Error: This exception is thrown if one or more properties required by Reference source not found) the SecurityManager (e.g. the location of the secure repository where digital certificates reside) were corrupted.

6.3.1.6 Create an ORC License using ORCLicenseBuilder

ORC licenses are ISO/IEC 21000-5 Amd 3 licenses equivalent to Creative Commons Error: Reference source not found licenses.

Interface ORCLicenseBuilder (see Error: Reference source not found)

Method Syntax

+buildORCLicense(resourceID:string, licenseName:string, issuer:Issuer, creatorName:String):RELLicense

Java sample code public interface ORCLicenseBuilder { public RELLicense buildORCLicense(String resourceID, String licenseName, Issuer issuer, String creatorName) throws LicenseGenerationException; } Method description

This method is used to generate a license conformant to ISO/IEC 21000-5 Amd 3 and semantically equivalent to a Creative Commons Error: Reference source not found license. As the number of Creative Common licenses is a finite number, in order to create an OAC license it is only sufficient to specify the identifier of the governed resource to be inserted in the license, and the specific Creative Commons license name. All possible names for OAC licenses are defined in the RELLicense (See Error: Reference source not found) interface.

Parameters

© ISO/IEC 2009 — All rights reserved 25 ISO/IEC CD 23006-2 resourceID The identifier of the resource to which the Grant in the license applies. licenseName The name of the specific OAC license to be created. All possible names for OAC licenses are defined in the RELLicense (see Error: Reference source not found) interface. issuer An object extending the Issuer interface (see Error: Reference source not found), the issuer of the license to be issued. creatorName The name of the creator as it shall appear in the copyrightString of the OAC license.

Return value

RELLicense (See Error: Reference source not found), a license conformant to ISO/IEC 21000-5 Amd 3 and semantically equivalent to a Creative Commons Error: Reference source not found license.

Exceptions

LicenseGenerationException (see Error: This exception is thrown if an error occurred while instantiating Reference source not found) the classes involved in the creation of XML data.

6.3.2 License Access

6.3.2.1 Getting the LicenseId

Interface License (see Error: Reference source not found)

Method Syntax

+getLicenseId(): String

Java sample code public String getLicenseId(String xmlLicenses) throws UnsupportedFeatureException;

Method description

This method is used to extract the r:licenseId from a given license conformant to ISO/IEC 21000-5.

Parameters

A license conformant to ISO/IEC 21000-5 containing one or more rel-r:grant and the issuer

Return value

String (See Error: Reference source not found), the license id.

Exceptions

UnsupportedFeatureException (see This exception is thrown if one or more properties Error: Reference source not found) required by the SecurityManager (e.g. the encryption algorithm for encrypting the Master Key with the principal’s public key) is not supported by MXM.

Note that the license might have more than one title, and it could have several languages etc. In its simplest version, we can consider title as a string.

Method Syntax

+getTitle(): String

Java sample code public String getTitle(String xmlLicenses) throws UnsupportedFeatureException;

Method description

This method is used to extract the title from a given license conformant to ISO/IEC 21000-5. If there are moret han one titles, behaviour is undefined.

Parameters

A license conformant to ISO/IEC 21000-5

Return value

String (See Error: Reference source not found), the license title.

Exceptions

6.3.2.3 Operation to retrieve the inventory

Method Syntax

+getInventory(): String

Java sample code public String getInventory(String xmlLicenses) throws UnsupportedFeatureException;

Method description

This method is used to extract the inventory from a given license conformant to ISO/IEC 21000- 5.

Parameters

A license conformant to ISO/IEC 21000-5

Return value

String (See Error: Reference source not found), the license inventory.

6.3.2.4 Operation to retrieve the list of grants

Method Syntax

+getListofGrants(xmlLicense:string): List

Java sample code public List getListofGrants(String xmlLicenses) throws MalformedContentElementException, UnsupportedFeatureException;

Method description

This method is used to extract the grants from a given license conformant to ISO/IEC 21000-5.

Parameters xmlLicense A license conformant to ISO/IEC 21000-5 containing one or more rel- r:grant and the issuer

Return value

List (See Error: Reference source not found), the list of grants conformant to ISO/IEC 21000-5 contained in the license.

Exceptions

MalformedContentElementException This exception is thrown if the data contained in the (see Error: Reference source not license passed as a parameter was not complete or found) corrupted (e.g. the Master key for a ProtectedContentElement is missing).

6.3.2.5 Operation to retrieve the license issuer

Method Syntax

+getIssuer(xmlLicense:string): RELIssuer

Java sample code public RELIssuer getIssuer(String xmlLicenses) throws MalformedContentElementException, UnsupportedFeatureException;

Method description

Parameters xmlLicense A license conformant to ISO/IEC 21000-5 containing one or more rel- r:grant and the issuer

Return value String (See Error: Reference source not found), the issuer conformant to ISO/IEC 21000-5 contained in the license.

Exceptions

6.3.2.6 Operation to retrieve other information

Method Syntax

+getOtherInfo(): String

Java sample code public String getOtherInfo (String xmlLicenses) throws UnsupportedFeatureException;

Method description

This method is used to extract the r:licenseId from a given license conformant to ISO/IEC 21000-5.

Parameters

A license conformant to ISO/IEC 21000-5 containing one or more rel-r:grant and the issuer

Return value

String (See Error: Reference source not found), the otherInfo.

Exceptions

6.3.3.1 Validate if a License is Issued by a specific Issuer

6.3.4 License authorisation

6.3.4.1 Authorise an REL query against an REL License given a Context

[Editor's note: we need to define the Context interface]

The authorise method is employed to verify whether among a set of licenses in input there is one that may grant to a specific principal a specific right over a specific resource, after verifying that the conditions in the license, if present, are met.

Interface LicenseManager (see Error: Reference source not found)

Method Syntax

+ authorise (resourceID : string, licenses: List, rightElement : RightElement, userAlias : String, password : string): AuthorisationResult

Java sample code public interface LicenseManager { private AuthorisationResult isActionAllowed (String resourceID, List licenses, RightElement rightElement, String userAlias, String password) throws SecurityManagerException, BadPropertyException, LicenseAuthorisationException, UnsupportedFeatureException; } Method description

This method is used to verify whether a License in a list of Licenses may grant to a principal a right over a resource.

Parameters resourceID A string identifying the resource, over which a principal wants a right be granted licenses A vector of objects of type RELLicense (see Error: Reference source not found) representing an rel-r:license rightElement An object conveying the right to be granted in the license (see Error: Reference source not found). userAlias A string necessary to identify the certificate of the principal among those stored in the SecurityManager. password A string value needed to access the SecurityManager certificate repository.

Return value

An array containing all the licenses (see Error: Reference source not found) found in the list of Licenses that grant the user with userAlias and password the right in rightElement for the content item or content element with identifier resourceID.

Exceptions

LicenseAuthorisationException This exception is thrown if problems occurred while generating a query to be validated against the licenses, and parsing the

SecurityManagerException This exception is thrown if the data in the secure repository is corrupted

BadPropertyException This exception is thrown if the properties used to initialise the SecurityManager were not correctly set, hence the SecurityManager was unable to determine the location of the secure repository.

UnsupportedFeatureException This exception is thrown if an error occurred while validating the principal in the license against the principal in the query.

6.4 IPMP Engine APIs

6.4.1 IPMP Information Creation

This section specifies the APIs to create a Digital Item describing a content item containing one or more protected resources, whose protection information is specified according to the MPEG-21 IPMP Components profile defined in ISO/IEC 23000-5. When a protected resource is added to a content item, and the information required to protect it has been set by means of the APIs specified in this section, an application may additionally request MXM to create the protected resource as specified in Error: Reference source not found, and obtain a new identifier for it from a Content Identification Device as specified in Error: Reference source not found.

6.4.1.1 AddIPMPTool

Interface ProtectedContentElement (see Error: Reference source not found)

Method Syntax

+addDRMTool (toolID:string, controlPointIDs:int[], key:byte[], keyFilePathname:string, initDataFilePathname:string):void

Java sample code public interface ProtectedContentElement { public void addDRMTool (String toolID, int[] controlPointIDs, byte[] key, String keyFilePathname, String initDataPathname) ; } Method description

This method is used to specify that a resource part of a content item is protected. When the Digital Item representing the content item is created, a didl:Item corresponding to this resource will be added. This will contain a didl:Component element containing a didl:Resource element, which in turn will contain an ipmpdidl:ProtectedAsset element containing the IPMP information for the resource.

A Resource may be protected by a number of IPMP Tools. Each IPMP Tool can be individually configured using the addDRMTool method. The value of the parameters of this method will be transformed into ISO/IEC 21000-4 elements and added as child of the ipmpdidl:ProtectedAsset.

Parameters toolID The identifier of the IPMP Tool controlPointIDs The list of control points in which the IPMP Tool shall operate, as defined in ISO/IEC 23001-3. key The symmetric encryption key in clear text, to be used to encrypt the resource.

© ISO/IEC 2009 — All rights reserved 31 ISO/IEC CD 23006-2 keyFilePathname The absolute pathname to an XML file containing time-dependent keys to be used to encrypt the resource. The XML file shall be formatted as a KeyData XML message as specified in ISO/IEC 23001-3. This parameter can be null, in which case the resource will not be encrypted, and no KeyData message will be added to the IPMP information related to this IPMP Tool. initDataFilePathname The absolute pathname to an XML file containing initialisation data for the IPMP Tool. The XML file shall be formatted as an InitialiseTool XML message as specified in ISO/IEC 23001-3. In case this parameter is null, no initialisation information will be added to the IPMP information related to this IPMP Tool.

Return value

Exceptions

6.4.1.2 SetMasterKey

Interface ProtectedContentElement (see Error: Reference source not found)

Method Syntax

+setMasterKey (masterKey:byte[], encryptionKeyAlgorithm_JCA:string, encryptionKeyAlgorithm_W3C:string):void

Java sample code public interface ProtectedContentElement { public void setMasterKey(byte[] masterKey, String encryptionKeyAlgorithm_JCA, String encryptionKeyAlgorithm_W3C) ; } Method description

This method is used to specify a Master Key to be used to encrypt all the encryption keys to be inserted in the ipmpmsg:KeyData element, child of the ipmpinfo:InitializationData, set by means of the addDRMTool method (See Error: Reference source not found).

Parameters masterKey The Master Key to be used to encrypt all the symmetric keys set by means of the addDRMTool method (See Error: Reference source not found), to be used by the IPMP Tool to encrypt (creation phase) or decrypt (presentation phase) a resource. All these keys will be encrypted with the specified Master Key before being inserted in the ipmpmsg:KeyData message(s). encryptionKeyAlgorithm_JCA The name of the encryption algorithm to be used to encrypt all the keys with the specified Master Key as known by the platform on which the algorithm runs

32 © ISO/IEC 2009 — All rights reserved encryptionKeyAlgorithm_W3C The name of the encryption algorithm to be used to encrypt all the keys with the specified Master Key as specified in Error: Reference source not found

Return value

Exceptions

6.4.1.3 Method to add a rigths descriptor to an IPMPInfoDescriptor.

Interface ProtectedContentElement??()

Method Syntax

+addRightsDescriptor (IPMPInfoDescriptor:string, RightsDescriptor:string): string

Java sample code public interface ProtectedContentElement?? { public string addRightsDescription(String IPMPInfoDescriptor, String rightsDescriptor) ; } Method description

This method is used to add a Rights Descriptor to an existing IPMPInfoDescriptor.

Parameters

IPMPInfoDescriptor The IPMP element is the XML representation of the element where the Rights Descriptor has to be added. rightsDescriptor The Rights Descriptor is the XML representation of the Rights Descriptor to be added to the IPMP element.

Return value

A string indicating if the operation has been correctly performed. In case of error, a description of the error is returned, OK otherwise.

Exceptions

6.4.1.4 Method to add an element to an IPMPInfoDescriptor

Interface ProtectedContentElement

Method Syntax

+addElementIPMPInfo(IPMPInfoDescriptor: string, element: string):string

Java sample code public interface ProtectedContentElement?? {

This method is used to add an element to an existing IPMPInfoDescriptor.

Parameters

IPMPInfoDescriptor The IPMPInfoDescriptor is the XML representation of the element where the element has to be added.

Element The element is the XML representation of the element to be added to the IPMPInfoDescriptor.

Return value

Exceptions isValid It raises if the element is not valid.

6.4.1.5 Method to add an element to an IPMPGeneralInfoDescriptor

Method Syntax

+addElementIPMPGeneralInfo(IPMPGeneralInfoDescriptor: string, element: string):string

Java sample code public interface ProtectedContentElement?? { public string addElementIPMPGeneralInfo(String IPMPGeneralInfoDescriptor, String element) ; } Method description

This method is used to add an element to an existing IPMPGeneralInfoDescriptor.

Parameters

IPMPGeneralInfoDescriptor The IPMPGeneralInfoDescriptor is the XML representation of the element where the element has to be added.

Element The element is the XML representation of the element to be added to the IPMPGeneralInfoDescriptor.

Return value

Exceptions isValid It raises if the element is not valid.

6.4.2.1 Parse an XML IPMP Message

6.4.2.2 Method to access IPMP Tool information from an IPMPInfoDescriptor

Method Syntax

+getIPMPToolInfo(IPMPInfoDescriptor: string): array of string

Java sample code public interface ProtectedContentElement?? { public string [] getIPMPToolInfo(String IPMPInfoDescriptor); } Method description

This method is used to get the information from an IPMP Tool contained in an IPMPInfoDescriptor.

Parameters

IPMPInfoDescriptor The IPMPInfoDescriptor is the XML representation of the descriptor from where the IPMP tool has to be obtained.

Return value

A string array with the whole information of the IPMP tools in XML format.

Exceptions

6.5 Access RightsDescriptor from an IPMPInfoDescriptor

6.5.1.1 Method to access RightsDescriptor from an IPMPInfoDescriptor

Method Syntax

+getRightsDescriptor (IPMPInfoDescriptor: string):array of string

Java sample code public interface ProtectedContentElement?? { public string [] getRightsDescriptor(String IPMPInfoDescriptor); } Method description

This method is used to get the Rights Descriptor in an IPMPInfoDescriptor.

Parameters

IPMPInfoDescriptor The IPMPInfoDescriptor is the XML representation of the descriptor from where the Rights Descriptor has to be obtained.

Return value

Exceptions

6.5.1.2 Method to access any information from any IPMP element

Method Syntax

+parseIPMPElement (elementName: string):string

Java sample code public interface ProtectedContentElement?? { public string parseIPMPElement(String elementName); } Method description

This method is used to extract the information associated to the element identified by the elementName parameter.

Parameters elementName The name of the element to be parsed and obtained.

Return value

A string with the whole information of the element identified by elementName.

Exceptions

6.5.1.3 Create an XML IPMP Message

6.5.2 Resource Protection

6.5.2.1 ProtectResource

A resource can be protected by invoking the protectResource method specified below. After being protected, the protected resource requires a new identifier, which can be obtained by invoking the method identifyProtectedResource also specified below.

Method Syntax

+ protectResource (resourceInfo:ProtectedContentElement):boolean

Java sample code public interface ContentBuilder { public boolean protectResource(ProtectedContentElement resourceInfo) throws MediaFrameworkException, MalformedContentElementException, UnsupportedFeatureException, IOException, DRMProcessorException; } Method description

This method is used to protect (e.g. encrypt) a resource. The method assumes that an object of type

Parameters resourceInfo An instance of class ProtectedContentElement (see Error: Reference source not found) containing all the information describing the resource and how it shall be protected.

Return value true if the resource was successfully protected, false otherwise.

Exceptions

MediaFrameworkException (see Error: This exception is thrown if the MediaFramework to be used to Reference source not found) protect the resource was not found or could not be instantiated.

MalformedContentElementException This exception is thrown if the information contained in the (see Error: Reference source not found) ProtectedContentElement object given in input was not complete, not valid or leading to an ambiguous interpretation, hence MXM was unable to protect the resource.

UnsupportedFeatureException (see This exception is thrown if the information contained in the Error: Reference source not found) ProtectedContentElement object given in input was not supported by MXM (e.g. encryption algorithm not supported).

IOException (see Error: Reference This exception is thrown if problems were detected while writing source not found) the protected resource in a new file.

DRMProcessorException (see Error: This exception is thrown if one of the IPMP Tools to be used to Reference source not found) protect the resource was not found or could not be instantiated.

6.5.2.2 IdentifyProtectedResource

The identifyProtectedResource method is used to identify a resource after it has been protected (e.g. encrypted). This method works at a higher level of that that specified in Error: Reference source not found, as the ProtectedContentElement given in input, if the operation succeeds, will already contain the new identifier and its hash properly set.

Method Syntax

+ identifyProtectedResource (protectedContentElement:ProtectedContentElement, cidURL:String):String

Java sample code public interface ContentBuilder { public String identifyProtectedResource (ProtectedContentElement protectedContentElement, String cidURL) throws ContentIdentificationException, IOException, UnsupportedFeatureException, ServiceException; } Method description

This method is used to identify a resource after this has been protected (e.g. encrypted), hence a new file has been created. The method assumes that an object of type ProtectedContentElement was previously initialised with the information required in order to allow MXM to protect the resource accordingly

Parameters

© ISO/IEC 2009 — All rights reserved 37 ISO/IEC CD 23006-2 protectedContentElement An instance of class ProtectedContentElement (see Error: Reference source not found) containing all the information describing the resource and how it shall be protected. cidURL The URL of the service to be invoked in order to request an identifier for the new resource.

Return value

The resource identifier if the resource was successfully identified, false otherwise.

Exceptions

ContentIdentificationException This exception is thrown if an error occurred while creating the (see Error: Reference source not message to request the new identifier, or if the cidURL input found) parameter is malformed.

UnsupportedFeatureException This exception is thrown if the information contained in the (see Error: Reference source not ProtectedContentElement object given in input was not supported by found) MXM (e.g. hash algorithm not supported).

IOException (see Error: Reference This exception is thrown if problems were detected while calculating source not found) the hash value of the resource file.

ServiceException (see Error: This exception is thrown if an error occurred while communicating Reference source not found) with the content identification service.

6.6 IPMP Tool instantiation

6.6.1.1 Method to instantiate a specific IPMP Tool having specific characteristics in a specific Control Point.

Method Syntax

+instantiateIPMPTool (IPMPTool: string):int

Java sample code public interface ProtectedContentElement?? { public int instantiateIPMPTool(String IPMPTool); } Method description

This method is used to instantiate an IPMPTool from its XML description.

Parameters

IPMPTool The information of the IPMP Tool to be instantiated.

Return value

An integer with value 0 if the tool can be instantiated and different that 0 otherwise, to indicate

Exceptions

6.6.1.2 Method to Initialise a specific IPMP Tool already instantiated with specific initialisation data.

Method Syntax

+initialiseIPMPTool (tool: IPMPTool):int

Java sample code public interface ProtectedContentElement?? { public int initialiseIPMPTool(IPMPTool tool); } Method description

This method is used to initialise an IPMPTool.

Parameters tool A class representing the IPMPTool to be initialised

Return value

An integer with value 0 if the tool can be instantiated and different that 0 otherwise, to indicate the error.

Exceptions

6.7 Media Framework Engine APIs

6.7.1 Generic Elementary Stream

6.7.1.1 Creation

6.7.1.1.1 EncodeElementaryStream

Interface ResourceManager (see Error: Reference source not found)

Method Syntax

+ encodeElementaryStream (es:ElementaryStream[]):boolean

Java sample code public interface ResourceManager { public boolean encodeElementaryStream (ElementaryStream[] es, URL location) throws ResourceBuilderException } Method description

This method is used to create (e.g. encode) a resource. The method assumes that an object of type ElementaryStream[] was previously initialised (or retrived from a demuxResource call) with the

Parameters es A set of instances of class ElementaryStream containing all the information describing the ElementaryStream and how it shall be encoded/decoded.

Return value true if the resource was successfully created, false otherwise.

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourseBuilder failed Reference source not found) creating the Resource

6.7.1.1.2 AddEncoderInformation

Interface ElementaryStream (see Error: Reference source not found)

Method Syntax

+addEncoderInformation (bitrate:double, algorithmName:string):void

Java sample code public interface ElementaryStream { public void addEncoderInformation(Double bitrate, String algorithmName) throws EncoderException; } Method description

This method is used to specify how an ElementaryStream has to be encoded. When an application create a Resource, an Encoder labelled algorithmName has to be instantiated in the media chain before the Muxing and Composition phase. If no EncoderInformation was specified, no Encoder has to be instantiated in the media chain

Parameters bitrate The bitrate the encoder has to use algorithmName The algorithm's name of the encoder [Editor's note: which names are allowed?]

Return value

Exceptions

EncoderException (see This exception is thrown if the algorithmName is not feasible to the Error: Reference ElementaryStream. source not found)

6.7.1.3 Decoding

6.7.1.4 Rendering

6.7.1.5 Adaptation

[Editor's note: use one table for each method, make consistent with the rest of the document]

Adapting resources according to terminal environment description

UML Specifications

Method Syntax for Interface MXMResAdaptDescr

+ adaptResByDescr (namespaceURI:string, ued:string):boolean

Class Diagram

Java sample code implementation public interface MXMResAdaptDescr

public boolean adaptResByDescr(String namespaceURI,String ued) throws MXMDescrException;

Method adaptResByDescr description

This method is used to adapt the resource by using the usage environment description (ued) identified by the namespace namespaceURI. The ued shall provide a description of the usage environment where the resource is consumed.

namespaceURI

The namespaceURI parameter is a String containing the URI of the namespace identifying the usage environment description.

The ued parameter is a String containing the usage environment description.

Return value

The return value is true if the adaptation was successful, otherwise false is returned.

Exceptions

MXMDescrException with NOT_SUPPORTED_ERROR.

MXMDescrException with INVALID_DESCRIPTION_ERROR.

6.7.2.1 Creation

6.7.2.2 Editing

6.7.2.3 Decoding

6.7.2.4 Rendering

6.7.3 Audio APIs

6.7.3.1 Creation

6.7.3.2 Editing

6.7.3.3 Decoding

6.7.3.4 Rendering

6.7.4 Video APIs

6.7.4.1 Creation

6.7.4.2 Editing

6.7.4.3 Decoding

6.7.4.4 Rendering

6.7.5 Reconfigurable Video APIs

6.7.5.1 Creation

6.7.5.2 Decoding

6.7.5.3 Engine-specific APIs

6.7.5.3.1 AddRVCDecoder

Building an RVC decoder or receiving/downloading a decoder plug-in

Interface RVCDecoderManager (see Error: Reference source not found)

Method Syntax

+addRVCDecoder (RVCType:string, serviceprovider:URL):void

Java sample code public interface RVCDecoderManager { public void addRVCDecoder(String RVCType, URL serviceprovider) throws DecoderManagerExceptions; } Method description

This method is used to configure a new RVC decoder as player plug-in or receive/download a decoder

© ISO/IEC 2009 — All rights reserved 43 ISO/IEC CD 23006-2 plug-in from web URL or service provider. It supports both “embedded” (where the new RVC decoder configuration plug-in is generated inside the MXM media receiver) and “centralized” (where the new RVC decoder configuration plug-in is received by the service provider or downloaded by a web URL) use cases.

Parameters

RVCType The identifier of a RVC configuration

Serviceprovider The URL of the service provider server

Return value

Exceptions

NewDecoderConfigurat This exception is thrown if the RVCDecoderManager process failed in ionFailedException creating/downloading the required RVC decoder plug-in (see Error: Reference source not found)

ServiceProviderConne This exception is thrown if the RVCDecoderManager process failed in ctionException (see creating/downloading the required RVC decoder plug-in for failing connection Error: Reference with the service provider server source not found)

6.7.5.3.2 AddDecoderInformation

This section specifies the APIs to describe the algorithm_name (Decoder) that has to be applied to an ElementaryStream.

Interface ElementaryStream (see Error: Reference source not found)

Method Syntax

+addDecoderInformation (algorithName:string):void

Java sample code public interface ElementaryStream { public void addDecoderInformation(String algorithmName) throws DecoderException; } Method description

This method is used to specify how a ElementaryStream has to be decoded. When an application consume a Resource, a Decoder labelled algorithmName has to be instantiated in the media chain before the Composition and Rendering phase. If no DecoderInformation are specified, the MXM framework has to be able to instantiate the decoder it holds that best fits with the ElementaryStream characteristics. Parameters algorithmName The algorithm's name of the encoder

Return value void

DecoderException This exception is thrown if the algorithmName is not feasible to the (see Error: Reference ElementaryStream characteristics. source not found)

6.7.6 Muxed Content APIs

6.7.6.1 Creation

6.7.6.2 Editing

6.7.6.3 Access

[Editor's note: use tables for each method to keep consistency with the rest of the document, add exceptions and interfaces to annex]

The following interface defines the API for loading an MP4 file.

UML Specifications

Method syntax for interface MXMFileFormat

+LoadMP4(url : string, type : outputType) : boolean

+GetRARfromMETA(alloc : boolean, buff : string, size : int) : boolean

+GetXMLfromMETA(alloc : boolean, buff : string, size : int) : boolean

Class Diagram

C++ sample code implementation interface MXMFileFormat {

Boolean LoadMP4( in String url, out outputType type) raises(MXMFileFormatException);

Boolean GetRARfromMETA(in Boolean alloc, out String buff, out int size,) raises(MXMFileFormatException);

Boolean GetXMLfromMETA(in Boolean alloc, out String buff, out int size,) raises(MXMFileFormatException);

LoadMP4File()

This method is used to load and process (demux and decode) an MP4 file.

Parameters

The url parameter is a String containing the URL from where the MPEG-4 data is read.

The type parameter is an output parameter ot type outputType. The structure of outputType is the following:

enum outputType

NOTHING = -1,

OUT_VB = 0,

OUT_IFS= 1

// to be completed by other types

type is 0 if the geometry data from the MP4 file is proposed as a flat vertex and index buffer or 1 of it is proposed as a IndexedFaceSet structure.

Return value

The return value is true if the operation was successful, otherwise false is returned.

Exceptions

MXMFileFormatException with NOT_SUPPORTED_ERROR.

MXMFileFormatException with INVALID_FILE_ERROR.

Method GetRARfromMETA description

GetRARfromMETA()

This method gives access to the RAR version of the META atom of the MP4 file. One of usages is for accessing scene graph data encapsulated as described in ISO/IEC 14496-25.

Parameters

If alloc is true, the buffer is allocated inside the function, If alloc is false, the buffer should be allocated before calling the function

size specifies the size of buff

Return value

Exceptions

Method GetXMLfromMETA description

GetXMLfromMETA()

This method gives access to the XML version of the META atom of the MP4 file. One of usages is for accessing scene graph data encapsulated as described in ISO/IEC 14496-25.

Parameters

buff contains the META atom in RAR form

size specifies the size of buff

Return value

Exceptions

6.7.6.4 Rendering

6.7.6.4.1 Mute

Method Syntax

+ mute ():boolean

Java sample code public interface ResourceManager { public boolean mute () throws ResourceBuilderException } Method description

This method is used to mute the audio renderer. The method assumes that a media chain was previously instantiated

Parameters

Return value true if the resource was successfully muted, false otherwise.

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) mute the audio renderer

6.7.6.4.2 Un-Mute

Method Syntax

+ unMute (volume: float):boolean

Java sample code public interface ResourceManager { public boolean unMute (Float volume) throws ResourceBuilderException } Method description

This method is used to unmute the audio renderer and to set accord lying the new volume level (in percent). The method assumes that a media chain was previously instantiated

Parameters

Volume New volume, in percent

Return value true if the resource was successfully unmuted, false otherwise.

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) unmute the audio renderer

6.7.6.4.3 SetVolume

+ setVolume (volume: float):boolean

Java sample code public interface ResourceManager { public boolean setVolume (Float volume) throws ResourceBuilderException } Method description

This method is used to set the volume (in percent) of the audio renderer. The method assumes that a media chain was previously instantiated

Parameters

Volume New volume, in percent

Return value true if the volume was successfully stored, false otherwise.

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to set Reference source not found) the volume of the audio renderer

6.7.6.5 Engine-specific APIs

6.7.6.5.1 Start

Method Syntax

+ start():boolean

Java sample code public interface ResourceManager { public boolean start() throws ResourceBuilderException } Method description

This method is used to start the media chain to process. The method assumes that a media chain was previously instantiated

Parameters

Return value true if the resource was successfully started, false otherwise.

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to start Reference source not found) the media chain

Method Syntax

+ stop ():boolean

Java sample code public interface ResourceManager { public boolean stop () throws ResourceBuilderException } Method description

This method is used to stop the media chain to process. The method assumes that a media chain was previously instantiated and started

Parameters

Return value true if the resource was successfully stopped, false otherwise.

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) stop the Resource

6.7.6.5.3 Pause

Method Syntax

+ pause ():boolean

Java sample code public interface ResourceManager { public boolean pause () throws ResourceBuilderException } Method description

This method is used to pause the media chain to process. The method assumes that a media chain was previously instantiated and started

Parameters

Return value true if the resource was successfully paused, false otherwise.

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) pause the Resource

Method Syntax

+ destroy ():boolean

Java sample code public interface ResourceManager { public boolean destroy () throws ResourceBuilderException } Method description

This method is used to destroy the media chain and deallocate any resources. The method assumes that a media chain was previously instantiated

Parameters

Return value true if the media chain was successfully destroyed, false otherwise.

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) destory the media chain

6.7.6.5.5 SetMediaTime

Method Syntax

+ setMediaTime (time:double):boolean

Java sample code public interface ResourceManager { public boolean setMediaTime (Double time) throws ResourceBuilderException } Method description

This method is used to set the time, in milliseconds, of the media chain. The method assumes that a media chain was previously instantiated

Parameters

Time Time in milliseconds that specify the new media chain position

Return value true if the time was successfully stored, false otherwise.

Exceptions

© ISO/IEC 2009 — All rights reserved 51 ISO/IEC CD 23006-2 ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to set Reference source not found) the new position of the media chain

6.7.6.5.6 GetDuration

Method Syntax

+ getDuration ():double

Java sample code public interface ResourceManager { public Double getDuration () throws ResourceBuilderException } Method description

This method is used to query the duration, in milliseconds, of the resource is currently playing in the media chain. The method assumes that a media chain was previously instantiated

Parameters

Return value

The duration of the resource, in milliseconds

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) query the media duration

6.7.6.5.7 getMediaTime

Method Syntax

+ getMediaTime ():double

Java sample code public interface ResourceManager { public Double getMediaTime () throws ResourceBuilderException } Method description

This method is used to query the current media position, in milliseconds, of the resource is currently playing in the media chain. The method assumes that a media chain was previously instantiated

Parameters

Return value

The current media time of the resource, in milliseconds

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) query the media position

6.7.6.5.8 IsRunning

Method Syntax

+ isRunning ():boolean

Java sample code public interface ResourceManager { public boolean isRunning () throws ResourceBuilderException } Method description

This method is used to query the status of the media chain. The method assumes that a media chain was previously instantiated

Parameters

Return value true if the resource is currently running, false otherwise

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) query the media chain status

6.7.6.5.9 AddMediaChainListener

Method Syntax

+ addMediaChainListener (listener MediaChainListener):boolean

Java sample code public interface ResourceManager { public boolean addMediaChainListener (MediaChainListener listener) throws ResourceBuilderException } Method description

This method is used by an Application to be notified on the Event throwed by the media chain

Parameters listener A class that implement the MediaChainListener

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourceManager failed to Reference source not found) add the media chain listener

6.7.6.5.10 RemoveMediaChainListener

Method Syntax

+ removeMediaChainListener (listener MediaChainListener):boolean

Java sample code public interface ResourceManager { public boolean removeMediaChainListener (MediaChainListener listener) throws ResourceBuilderException } Method description

This method is used by an Application to remove the listener from the list of the class has to be notified on the Event throwed by the media chain

Parameters listener A class that implement implement the MediaChainListener

Return value true if the listener was removed, false otherwise

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourseBuilder failed to Reference source not found) remove the media chain listener

6.7.6.5.11 AddMuxerInformation

Method Syntax

+addMuxerInformation (mimeType:string):void

Java sample code public interface ResourceManager { public void addMuxerInformation(String mimeType) throws MuxerException; } Method description

Parameters mimeType The mimetype of the Resource

Return value

Exceptions

ResourceBuilderExcept This exception is thrown if the mimetype is not compatible with the ion (see Error: ResourceManager characteristic Reference source not found)

6.7.6.5.12 AddDestination

Method Syntax

+ addDestination(es:ElementaryStream[], ipaddresses:URL[]):boolean

Java sample code public interface ResourceManager { public String addDestination (ElementaryStream[] es, URL[] ipaddresses) throws ResourceBuilderException } Method description

This method is used to forwarding (streaming) to a specified URLs the passed ElementaryStreams.

Parameters es A set of instance of class ElementaryStream containing all the information describing the ElementaryStream and how it shall be encoded/decoded. ipaddresses A set of URLs where the Elementary Stream has to be streamed

Return value true if the resource was successfully consumed, false otherwise.

Exceptions

ResourceBuilderException(see Error: This exception is thrown if the ResourseBuilder failed consuming Reference source not found) the Resource

6.7.6.5.13 ReceiveStreams

Method Syntax

Java sample code public interface ResourceManager { public ElementaryStream[] receiveStreams (int[] ports) throws ResourceBuilderException } Method description

This method is used to receive (from streaming) from a specified set of local ports a set of ElementaryStream

Parameters ports A set of ports where the ElementaryStreams can be retrieved

Return value

A set of instance of class ElementaryStreams containing all the information describing the ElementaryStream and how it shall be encoded/decoded.

Exceptions

ResourceBuilderException(see Error: This exception is thrown if the ResourseBuilder failed Reference source not found) consuming the Resource

6.7.6.5.14 Demux

Method Syntax

+ demux(location URL):ElementaryStream[]

Java sample code public interface ResourceManager { public ElementaryStream[] demux(URL location) throws ResourceBuilderException } Method description

This method is used to consume demux a resource, specified by an URL.

Parameters location It specifyies the source of the resource.

Return value

A set of instance of class ElementaryStream containing all the information describing the ElementaryStream and how it shall be encoded/decoded.

Exceptions

ResourceBuilderException(see Error: This exception is thrown if the ResourseBuilder failed creating Reference source not found) the Resource

6.7.7.1 Creation

This API is used for creating the geometric transformation of the 2D object inside the scene

6.7.7.2 Editing

6.7.7.3 Decoding

This API is used for retrieving the geometric transformation of the 2D object inside the scene (position, orientation and scale)

6.7.8 2D Graphics Primitives APIs

6.7.8.1 Creation

6.7.8.2 Editing

6.7.8.3 Decoding

6.7.8.4 Rendering

6.7.8.5 CreateDIPresentation

Interface LaserObjectProcessor

Method Syntax

+ createDIPresentation (laserFile:String, metadata:MetadataInterface,ccLicense:String):String

Java sample code public interface LaserObjectProcessor { public void createDIPresentation (String laserFile, MetadataInterface metadata, String ccLicense) throws IOException, DocumentException; } Method description

This method is used to insert content(resource) metadata and cc license information into an “empty” scene description file which should be created by an authoring tool. Then this scene description file which has been inserted with metadata and the cc license will be packaged into a binary file.

Parameters laserFile The path of the an “empty” scene description file. It defines the scene description about the metadata elements and cc license element, but these elements have not real values. metadata The MetadataInterface(see Error: Reference source not found) object, some values of this metadata will be inserted into the laserFile ccLicense The path of the cc License file

Return value

Exceptions

IOException This exception is thrown if occurs error while writing data into a file.

DocumentException This exception is thrown if occurs error while parse the laserFile.

6.7.8.6 Init

Interface LaserPresentation

Method Syntax

+ init (laserFile:String):void

Java sample code public interface LaserPresentation { public void inti (String laserFile) throws IOException, DocumentException; } Method description

This method is used to parse a laser File with path laserFile. It only parses the media part of the scene file and stores them.

Parameters laserFile The path of the scene description file.

Return value void

Exceptions

IOException This exception is thrown if occurs error while writing data into file.

DocumentException This exception is thrown if occurs error while parse the laserFile.

6.7.8.7 SetPresentationPanel

Method Syntax

+ setPresentationPanel (panel:Panel):void

Java sample code public interface LaserPresentation { public void setPresentationPanel (Panel panel); } Method description

This method is used to set a panel in which the scene will be presented.

Return value void

Exceptions

6.7.8.8 showNotify

Method Syntax

+ showNotify ():void

Java sample code public interface LaserPresentation { public void showNotify (); } Method description

This method is used to parse the content scene and present the objects in a panel. It will start a thread to implement this process.

Parameters

Return value void

Exceptions

6.7.9 3D Scene Graph APIs

6.7.9.1 Creation

6.7.9.2 Editing

6.7.9.3 Decoding

6.7.10 3D graphics primitives APIs

[Editor's note: use tables for each method to keep consistency with the rest of the document, add exceptions and interfaces to annex]

© ISO/IEC 2009 — All rights reserved 59 ISO/IEC CD 23006-2 6.7.10.1 Geometry related API The following interface defines the Geometry related API when the geometry is encoded by using the BIFS node "IndexedFaceSet" or by the 3DMC elementary stream.

UML Specifications

Method syntax for interface MXMGeometry

+GetVBandIBSize() : int

+GetVBandIB (alloc : boolean, buff : string) : boolean

+GetBIFSSize(ID : string) : Integer

+GetBIFS(alloc : boolean, ID : string, buff : string) : boolean

+Get3DMCCount() : Integer

+Get3DMCSize(ID : string) : Integer

+Get3DMC(alloc : boolean, ID : string, buff : string) : boolean

C++ sample code implementation interface MXMGeometry {

// Methods

int GetVBandIBSize () raises(MXMGeometryException);

Boolean GetVBandIB (in Boolean alloc, out String buff) raises(MXMGeometryException);

integer GetBIFSSize (in String ID) raises(MXMGeometryException);

Boolean GetBIFS (in Boolean alloc, in String ID, out String buff) raises(MXMGeometryException);

integer Get3DMCCount () raises(MXMGeometryException);

integer Get3DMCSize (in String ID) raises(MXMGeometryException);

Boolean Get3DMC (in Boolean alloc, in String ID out String buff); raises(MXMGeometryException);

6.7.10.1.1 GetVBandIBSize

GetVBandIBSize()

This method returns the size of the decoded vertex buffer and index buffer structure when the geometry is specified in BIFS or in 3DMC.

Parameters

Return value

The return value is an integer specifying the size of the buffer

Exceptions

MXMGeometryException with NOT_SUPPORTED_ERROR.

MXMGeometryException with INVALID_SCENE_ERROR.

6.7.10.1.2 GetVBandIB

GetVBandIB ()

This method gives access to the decoded vertex buffer and index buffer structure when the geometry is specified in BIFS or in 3DMC.

Parameters

buff contains the decoded mesh buffer (vertex buffer and index buffer structure) defined as following:

MeshBuffer

Int(4) sizeMeshData;

Int(1) vbCount;

for ( 1 .. vbCount )

VertexBufferDesc();

VertexBufferDesc

Int(4) sizeVertexBufferDesc;

VertexBuffer();

Int(1) ibCount;

For ( 1.. ibCount )

IndexBuffer();

VertexBuffer

Int(4) sizeVertexBuffer;

Int(1) description;

Int(4) vertexCount;

For ( 1 .. vertexCount )

Float(4) x ;

Float(4) y ;

Float(4) z ;

If ( boneWeights )

Float(4) w0;

Float(4) w1;

Float(4) w2;

Float(4) w3;

Int(1) boneIndex0;

Int(1) boneIndex1;

Int(1) boneIndex2;

Int(1) boneIndex3;

Int(4) normalCount;

For ( 1 .. normalCount)

Float(4) nx ;

Float(4) ny ;

Float(4) nz ;

Int(4) texCoordCount;

For ( 1 .. texCoordCount)

Float(4) u ;

IndexBuffer

Int(4) sizeIndexBuffer;

Int(4) appearanceID;

Int(4) coordIndexCount;

For ( 1 .. coordIndexCount )

Int(4) index;

Int(4) texCoordIndexCount;

For ( 1 .. texCoordIndexCount)

Int(4) index;

Int(4) normalIndexCount;

For ( 1 .. normalIndexCount)

Int(4) index;

Return value

Exceptions

The following methods should be used the geometry is encoded by using the elementary stream 3DMC.

6.7.10.1.3 Get3DMCSize

Get3DMCSize ()

This method returns the size of the BIFS buffer.

Parameters

a unique identifier of the BIFS stream

Return value

The return value is an integer specifying the size of the BIFS buffer

Exceptions

6.7.10.1.4 Get3DMC

Get3DMC()

This method gives access to the encoded BIFS buffer.

Parameters

a unique identifier of the BIFS stream

buff contains the encoded BIFS buffer

6.7.10.1.5 Get3DMCCount

Get3DMCCount()

This method indicates the number of 3DMC tracks in an MP4 file

Parameters

The return value is an integer specifying the number of 3DMC tracks

Exceptions

MXMGeometryException with INVALID_GEOMETRY_ERROR.

6.7.10.1.6 Get3DMCSize

Get3DMCSize ()

This method returns the size of the 3DMC buffer.

Parameters

a unique identifier of the 3DMC stream

Return value

The return value is an integer specifying the size of the 3DMC buffer

Exceptions

6.7.10.1.7 Get3DMC

Get3DMC()

This method gives access to the encoded 3DMC buffer.

Parameters

a unique identifier of the 3DMC stream

buff contains the encoded 3DMC buffer

6.7.10.1.8 FreeBuffer

FreeBuffer()

Parameters

The reference to the buffer to free

Return value

Exceptions

6.7.10.2 Appearance related API

The following interface defines the Appearance related API when it is encoded by using the BIFS node "Appearance".

UML Specifications

Method syntax for interface MXMAppearance

+GetAppBufferSize() : Integer

+GetAppBuffer(alloc : boolean, buff : string) : boolean

+FreeBuffer() : boolean

C++ sample code implementation interface MXMAppearance {

// Methods

integer GetAppBufferSize () raises(MXMAppearanceException);

Boolean GetAppBuffer (in Boolean alloc, out String buff) raises(MXMAppearanceException);

boolean FreeBuffer() raises(MXMAppearanceException);

6.7.10.2.1 GetAppBufferSize

GetAppBufferSize ()

This method returns the size of the decoded appearance buffer structure .

Parameters

The return value is an integer specifying the size of the buffer

Exceptions

MXMAppearanceException with NOT_SUPPORTED_ERROR.

MXMAppearanceException with INVALID_SCENE_ERROR.

6.7.10.2.2 GetAppBuffer

GetAppBuffer ()

This method gives access to the decoded appearance buffer structure.

Parameters

buff contains the decoded appearance buffer structure defined as following

AppearanceBuffer

Int(4) sizeAppearanceData;

Int(1) appearanceCount;

for ( 1 .. appearanceCount)

Appearance();

Appearance

Int(4) textureID;

Int(1) haveMaterial;

If (haveMaterial = 1 )

Color diffuseColor;

Color specularColor;

Float(4) transparency;

Float(4) ambientIntensity;

Float(4) shininess;

Float(4) red;

Float(4) green;

Float(4) blue;

Return value

Exceptions

MXMAppearanceException with INVALID_SCENE_ERROR.

6.7.10.2.3 Freebuffer

FreeBuffer()

This method frees the memory allocated for the buffer transmitted in the parameter.

Parameters

buff the reference to the buffer to free

Return value

Exceptions

6.7.10.3 Texture-related API

The following interface defines the Texture (Static Image) related API when.

UML Specifications

Method syntax for interface MXMTexture

+GetTextureCount() : Integer

+GetTextureSize(ID : string) : Integer

+GetTexture(alloc : boolean, buff : string, type : textureType) : boolean

+GetDecodedTexture(alloc : boolean, buff : string) : boolean

C++ sample code implementation interface MXMTexture {

integer GetTextureCount () raises(MXMTextureException);

integer GetTextureSize (in String ID) raises(MXMTextureException);

Boolean GetTexture (in Boolean alloc, out String buff, out textureType type) raises(MXMTextureException);

Boolean GetTextureResolution (in String ID, out integer W, out integer H) raises(MXMTextureException);

Boolean GetDecodedTexture (in Boolean alloc, out String buff) raises(MXMTextureException);

Boolean FreeBuffer() raises(MXMTextureException);

6.7.10.3.1 GetTextureCount

GetTextureCount ()

This method indicates the number of static image tracks in an MP4 file

Parameters

Return value

The return value is an integer specifying the number of static image tracks

Exceptions

MXMTextureException with NOT_SUPPORTED_ERROR.

6.7.10.3.2 GetTextureSize

GetTextureSize ()

This method returns the size of the encoded texture buffer.

Parameters

a unique identifier of the texture stream

Return value

The return value is an integer specifying the size of the texture buffer

Exceptions

MXMTextureException with INVALID_TEXTURE_ERROR.

6.7.10.3.3 GetTexture

GetTexture()

This method gives access to the encoded texture buffer.

Parameters

buff contains the encoded texture buffer

6.7.10.3.4 GetTextureResolution

GetTextureResolution()

This method gives access to the resolution of the static image.

Parameters

The height of the image

Return value

Exceptions

6.7.10.3.5 GetDecodedTexture

GetDecodedTexture()

This method gives access to the decoded image buffer.

Parameters

a unique identifier of the image stream

buff contains the decoded image buffer defined as a vector of RGBA pixels.

Return value

Exceptions

FreeBuffer()

This method frees the memory allocated for the buffer transmitted in the parameter

Parameters

Return value

Exceptions

6.7.10.4 Animation related API

The following interface defines the Animation related API when it is encoded by using the elementary stream BBA or FAMC.

UML Specifications

Method syntax for interface MXMAnimation

+GetBBACount() : Integer

+GetBBASize(ID : string) : Integer

+GetBBA(alloc : boolean, buff : string) : boolean

+GetDecodedBBA(alloc : boolean, buff : string) : boolean

+GetFAMCCount() : Integer

+GetFAMCSize(ID : string) : Integer

+GetFAMC(alloc : boolean, buff : string) : boolean

+GetDecodedFAMC(alloc : boolean, buff : string) : boolean

Class Diagram

integer GetBBACount () raises(MXMAnimationException);

integer GetBBASize (in String ID) raises(MXMAnimationException);

Boolean GetBBA (in Boolean alloc, out String buff raises(MXMAnimationException);

Boolean GetDecodedBBA (in Boolean alloc, out String buff) raises(MXMAnimationException);

integer GetFAMCCount () raises(MXMAnimationException);

integer GetFAMCSize (in String ID) raises(MXMAnimationException);

Boolean GetFAMC (in Boolean alloc, out String buff raises(MXMAnimationException);

Boolean GetDecodedFAMC (in Boolean alloc, out String buff) raises(MXMAnimationException);

Boolean FreeBuffer () raises(MXMAnimationException);

6.7.10.4.1 GetBBACount

GetBBACount ()

This method indicates the number of BBA tracks in an MP4 file

Parameters

Return value

The return value is an integer specifying the number of BBA tracks

Exceptions

MXMAnimationException with NOT_SUPPORTED_ERROR.

MXMAnimationException with INVALID_ANIMATION_ERROR.

6.7.10.4.2 GetBBASize

GetBBASize ()

This method returns the size of the encoded BBA buffer.

Parameters

a unique identifier of the BBA stream

Return value

The return value is an integer specifying the size of the BBA buffer

Exceptions

6.7.10.4.3 GetBBA

Method GetBBA description

GetBBA()

This method gives access to the encoded BBA buffer.

Parameters

buff contains the encoded BBA buffer

GetDecodedBBA()

This method gives access to the decoded BBA buffer.

Parameters

buff contains the decoded BBA buffer defined as following

BBABuffer

Int(4) sizeAnimationBuffer ;

Int(1) hasHierarchy ;

If (hasHierarchy)

Hierarchy h;

Int(4) NoOfFrames ;

For (i=1 to NoOfFrames )

Frame f[i];

Hierarchy

Int(4) sizeHierarchy ;

Int(4) charactersCount;

For (i=1 to charactersCount )

Bone rootBone[i];

Int(4) idBone ;

Int(4) childBonesCount;

Bone Bone[i];

Frames

Int(4) size ;

Int(4) timestamp; // Frame time in miliseconds

Int(4) boneDataCount;

For (i=1 to boneDataCountt)

BoneData bd[i];

BoneData

Int(1) boneDataMask//Center,rotation,isQuaternion,Translation,ScaleOrientation,Scale

For each component in boneDataMask

Float(4) component;

Return value

Exceptions

6.7.10.4.5 GetFAMCCount

GetFAMCCount ()

This method indicates the number of FAMC tracks in an MP4 file

Parameters

Return value

Exceptions

6.7.10.4.6 GetFAMCCount

GetFAMCSize ()

This method returns the size of the encoded FAMC buffer.

Parameters

a unique identifier of the FAMC stream

Return value

The return value is an integer specifying the size of the FAMC buffer

Exceptions

6.7.10.4.7 GetFAMC

GetFAMC()

This method gives access to the encoded FAMC buffer.

Parameters

buff contains the encoded FAMC buffer

GetDecodedFAMC()

This method gives access to the decoded FAMC buffer.

Parameters

buff contains the decoded FAMC buffer defined as a vector of VertexBuffer

Return value

Exceptions

FreeBuffer()

This method frees the memory allocated for the buffer transmitted in the parameter

Parameters

Return value

Exceptions

6.7.10.6 Editing

6.7.10.7 Decoding

6.7.10.8 Rendering

6.8 Image Metadata Engine APIs

[Editors' note: Split the following text into the sections Creation, Editing, Access, Presentation and Image Metadata Engine-specific methods. Use one table for each method to keep consistency with the rest of the document]

Creation of MPEG-7 Image Metadata (currently restricted to those used in Photo Player AF)

UML Specifications

Method syntax for class Image

~LoadImage(imageURI : string *) : int

~LoadImage(buffer : char *) : int

~EncodeJPEGImage(parameter : char *): int

Method syntax for class VisualDescriptor

~Extract(img : Image *) : boolean

~Distance(desc2 : VisualDescriptor *) : double

~EncodeXML() : string *

~DecodeXML(xml : string *) : boolean

~DecodeBinary(buffer : char *, buflen : int) : boolean

Class Diagram

C++ sample code implementation

class Image

// Image class can contain the following fields string *imageURI; unsigned char *pixels; int width; int height; int bitsPerPixel; // int colorModel; // e.g. RGB

// functions:

/** Loads image from the given URI or local file, returns the status of image:

success, error code*/ int LoadImage(string *imageURI);

/** Loads images from memory – it can be used by PhotoPlayer to decode jpeg images retrieved from PP MAF file tracks */ int LoadImage(unsigned char *buffer);

this function may be used to add images originally stored in non-jpeg formats

to Photo Player MAF file */

int EncodeJPEGImage(unsigned char **buffer);

class XMLNode

/* representation of XML element e.g DOM node or string? */

/* General class for visual still image desciptor */ class VisualDescriptor

/** Extracts the descriptor from image*/

bool Extract(Image *img);

//or bool Extract(string*imageURI);

/** Computes the distance to the descriptor desc2 of the same type */

double Distance(VisualDescriptor *desc2);

/** Encodes XML representation of this descriptor and returns the result*/

string *EncodeXML ();

// or XMLNode * EncodeXML ();

/** Decodes and creates this descriptor from xml representation */

bool DecodeXML(string*xml);

// or bool DecodeXML(XMLNode *xml);

/** Decodes and creates this descriptor from binary representation */

bool DecodeBinary(char *buffer, int buflen);

© ISO/IEC 2009 — All rights reserved 81 ISO/IEC CD 23006-2 VisualDescriptor is an abstract class. The following classes are subclasses of VisualDescriptor, they implement the common interface of functions:

class DominantColorDescriptor:VisualDescriptor; class ScalableColorDescriptor:VisualDescriptor; class ColorStructureDescriptor:VisualDescriptor; class ColorLayoutDescriptor:VisualDescriptor; class HomogeneousTextureDescriptor:VisualDescriptor; class TextureBrowsingDescriptor:VisualDescriptor; class EdgeHistogramDescriptor:VisualDescriptor; class RegionShapeDescriptor:VisualDescriptor; class ContourShapeDescriptor:VisualDescriptor; class ImageSignature:VisualDescriptor;

6.8.1 Image Metadata Creation

6.8.2 Image Metadata Editing

6.8.3 Image Metadata Access

6.8.4 Image Metadata Presentation

6.9 Audio Metadata Engine APIs

6.9.1 Audio Metadata Creation

Interface MetadataInterface (see Error: Reference source not found)

Method Syntax

+ setDuration (time:String):void

Java sample code public interface MetadataInterface { public void setDuration (String time); } Method description

This method is used to set the duration time of a video.

Parameters time the duration of the video.

Return value

Exceptions

6.9.2 Audio Metadata Editing

6.9.3 Audio Metadata Access

Method Syntax

+ getDuration ():String

Java sample code public interface MetadataInterface { public String getDuration (); } Method description

This method is used to get the duration time of an audio track.

Parameters

Return value

String, if exists a duration time, return the date else return null.

Exceptions

6.9.4 Audio Metadata Presentation

6.10 Video Metadata Engine APIs

6.10.1 Video Metadata Creation

Method Syntax

+ setDuration (time:String):void

Java sample code public interface MetadataInterface {

This method is used to set the duration time of a video.

Parameters time the duration of the video.

Return value void

Exceptions

6.10.2 Video Metadata Editing

6.10.3 Video Metadata Access

Method Syntax

+ getDuration ():String

Java sample code public interface MetadataInterface { public String getDuration (); } Method description

This method is used to get the duration time of a video.

Parameters

Return value

String, if exists a duration time, return the date else return null.

Exceptions

6.11 Content Metadata Engine APIs

6.11.1 Content Metadata Creation

Method Syntax

+ setID (ID:String):void

Java sample code public interface MetadataInterface { public void setID (String ID); } Method description

This method is used to set the identification of a content.

Parameters

ID the identifier of the content.

Return value void

Exceptions

Method Syntax

+ setTitle (title:String):void

Java sample code public interface MetadataInterface { public void setTitle (String title); } Method description

This method is used to set the title of a content.

Parameters title the title of the content.

Return value void

Exceptions

Method Syntax

+ setAuthor (author:String):void

Java sample code public interface MetadataInterface { public void setAuthor (String author); } Method description

This method is used to set the author of a content.

Parameters author the author of the content.

Return value void

Exceptions

Method Syntax

+ setAbstract (abstract:String):void

Java sample code public interface MetadataInterface { public void setAbstract (String abstract); } Method description

This method is used to set the content abstract.

Parameters abstract the abstract of the content.

Return value void

Exceptions

Method Syntax

+ setMimeType (mimeType:String):void

Java sample code public interface MetadataInterface { public void setMimeType (String mimeType); } Method description

This method is used to set the mime type of a content.

Parameters mimeType the mime type of the content.

Return value void

Exceptions

Method Syntax

+ setContributor (contributor:String):void

Java sample code public interface MetadataInterface { public void setContributor (String contributor); } Method description

This method is used to set the contributor to the creation of a content item.

Parameters creator the creator of the content.

Return value void

Exceptions

Method Syntax

+ setGenre (genre:String):void

Java sample code public interface MetadataInterface { public void setGenre (String genre); } Method description

This method is used to set the genre of a content.

Parameters genre the genre of the content.

Return value void

Exceptions

Method Syntax

+ setCopyRight (copyright:String):void

Java sample code public interface MetadataInterface { public void setCopyRight (String copyright); } Method description

This method is used to set the copyright of a content.

Parameters copyright the copyright of the content.

Return value void

Exceptions

Method Syntax

Java sample code public interface MetadataInterface { public void setCreationDate (String date); } Method description

This method is used to set the creation date of a content.

Parameters date the date of the content.

Return value void

Exceptions

Method Syntax

+ setThumbnail (thumbnail:String):void

Java sample code public interface MetadataInterface { public void setThumbnail (String thumbnail); } Method description

This method is used to set the thumbnail image of a content item.

Parameters thumbnail the thumbnail image of the content item.

Return value void

Exceptions

6.11.2 Content Metadata Editing

6.11.3 Content Metadata Access

+ getID ():String

Java sample code public interface MetadataInterface { public String getID (); } Method description

This method is used to get the ID of a content item.

Parameters

Return value

String, if exists a identification, return the identification else return null.

Exceptions

Method Syntax

+ getTitle ():String

Java sample code public interface MetadataInterface { public String getTitle (); } Method description

This method is used to get the title of a content item.

Parameters

Return value

String, if exists a title, return the title else return null.

Exceptions

Method Syntax

Java sample code public interface MetadataInterface { public String getAuthor (); } Method description

This method is used to get the author of a content item.

Parameters

Return value

String, if exists an author, return the author else return null.

Exceptions

Method Syntax

+ getDescripition ():String

Java sample code public interface MetadataInterface { public String getDescripition (); } Method description

This method is used to get the abstract of a content item.

Parameters

Return value

String, if exists an abstraction, return the abstract else return null.

Exceptions

Method Syntax

+ getMimeType ():String

This method is used to get the mime type of a content item.

Parameters

Return value

String, if exists a mime type, return the mime type else return null.

Exceptions

Method Syntax

+ getContributor ():String

Java sample code public interface MetadataInterface { public String getContributor (); } Method description

This method is used to get the contributor of a content item.

Parameters

Return value

String, if exists a creator, return the contributor else return null.

Exceptions

Method Syntax

+ getGenre ():String

Java sample code public interface MetadataInterface { public String getGenre ();

This method is used to get the genre of a content item.

Parameters

Return value

String, if exists a genre, return the genre else return null.

Exceptions

Method Syntax

+ getCopyRight ():String

Java sample code public interface MetadataInterface { public String getCopyRight (); } Method description

This method is used to get the copyright of a content item.

Parameters

Return value

String, if exists a copyright, return the copyright else return null.

Exceptions

Method Syntax

+ getDate ():String

Java sample code public interface MetadataInterface { public String getDate (); } Method description

Parameters

Return value

String, if exists a creation date, return the date else return null.

Exceptions

Method Syntax

+ getThumbnail ():String

Java sample code public interface MetadataInterface { public String getThumbnail (); } Method description

This method is used to get the thumbnail information of a content item.

Parameters

Return value

String, if exists a thumbnail information, return the date else return null.

Exceptions

6.12 Digital Item Streaming Engine APIs

6.12.1 Digital Item Streaming Creation

6.12.2 Digital Item Streaming Editing

6.12.3 Digital Item Streaming Access

6.13 Digital Item Adaptation Engine APIs

6.13.1 Usage Environment Description Creation

UML Specifications

Method syntax for interface MXMUseEnvDesc

~setUseEnvDescr(namespaceURI : string, ued : string) : boolean

Attribute syntax for class MXMDesrException

ACCESS_VIOLATION_ERROR : short const = 1

NOT_SUPPORTED_ERROR : short const = 2

INVALID_DESCRIPTION_ERROR const = 3

Class Diagram

Java sample code implementation for interface MXMUseEnvDescr interface MXMUseEnvDescr {

// Methods boolean setUseEnvDescr(String namespaceURI, String ued) throws MXMDescrException;

String parseUseEnvDescr(String namespaceURI) throws MXMDescrException;

Method setUseEnvDescr description

© ISO/IEC 2009 — All rights reserved 95 ISO/IEC CD 23006-2 This method is used to set the usage environment description (ued) identified by the namespace namespaceURI. The ued shall provide a description of the usage environment where the resource is consumed.

Parameters

namespaceURI

The ued parameter is a String containing the usage environment description.

Return value

Exceptions

6.13.2 Digital Item Adaptation Editing

6.13.3 Digital Item Adaptation Access

Method parseUseEnvDescr description

This method is used to parse a usage environment description identified by the namespace namespaceURI. The return value shall provide a description of the usage environment where the resource is consumed.

Parameters

namespaceURI

Return value

The return value is a String containing the usage environment description (ued) identified by the namespace namespaceURI. The ued shall provide a description of the usage environment where the resource is consumed.

Exceptions

Java sample code implementation for class MXMDescrException public class MXMDescrException extends Exception

96 © ISO/IEC 2009 — All rights reserved { public static final short ACCESS_VIOLATION_ERROR = 1; public static final short NOT_SUPPORTED_ERROR =2; public static final short INVALID_DESCRIPTION_ERROR = 3;

C++ sample code implementation for class MXMDescrException exception {

unsigned short code;

// Exception codes const unsigned short ACCESS_VIOLATION_ERROR = 1; const unsigned short NOT_SUPPORTED_ERROR = 2; const unsigned short INVALID_DESCRIPTION_ERROR = 3;

Class MXMDescrException description

ACCESS_VIOLATION_ERROR

This exception is raised if an implementation of MXM, that supports access control, detects an illegal attempt to access the delivery context.

NOT_SUPPORTED_ERROR

This exception is raised if a call is made to a method which is not supported by MXM description API.

INVALID_DESCRIPTION_ERROR

This exception is raised if a description is not valid within the given namespace.

6.14 Digital Item Processing Engine APIs

6.14.1 Digital Item Processing Creation

6.14.2 Digital Item Processing Access

6.15 Event Reporting Engine APIs

6.15.1 Event Report Request Creation

6.16 Event Report Request Creation

6.16.1 Method to generate an ISO/IEC 21000-15 conformant Event Report Request.

Interface ContentBuilder1

Method Syntax

+ createERR(modificationUserID: String, modificationPeerID: String, errDescription: String, ERSDII: String, ERSDescription: String, ERSPayloadPeerId:boolean, ERSPayloadUserId:boolean, ERSPayloadTime:boolean, ERSPayloadLocation:boolean, ERSPayloadDIOperation:Boolean, ERSPayloadDomainDataReportTag:String [], ERSPayloadDomainDatsemantics:String [], ERSPayloadDomainDataSyntax:String [], ERSPayloadDomainDataValue:String [], ERSPayloadDIMetadata: String [], ERSFormatSRef:String, ERSFormatSSchema:String, ERSFormatSMimeType:String, ERSDeliveryUser:String, ERSEmbeddedERRorERRReference:String, ERisERRackFullEmbedded:boolean, EVCOperations:String [], EVCDII: String []):String

Java sample code public interface ContentBuilder { public String createERR(String modificationUserID, String modificationPeerID, String errDescription, String ERSDII, String ERSDescription, boolean ERSPayloadPeerId, boolean ERSPayloadUserId, boolean ERSPayloadTime, boolean ERSPayloadLocation, boolean ERSPayloadDIOperation, String [] ERSPayloadDomainDataReportTag, String [] ERSPayloadDomainDatsemantics, String [] ERSPayloadDomainDataSyntax, String [] ERSPayloadDomainDataValue, String [] ERSPayloadDIMetadata, String ERSFormatSRef, String ERSFormatSSchema, String ERSFormatSMimeType, String ERSDeliveryUser, String ERSEmbeddedERRorERRReference,boolean ERisERRackFullEmbedded, String [] EVCOperations, String [] EVCDII) throws ERRGenerationException } Method description

This method is used to generate an Event Report Request conformant to ISO/IEC 21000-15. It generates an ERR according to the terms stated by the creator or distributor of the digital content. An ERR will contain information about the Digital Item, the resource, and the conditions under which the event will occur. Once created, it is associated to a Digital Item.

Parameters modificationUserID ERRDescriptor Modification field. The User that is modifying the ERR. modificationPeerID ERRDescriptor Modification field. The Peer that is modifying the ERR. errDescription ERRDescriptor Modification field. A description for the ERR.

ERSDII ERSpecification field.

ERSDescription ERSpecification field.

ERSPayloadPeerId ERPayloadSpecification field.

ERSPayloadUserId ERPayloadSpecification field.

ERSPayloadTime ERPayloadSpecification field.

ERSPayloadLocation ERPayloadSpecification field.

ERSPayloadDIOperation ERPayloadSpecification field.

ERSPayloadDomainDataReportTag ERPayloadSpecification DomainData field. Domain

1 The ContentBuilder, although understood from its Chillout reference, needs a description in MXM.

ERSPayloadDomainDataSemantics ERPayloadSpecification DomainData field. Domain metadata tag semantics (e.g. “Identifier of the license used for the authorisation”).

ERSPayloadDomainDataSyntax ERPayloadSpecification DomainData field. Domain metadata tag syntax (e.g. “xsd: string”).

ERSPayloadDomainDataValue ERPayloadSpecification DomainData field. Domain metadata tag value (e.g. “LID:44t7r665:12fq35:513t554”).

ERSPayloadDIMetadata ERPayloadSpecification information for the DIMetadata field. Array containing the names of the DI metadata fields to be reported (e.g. "abstract", "title", "alternative", "creator", "creator", "identifier", "date").

ERSFormatSRef ERFormatSpecification field.

ERSFormatSSchema ERFormatSpecification field.

ERSFormatSMimeType ERFormatSpecification field.

ERSDeliveryUser ERDeliverySpecification Recipient field.

ERSDeliveryPeer ERDeliverySpecification Recipient field.

ERSDeliveryTime. ERDeliverySpecification field.

ERSDeliveryTransportService. ERDeliverySpecification field.

ERSEmbeddedERRorERRReference ERR or ERRReference to be placed in the EmbeddedERR field.

ERisERRackFullEmbedded Indicates if the previous ERSEmbeddedERRorERRReference parameter is of type ERR (true) or a ERRReference (false).

EVCOperations Array containing the ordered chain of operations that, if executed, will trigger the generation of the ER. They will be included in different DIOperationEvent elements.

EVCDII The Digital Item Identifier of the DI over which the previous operations apply, to be included in order in the previous DIOperationEvent elements.

Return value

ERRequest: an Event Report Request conformant to ISO/IEC 21000-15 containing information about the Digital Item, the resource, and the conditions under which the event will occur.

Exceptions

ERRGenerationException This exception is thrown if an error occurred while instantiating the classes

6.17 Event Report Creation

6.17.1 Method to generate an ISO/IEC 21000-15 conformant Event Report.

Interface ContentBuilder

Method Syntax

+ createER (ERR:String, AppID: String, userID:String, peerID:String, DIOperation:String, DII:String, DIImetaName:String [], DIImetaValue:String [], DIIMetaSchema:String [], ERdescription:String, embedERR:boolean, ERRelatedDII:String, ERUserCountry:String, ERUserRegion:String, ERTime:String, DomainDataName:String[], DomainDataValue:String[], DomainDataSchema: String[], ERRReference:String):String

Java sample code public interface ContentBuilder { public String createER (String ERR, String AppID, String userID, String peerID, String DIOperation, String DII, String [] DIImetaName, String [] DIImetaValue, String [] DIIMetaSchema, String ERdescription, boolean embedERR, String ERRelatedDII, String ERUserCountry, String ERUserRegion, String ERTime, String [] DomainDataName, String[] DomainDataValue, String[] DomainDataSchema, String ERRReference) throws ERGenerationException } Method description

This method is used to generate an Event Report conformant to ISO/IEC 21000-15. It decides whether an ER needs to be created according to an ERR and some input information regarding content usage. If necessary, it generates and returns the corresponding ER. It receives as inputs a single ERR, the identification of the user, the operation that this user has performed, the time when the operation has been performed, the Digital Item identifier and the Peer identifier, amongst others. The ER generated contains information about the Digital Item, or the digital resource, and the conditions under which the event has succeeded.

Parameters

ERR Event Report Request that triggers the generation of the Event Report.

AppID Application Identifier (for the case when there is no input ERR). userID The identifier of the user that performs the action to be reported. peerID The identifier of the peer that performs the action.

DIOperation The action performed over the Digital Item or resource.

DII The Digital Item Identifier.

DIImetaName These three arrays must have the same length, and contain the key, value and schema triples that refer to any metadata in the DI DIImetaValue that needs to be reported. Those metadata elements must be those specified in the ERR, if present. DIIMetaSchema

ERdescription Textual description for the Event Report.

ERRelatedDII Related Digital Item Identifier.

ERUserCountry Contextual information for the user.

ERUserRegion Contextual information for the user.

ERTime Time when action was performed, expressed in XMLGregorian format.

DomainDataName These three arrays must have the same length, and contain the key, value and schema triples that refer to any domain data that DomainDataValue needs to be reported. Those metadata elements must be those specified in the ERR, if present. DomainDataSchema

ERRReference If not null, it contains an URI to be included as the field in the ER.

Return value

ER: an Event Report conformant to ISO/IEC 21000-15

Exceptions

ERRGenerationException This exception is thrown if an error occurred while instantiating the classes involved in the creation of XML data.

6.18 Event Report Request Access

6.18.1 Method to obtain form a Digital Item all the Event Report Requests within it.

An instance of DCIParser (see Error: Reference source not found) has to be created and initialised by requesting the DCIParser to parse the Digital Item.

This method should perhaps go in 6.1.3, Digital Item Access (N10291).

Interface DCIParser

Method Syntax

+ getArrayOfERRs (): String[]

Java sample code public interface DCIParser { public String[] getArrayOfERRs(); } Method description

This method is used to obtain all the ERRs within A Digital Item. This method supposes that an object of type DCIParser has been instantiated and requested to parse the Digital Item containing one or more Event Report

Parameters

Return value

An array containing all the Event Report Requests found in the Digital Item.

Exceptions

6.18.2 Method is used to obtain Event Report Request fields from and ERR conformant to ISO/IEC 21000-15.

The extracted information will be used to determine if ERs shall be generated, and delivery options (user and/or peer to which the ER shall be sent, transport service, time of delivery, etc.).

Interface ContentBuilder

Method Syntax

+ getERRData(ERR: String):String[]

Java sample code public interface ContentBuilder { public String[] getERRDatta(String ERR) } Method description

This method is used to obtain Event Report Request fields from and ERR conformant to ISO/IEC 21000-15. The extracted information will be used to determine if ERs shall be generated, and delivery options (user and/or peer to which the ER shall be sent, transport service, time of delivery, etc.).

Parameters

ERR Event Report Request conformant to ISO/IEC 21000- 15

Return value

String[]: The different elements within the Event Report Request.

Exceptions

6.18.3 Event Registration

[Input from Eva :-)]

6.19 Content Protocol Engine APIs

6.19.1 Content Identification Protocol

Content Identification is the process by which the hash value of a Digital Item (DCI) is persistently registered by a service (the Content Identification Device, CID) and bound to a globally unique identifier inserted in the Digital Item before the hash value was calculated. MXM provides two methods to identify a new content item: a) by sending the DCI to the CID and requesting that the hash calculation is made by the CID b) by:

1) requesting an identifier to the CID

2) inserting it in the new DCI

3) calculating the hash value or digital signature of the resulting DCI

4) sending the hash value to the CID together with the identifier obtained in 2.a requesting the new record to be registered.

6.19.1.1 Identify Content Item

6.19.1.1.1 Content Identification by sending the DCI

Method Syntax

+ identifyContent (dci:DIDL, cidServiceURL:String):DIDL

Java sample code public interface ContentBuilder{ public DIDL identifyContent (DIDL dci, String cidServiceURL) throws ContentIdentificationException, MalformedContentElementException, DCIParsingException; } Method description

This method is used to identify a Digital Item (DCI) by sending it to the Content Identification Device. The Content Identification Device generates a new identifier, inserts it in the DCI as specified in ISO/IEC 23000- 5, generates a hash value of the DCI file and finally inserts the hash/digital signature value in the DCI as specified in ISO/IEC 23000-5. If these operations are performed successfully, the DCI containing these modifications is returned to the requesting application.

Parameters dci The Digital Item to be identified (see Error: Reference source not found for more information on the DIDL interface). cidServiceURL The URL of the service to be invoked in order to request an identifier for the new resource.

Return value

The Digital Item (see Error: Reference source not found for more information on the DIDL interface) containing the content identifier and the hash/digital signature value if the operation was performed

Exceptions

ContentIdentificationException (see Error: This exception is thrown if an error occurred while creating the Reference source not found) message to request the new identifier, or if the cidURL input parameter is malformed.

MalformedContentElementException (see This exception is thrown if the Digital Item given in input is Error: Reference source not found) corrupted, malformed or it already contains a content identifier.

DCIParsingException (see Error: This exception is thrown if the DCI returned from the Content Reference source not found) Identification service was corrupted.

6.19.1.1.2 Content Identification by sending the DCI hash

Method Syntax

+ identifyContent (dci:DIDL, digestAlgonameJCA:String, digestAlgonameW3C, cidServiceURL:String):DIDL

Java sample code public interface ContentBuilder{ public DIDL identifyContent (DIDL tempDCI, String digestAlgonameJCA, String digestAlgonameW3C, String cidServiceURL) throws ContentIdentificationException, MalformedContentElementException, UnsupportedFeatureException; } Method description

This method is used to identify a Digital Item (DCI) by sending to the Content Identification Device its hash value. Before the hash value is calculated, a content identifier will be requested to the specified content identification service and inserted in the DCI. The Content Identification Device, upon receiving the hash value and the identifier from the client application stores the two values persistently. If these operations are performed successfully, the DCI containing these modifications is returned to the requesting application.

Parameters dci The Digital Item to be identified (see Error: Reference source not found for more information on the DIDL interface). digestAlgonameJCA The name of the hash algorithm as known by the platform on which the algorithm runs digestAlgonameW3C The name of the hash algorithm as specified in Error: Reference source not found cidServiceURL The URL of the service to be invoked in order to request an identifier for the new resource.

Return value

The Digital Item (see Error: Reference source not found for more information on the DIDL interface) containing the content identifier and the hash/digital signature value if the operation was performed successfully, null otherwise.

Exceptions

104 © ISO/IEC 2009 — All rights reserved ContentIdentificationException (see Error: This exception is thrown if an error occurred while creating the Reference source not found) message to request the new identifier, or if the cidURL input parameter is malformed.

MalformedContentElementException (see This exception is thrown if the Digital Item given in input is Error: Reference source not found) corrupted, malformed or it already contains a content identifier.

UnsupportedFeatureException (see Error: This exception is thrown if the specified digest algorithm was Reference source not found) not supported by MXM.

6.19.1.2 Identify Content Element

6.19.1.2.1 Resource identification with file in input

Interface IdentifyResourceManager (see Error: Reference source not found)

Method Syntax

+ identifyResource (resourceFile:File, digestAlgonameJCA:String, digestAlgonameW3C:String, cidServiceURL:String):String

Java sample code public interface IdentifyResourceManager{ public RequestIdentifierResponse identifyResource(File resourceFile, String digestAlgonameJCA, String digestAlgonameW3C, String cidServiceURL) throws ContentIdentificationException, AxisFault, ServiceException, IOException, UnsupportedFeatureException; } Method description

This method is used to identify a resource stored in a file. MXM generates a hash value of the resource using the specified algorithm and request an identifier to the specified service. The hash value of the resource is sent to the Content Identification service so that the issued content identifier and the resource hash will be stored persistently on the Content Identification service.

Parameters resourceFile The resource file to be identified. digestAlgonameJCA The name of the hash algorithm as known by the platform on which the algorithm runs digestAlgonameW3C The name of the hash algorithm as specified in Error: Reference source not found cidServiceURL The URL of the service to be invoked in order to request an identifier for the new resource.

Return value

Exceptions

ContentIdentificationException (see Error: This exception is thrown if an error occurred while creating the Reference source not found) message to request the new identifier, or if the cidURL input

UnsupportedFeatureException (see Error: This exception is thrown if the information contained in the Reference source not found) ProtectedContentElement object given in input was not supported by MXM (e.g. hash algorithm not supported).

IOException (see Error: Reference source This exception is thrown if problems were detected while not found) calculating the hash value of the resource file.

ServiceException (see Error: Reference This exception is thrown if an error occurred while source not found) communicating with the content identification service.

AxisFault (see Error: Reference source This exception is thrown if the service to be invoked is not found) unreachable.

6.19.1.2.2 Resource identification with hash in input

Interface IdentifyResourceManager (see Error: Reference source not found)

Method Syntax

+ identifyResource (resourceHash:Signature, cidServiceURL:String):String

Java sample code public interface IdentifyResourceManager{ public RequestIdentifierResponse identifyResource(Signature resourceHash, String cidServiceURL) throws ContentIdentificationException, ServiceException, AxisFault, IOException; } Method description

This method is used to identify a resource whose hash is specified in input. The hash value of the resource is sent to the Content Identification service so that the issued content identifier and the resource hash will be stored persistently on the Content Identification service.

Parameters resourceHash The hash value of the resource whose identifier is sought. See the Signature interface (Error: Reference source not found) for more information. cidServiceURL The URL of the service to be invoked in order to request an identifier for the new resource.

Return value

Exceptions

ContentIdentificationException (see Error: This exception is thrown if an error occurred while Reference source not found) creating the message to request the new identifier, or if the cidURL input parameter is malformed.

IOException (see Error: Reference source not This exception is thrown if problems were detected while found) calculating the hash value of the resource file.

106 © ISO/IEC 2009 — All rights reserved ServiceException (see Error: Reference source This exception is thrown if an error occurred while not found) communicating with the content identification service.

AxisFault (see Error: Reference source not This exception is thrown if the service to be invoked is found) unreachable.

6.19.2 Content Authentication Protocol

These methods are used to verify that the hash value of a content item and/or any of its conrtent elements are authentic, i.e. the same values registered when the content item or content element were identified.

6.19.2.1 Authenticate Content Item

Interface ContentIdentificationManager (see Error: Reference source not found)

Method Syntax

+ authenticateContent (didl : DIDL, cidServiceURL : string, contentAuthenticationType : string) : ContentIdentificationResult

Java sample code public interface ContentIdentificationManager { public ContentIdentificationResult authenticateContent (DIDL didl, String cidServiceURL, string contentAuthenticationType) throws ContentAuthenticationException, MalformedContentElementException ; } Method description

This method is used to authenticate a content item (DCI). Content authentication can be performed

1. by calculating the hash value of the digital item and a. sending it to the Content Identification Device to be compared with the one stored in conjunction with the content ID b. requesting to the Content Identification Device the stored hash value in order to compare the two values 2. by sending the whole Digital Item to the Content Identification Device and letting the Content Identification Device to compare the stored value with the one calculated on the submitted DCI. Parameters didl The Digital Item to be authenticated (see Error: Reference source not found for more information on the DIDL interface). cidServiceURL The URL of the service to be invoked in order to authenticate the content item in the three modalities contentAuthenticationType a string with the name of one of the three types of content authentication available

Return value

An object or type ContentIdentificationResult (see Error: Reference source not found) containing either a true result or the reason of authentication failure.

Exceptions

ContentAuthenticationException (see This exception is thrown if an error occurred while creating the Error: Reference source not found) request message for the Content Identification Device, or if the

MalformedContentElementException (see This exception is thrown if the Digital Item given in input is Error: Reference source not found) corrupted or malformed.

6.19.2.2 Authenticate Content Element

Interface ContentIdentificationManager (see Error: Reference source not found)

Method Syntax

+ authenticateContent (didl : DIDL, contentElementID : string, cidServiceURL : string, contentAuthenticationType : string) : ContentIdentificationResult

Java sample code public interface ContentIdentificationManager { public ContentIdentificationResult authenticateContent (DIDL didl, String contentElementID, String cidServiceURL, string contentAuthenticationType) throws ContentAuthenticationException, MalformedContentElementException ; } Method description

This method is used to authenticate a content item (DCI). Content authentication can be performed by calculating the hash value of the content element and

1. sending it to the Content Identification Device to be compared with the one stored in conjunction with the content ID 2. requesting to the Content Identification Device the stored hash value in order to compare the two values Parameters didl The Digital Item to be authenticated (see Error: Reference source not found for more information on the DIDL interface). contentElementID The identifier of the content element within the content item requiring authentication. cidServiceURL The URL of the service to be invoked in order to authenticate the content element in the two modalities contentAuthenticationType a string with the name of one of the two types of content element authentication available

Return value

An object or type ContentIdentificationResult (see Error: Reference source not found) containing either a true result or the reason of authentication failure.

Exceptions

ContentAuthenticationException (see This exception is thrown if an error occurred while creating the Error: Reference source not found) request message for the Content Identification Device, or if the cidServiceURL input parameter is malformed.

MalformedContentElementException (see This exception is thrown if the Digital Item given in input is Error: Reference source not found) corrupted or malformed.

6.19.3.1 AccessContentElement

In order to request time-dependent information related to a Content Element (e.g. a streaming resource, streaming metadata, etc.), the following method is employed:

Interface RemoteContentElementManager (see Error: Reference source not found)

Method Syntax

+ accessContentElement (contentID : string, contentElementID : string, cpdServiceURL : string, transactionID : string): void

Java sample code public interface RemoteContentElementManager { public void accessContentElement(String contentID, String contentElementID, String cpdServiceURL, String transactionID) throws AccessContentException, UnsupportedFeatureException ; } Method description

This method is used to request time-dependent information related to a content element identified by a content element ID and part of a content item identified by a content ID from a remote service (i.e. the Content provider Device). The request to the service is made according to the Request Content protocol specified in ISO/IEC 29116-1. If the protocol is successfully carried out, URLs from where the time-dependent parts of the content item can be retrieved will be returned and accessed directly by MXM which will display any audiovisual resource using the specified MediaFramework. Applications calling the method accessContentElement may listen to events of type ContentResponseEvent by implementing the callback method specified at the bottom of this table.

Parameters contentID The identifier of the content item to which the requested content element belongs to contentElementID The identifier of the requested content element cpdServiceURL The URL of the remote service to which content is requested transactionID The identifier of the message to be used in the request.

Return value

Exceptions

AccessContentException This exception is thrown if an error occurs while the Request Content protocol is being carried out

UnsupportedFeatureException This exception is thrown if MXM doesn’t know how to deal with the content received from the remote service.

Callback Interface

RequestContentResponseListener (see Error: Reference source not found)

Callback Method

+ public void handleRequestContentResponseEvent(event ContentResponseEvent) : void

6.19.4 Content Storage Protocol

Content created by a Content Creation application may be stored on a remote location (e.g. a Content Provider Device) by invoking the methods specified below:

6.19.4.1 Store a DCF

Interface ContentUploader (see Error: Reference source not found)

Method Syntax

+ uploadDCF (contentInfoType: ContentInfoType, dcfFile : File, transactionID : string) : void

Java sample code public interface ContentUploader { public boolean uploadDCF(ContentInfoType contentInfoType, File dcfFile, String transactionID) throws StoreContentException, UnsupportedFeatureException, BadPropertyException ; } Method description

This method is used to upload an ISO/IEC 21000-9 file to a remote location.

Parameters contentInfoType An object of type ContentInfoType (see Error: Reference source not found) containing a set of information needed to create the message to request content to be uploaded dcfFile The ISO/IEC 21000-9 file to be uploaded, which shall contain the Digital Item describing it in either the XML or BXML boxes transactionID A string identifying the specific request to upload the content, to be used in the protocol with the CPD

Return value

Exceptions

StoreContentException (Error: Reference This exception is thrown if an error occurs while the content is source not found) being stored

BadPropertyException (Error: Reference This exception is thrown if the properties used to initialise the source not found) SecurityManager were not correctly set, hence the SecurityManager was unable to determine the location of the secure repository.

UnsupportedFeatureException (Error: This exception is thrown if an error occurred while validating Reference source not found) the principal in the license against the principal in the query.

Callback Interface

StoreContentListener (see Error: Reference source not found)

+ processStoreContentEvent(event : StoreContentEvent) : void

6.19.4.2 Store a DCS

Interface ContentUploader (see Error: Reference source not found)

Method Syntax

+ storeDCS (contentBuilder: ContentBuilder, cpdServiceURL: string) : void

Java sample code public interface ContentUploader { public void storeDCS(String cpdServiceURL, ContentBuilder contentBuilder) throws StoreContentException, UnsupportedFeatureException, BadPropertyException ; } Method description

This method is used to upload a Digital Item and a number of resources referenced in it, to a remote location.

Parameters contentBuilder An object of type ContentBuilder (see Error: Reference source not found) containing the information about all the resources to be stored to a remote location, and the Digital Item previously generated after the method createDCI has been invoked (see Error: Reference source not found) cpdServiceURL The URL of the service where content shall be uploaded

Return value

Exceptions

StoreContentException (Error: Reference This exception is thrown if an error occurs while the content is source not found) being stored

BadPropertyException (Error: Reference This exception is thrown if the properties used to initialise the source not found) ContentUploader class were not correctly set, hence content storage failed.

UnsupportedFeatureException (Error: This exception is thrown if a feature not supported by MXM was Reference source not found) requested, such as storing content using a protocol which was not supported.

Callback Interface

StoreContentListener (see Error: Reference source not found)

Callback Method

6.20.1 License Access

In order to extract from a remote service the method below can be invoked. A license conforming to ISO/IEC 21000-5 will be requested to the service by performing the Request License protocol specified in ISO/IEC 29116-1.

Interface LicenseManager (see Error: Reference source not found)

Method Syntax

+ requestLicense (contententID:string, contentElementID:string, licenseTemplate:RELLicense, lpdServiceURL:string):void

Java sample code public interface LicenseManager { public void requestLicense(String contentID, String contentElementID, RELLicense licenseTemplate, String lpdServiceURL) throws AccessLicenseException; } Method description

This method is used to obtain a license for a content item or content element part of a content item, possibly conforming to a license template from a service.

Parameters contentID The identifier of the content item whose license is sought, or the identifier of the content item containing a content element whose license is sought contentElementID The identifier of a content element whose license is sought. This parameter shall be null in the case a license for a content item is sought licenseTemplate An object of type RELLicense (see Error: Reference source not found) specifying what shall the requested license contain in terms of principal, right, resource and possibly conditions. lpdServiceURL The URL of the remote service to be invoked in order to request a license.

Return value

Exceptions

AccessLicenseException (Error: This exception is thrown if an error occurs while the Reference source not found) msap:RequestLicense message is generated

Callback Interface

RequestLicenseResponseListener (see Error: Reference source not found)

Callback Method

+handleRequestLicenseResult(event: RequestLicenseResponseEvent) : void

Method Syntax

+ getLicense (xmlLicense:string licenseId): RELLicense

Java sample code public interface ContentBuilder { public RELLicense getLicense(String licenseId) throws SecurityManagerException, BadPropertyException, UnsupportedFeatureException; } Method description

This method is used to retreive a License given its id.

Parameters licenseId The id attribute of the license element.

Return value

RELLicense the REL license

Exceptions

SecurityManagerException (see Error: This exception is thrown if the digital certificate of Reference source not found) either the license issuer or the license principal could not be retrieved from the SecurityManager because it does not exist.

BadPropertyException (see Error: This exception is thrown if one or more properties Reference source not found) required by the SecurityManager (e.g. the location of the secure repository where digital certificates reside) were corrupted.

UnsupportedFeatureException (see This exception is thrown if one or more properties Error: Reference source not found) required by the SecurityManager (e.g. the encryption algorithm for encrypting the Master Key with the principal’s public key) is not supported by MXM. s

6.20.2 License Storage

Interface LicenseUploader (see Error: Reference source not found)

Method Syntax

+ storeLicense (storeLicenseRequest: StoreLicenseRequest, lpdServiceURL: string) : void

Java sample code public interface LicenseUploader { private void storeLicenseTemplates(StoreLicenseRequest : storeLicenseRequest, lpdServiceURL : string) throws MalformedContentElementException, UnsupportedFeatureException, StoreLicenseTemplateException; } Method description

Parameters storeLicenseRequest An object of type StoreLicenseRequest (see Error: Reference source not found) to be sent to the specified service lpdServiceURL The URL of the service where the license template shall be uploaded

Return value

Exceptions

StoreLicenseTemplateException (Error: This exception is thrown if an error occurs while the license Reference source not found) template is being stored

Callback Interface

StoreLicenseEventListener (see )

Callback Method

6.20.3 Operation to revoke a license

Method Syntax

+revokeLicense(String licenseId): boolean

Java sample code public boolean revokeLicense(String licenseId) throws MalformedContentElementException, UnsupportedFeatureException;

Method description

This method is used to revoke a license.

Parameters licenseId Identifier of the license to be revoked.

Return value

Boolean reportin gits success.

Exceptions

SecurityManagerException (see Error: The invoking User must have the right to revoke the Reference source not found) license. This exception is thrown if the digital certificate

6.21 IPMP Tool Protocol Engine APIs

6.21.1 IPMP Tool Access

Method Syntax

+ requestIPMPToolBody (location:URL, id:String, di:DeviceInformation):ToolBody

Java sample code public interface ResourceManager { public ToolBody requestIPMPToolBody(URL location, String id, DeviceInformation di) throws ResourceBuilderException } Method description

This method is used to retrieve from a TPD (specified by the passed location) a ToolBody that are compatible with the passed device informations

Parameters location A URL that specify where the TPD resides id The IPMPTool name that has to be retrieved di The Device Information that has to be matched from the TPD Error: Reference source not found

Return value

A TooBody, named id, that match the specified DeviceInformation Error: Reference source not found

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourseBuilder failed Reference source not found) requesting the IPMPInfo

6.21.2 IPMP Tool List Access

Method Syntax

+ requestIPMPInfoList (location:URL, di:DeviceInformation):IPMPInfo[]

Java sample code

© ISO/IEC 2009 — All rights reserved 115 ISO/IEC CD 23006-2 public interface ResourceManager { public IPMPInfo[] requestIPMPInfoList(URL location, DeviceInformation di) throws ResourceBuilderException } Method description

This method is used to retrieve from a TPD (specified by the passed location) a list of IPMPInfo that are compatible with the passed device informations

Parameters location A URL that specify where the TPD resides

di The Device Information that has to be matched Error: Reference source not found

Return value

A set of IPMPInfo that match the passed DeviceInformation Error: Reference source not found

Exceptions

ResourceBuilderException (see Error: This exception is thrown if the ResourseBuilder failed Reference source not found) requesting the IPMPInfo

6.22 Content Search Engine APIs

Class Diagram

6.22.1 Content Store

[Editors' note: Is this necessary, or we can treat this method as a particular case of the Store Content Protocol?]

The storage part of the system is accessible by means of the store(DCFWrapper), where the DCFWrapper is a wrapper of the DCF file and Pair is bean with key-value pair attributes.

116 © ISO/IEC 2009 — All rights reserved These high level functionality's interact with the low level functions of the Distributed System layer (e.g. based on DHT, Chord, CAN like etc...) which are not part of the APIs of this engine.

UML Specifications

Method Syntax for interface DistributedStorage

+store (dcfwrapper:DCFWrapper, distributedFlag:boolean):boolean

Java sample code implementation

public interface DistributedStorage { public boolean store(DCFWrapper dcfwrapper,boolean distributedFlag); }

Method description

Once the DCF is created by the Content Creator Device, it is possible to store and index the content using the keys bound to the metadata.

Once the indexes are set, all the mappings are inserted in the Distributed SystemDHT, with the reference to the position in the system of the DCF itself (represented as an associated entity in the class diagram)

The second parameter, the distributedFlag let the user to decide if the DCF can be stored somewhere in the network (flag=true) or can force the system to store the DCF only locally, even if the related indexes will be distributed.

6.22.2 Content Search

The function of searching for content

UML Specifications

Method Syntax for interface DistributedStorage

+retrieve (pairs:List):List

Java sample code implementation

public interface DistributedStorage {

public List retrieve(List pairs);

Method retrieve description

The retrieve process starts querying the system with specific keys that have been used for indexing the searched content.

It is possible retrieve the references to all the DCF provided by the issuer named “scott”, calling the method with the key-value pair: (“issuer”,”scott”). The user can apply for structured queries providing a list of key- value pairs mapped onto a Pair object, which is a bean with the key,value class attributes.

© ISO/IEC 2009 — All rights reserved 117 ISO/IEC CD 23006-2 The method returns a list of DCFWrappers that have the references to the real DCF content. In the DCFWrapper is written the resource from which pulling the DCF. A separate transferring channel must be set up for the physical downloading of the DCF.

6.23 Security Engine APIs

6.23.1 Key Generation

6.23.1.1 Random key generation

Interface SecurityManagerInterface

Method Syntax

+ generateRandomKey(String algorithm, int keyLength): byte[]

Java sample code public byte[] generateRandomKey(String algorithm, int keyLength) throws NoSuchAlgorithmException ; Method description

This method is employed to generate a random key using the given algorithm.

Parameters algorithm algorithm used to produce a random key. keyLength the size of the random key.

Return value byte[], a random key(a pseudo-random number).

Exceptions

NoSuchAlgorithmException

6.23.1.2 Random key-pair generation

Method Syntax

+ generateTestKeyPair(String algorithm): KeyPair

Java sample code public KeyPair generateTestKeyPair(String algorithm) throws NoSuchAlgorithmException, IOException, BadPropertyException, DeviceContextException ; Method description

This method is employed to generate a key pair (a private key and its associated public key) using the given algorithm.

Parameters algorithm algorithm to be used with this key pair.

KeyPair, a key pair (a private key and its associated public key).

Exceptions

IOException

BadPropertyException

DeviceContextException

6.23.2 Encryption

6.23.2.1 Encrypt an array of bytes using asymmetric encryption

Method Syntax

+ encrypt(byte[] data, String algorithm, String keyAlias, String password): byte[]

Java sample code public byte[] encrypt(byte[] data, String algorithm, String keyAlias, String password) throws SecurityManagerException, BadPropertyException, DeviceContextException, UnsupportedFeatureException, MalformedContentElementException ; Method description

This method is employed to encrypt the data with the given algorithm using the public key from a trusted certificate stored in the keyStore.

Parameters data data to be encrypted. algorithm algorithm used to encrypt the data. keyAlias alias for the key which is to be used with the given algorithm to encrypt the data. password password for accessing the key entry with the given key alias.

Return value byte[],result of encryption.

Exceptions

SecurityManagerException

MalformedContentElementException

6.23.2.2 Encrypt an array of bytes using symmetric encryption

Method Syntax

+ encrypt(byte[] data, byte[] encryptionKey, String algorithm): byte[]

Java sample code public byte[] encrypt(byte[] data, byte[] encryptionKey, String algorithm) throws SecurityManagerException, UnsupportedFeatureException, MalformedContentElementException; Method description

This method is employed to encrypt the data with the given algorithm using the key passed as a parameter.

Parameters data data to be encrypted. encryptionKey the key to be used to encrypt the data. algorithm algorithm used to encrypt the data.

Return value byte[], result of encryption.

Exceptions

UnsupportedFeatureException

MalformedContentElementException

6.23.3 Decryption

6.23.3.1 Asymmetric decrypt an array of bytes

Method Syntax

+ decrypt(byte[] data, String algorithm, String keyAlias, String password): byte[]

Java sample code public byte[] decrypt(byte[] data, String algorithm, String keyAlias, String password) throws NoSuchAlgorithmException, CertificateException, KeyStoreException, UnrecoverableEntryException, IOException, NoSuchPaddingException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException,

This method is employed to decrypt the input data using a private key.

Parameters data data to be decrypted. algorithm algorithm used to decrypt the data. keyAlias alias for the key which is to be used by the given algorithm to decrypt the data. password password for accessing the key entry with the given key alias.

Return value byte[], result of decryption.

Exceptions

CertificateException

KeyStoreException

UnrecoverableEntryException

IOException

NoSuchPaddingException

InvalidKeyException

IllegalBlockSizeException

BadPaddingException

6.23.3.2 Symmetric decrypt an array of bytes

Method Syntax

+ decrypt(byte[] data, byte[] decryptionKey, String algorithm): byte[]

Java sample code public byte[] decrypt(byte[] data, byte[] decryptionKey, String algorithm) throws NoSuchAlgorithmException, NoSuchPaddingException, InvalidKeyException, IllegalBlockSizeException, BadPaddingException ;

This method is employed to decrypt the data with the given algorithm using the key passed as a parameter.

Parameters data data to be decrypted. decryptionKey the key to be used to decrypt the data. algorithm algorithm used to decrypt the data.

Return value byte[], result of decryption.

Exceptions

NoSuchPaddingException

InvalidKeyException

IllegalBlockSizeException

BadPaddingException

6.23.4 Hash calculation

6.23.4.1 Generate a hash value of an array of bytes

Method Syntax

+ generateHash(byte[] data, String algorithm): byte[]

Java sample code public byte[] generateHash(byte[] data, String algorithm) throws NoSuchAlgorithmException ; Method description

This method is employed to generate hash value for the data using the given algorithm.

Parameters data data to be hashed. algorithm algorithm used to hash the data.

Return value byte[], a hash value.

Exceptions

6.23.4.2 Generate a hash value of the contents of a file

Method Syntax

+ generateHash(FileInputStream fis, String algorithm): byte[]

Java sample code public byte[] generateHash(FileInputStream fis, String algorithm) throws NoSuchAlgorithmException, IOException ; Method description

This method is employed to generate hash value for a file using the given algorithm.

Parameters fis the File to be hashed. algorithm algorithm used to hash the data.

Return value byte[], a hash value.

Exceptions

IOException

6.23.5 Hash verification

6.23.5.1 Verify the hash value of the contents of an array of bytes

Method Syntax

+ verifyHash(byte[] data, byte[] hashValue, String algorithm): boolean

Java sample code public boolean verifyHash(byte[] data, byte[] hashValue, String algorithm) throws

NoSuchAlgorithmException ;

Method description

This method is employed to verify the hash value for the data using the given algorithm.

Parameters

Return value

Boolean, result of verification

Exceptions

6.23.6 Digital Signature generation

6.23.6.1 Generate the digital signature for an array of bytes

Method Syntax

+ generateSignature(byte[] data, String algorithm, String keyAlias, String password): byte[]

Java sample code public byte[] generateSignature(byte[] data, String algorithm, String keyAlias, String password) throws NoSuchAlgorithmException, InvalidKeyException, SignatureException, KeyStoreException, CertificateException, IOException, UnrecoverableEntryException, BadPropertyException, DeviceContextException ; Method description

This method is employed to generate signature for the data using the given algorithm and a private key. The private key is not explicitly specified as an input parameter, the given key alias is used to obtain the needed private key.

Parameters data data to be signed. algorithm algorithm used to sign the data. keyAlias alias for the private key which is to be used with the given algorithm to sign the data. password password for accessing the key entry with the given key alias.

Return value byte[],signature for the input data.

Exceptions

InvalidKeyException

KeyStoreException

IOException

6.23.7 Digital Signature verification

6.23.7.1 Verify the digital signature for an array of bytes

Method Syntax

+ verifySignature(byte[] data, byte[] signature, String algorithm, String keyAlias,

String password): Boolean

Java sample code public boolean verifySignature(byte[] data, byte[] signature, String algorithm, String keyAlias, String password) throws NoSuchAlgorithmException, InvalidKeyException, SignatureException, KeyStoreException, CertificateException, IOException, UnrecoverableEntryException, BadPropertyException, DeviceContextException ; Method description

This method is employed to verify the signature for the data with the given algorithm and a public key. The public key is not explicitly specified as an input parameter, the given key alias is used to obtain the needed public key.

Parameters data data which has the given signature. signature ignature for the given data algorithm algorithm used to verify the signature. keyAlias alias for the private key which is to be used to obtain its corresponding public key. password password for accessing the key entry with the given key alias.

Return value boolean, result of verification.

Exceptions

InvalidKeyException

SignatureException

KeyStoreException

IOException

6.23.8 Security Information Access

6.23.8.1 Get a certificate from the secure repository as an X.509 Certificate

Method Syntax

+ getCertificate(String keyAlias, String password): X509Certificate

Java sample code public X509Certificate getCertificate(String keyAlias, String password) throws SecurityManagerException, BadPropertyException, DeviceContextException ; Method description

This method is employed to retrieve a trusted certificate from the keyStore giving in input a valid alias.

Parameters keyAlias The alias needed to retrieve the Certificate. password The KeyStore password.

Return value

X509Certificate, The X.509 Certificate corresponding to the alias.

Exceptions

Method Syntax

+ getPrincipal(String keyAlias, String password): Principal

Java sample code public Principal getPrincipal(String keyAlias, String password) throws SecurityManagerException, BadPropertyException ; Method description

This method is used to obtain the CCD REL Principal to be inserted in a License. The Principal key name indicates the User's full name. The Principal key value contains the User's Public Key

Parameters keyAlias The keyAlias identifying the User. password The password necessary to retrieve the data from the KeyStore.

Return value

Principal, key value contains the User's RSA Public Key

Exceptions

6.23.8.3 Get a certificate from the secure repository as a DeviceID

Method Syntax

+ getDeviceID(String keyAlias, String password): DeviceID

Java sample code public DeviceID getDeviceID(String keyAlias, String password) throws SecurityManagerException, BadPropertyException, DeviceContextException ;

Method description

This method is used to obtain the DeviceID.

Return value

DeviceID

Exceptions

6.23.8.4 Export a certificate to a file

Interface SecurityManager

Method Syntax

+ exportCertificate(String keyAlias, String password, FileOutputStream fos): void

Java sample code public void exportCertificate(String keyAlias, String password, FileOutputStream fos) throws SecurityManagerException, IOException, BadPropertyException, DeviceContextException Method description

This method is employed to export a Device Certificate as a file in the file system.

Parameters keyAlias The alias for the certificate to be exported. password The password to get access to the KeyStore. fos The FileOutputStream referring to the File.

Return value

Exceptions

IOException

6.23.8.5 Get an array of licenses from the secure repository

In order to extract from the SecurityManager (see Error: Reference source not found) all the licenses governing a content item or a content element part of a content item, an instance of SecurityManager has to be created and initialised. Licenses are stored in the SecurityManager using the method addLicense in Section 5.9.3

Interface SecurityManager (see Error: Reference source not found)

+ getArrayOfLicenses (secureInfoAlias:String): RELLicense[]

Java sample code public interface SecurityManager { public RELLicense[] getArrayOfLicenses(String secureInfoAlias) throws IOException, SecurityManagerException, BadPropertyException; } Method description

This method is used to extract from the SecurityManager all the licenses governing a content item or a content element part of a content item.

Parameters secureInfoAlias The identifier of the content item or content element part of a content item whose licenses are sought.

Return value

An array containing all the licenses (see Error: Reference source not found) found in the Security Manager’s repository for the content item or content element whose identifier was specified in input.

Exceptions

IOException This exception is thrown if problems occurred while reading from the secure repository.

6.23.8.6 Get a list of licenses from the secure repository

Method Syntax

+ getLicenses(String secureInfoAlias): List

Java sample code public List getLicenses(String secureInfoAlias) throws IOException, SecurityManagerException, BadPropertyException ; Method description

This method is employed to retrieve secure License information using the given alias from the infostore indicated by its infoStoreLocation.

Parameters secureInfoAlias alias for the entry of the secure information.

List,all Licenses found for a certain ResourceID or ContentID.

Exceptions

IOException

6.23.8.7 Get user information from the secure repository

Method Syntax

+ getSecureInfo(String secureInfoAlias): List

Java sample code public List getSecureInfo(String secureInfoAlias) throws IOException, SecurityManagerException, DeviceContextException, BadPropertyException ; Method description

This method is employed to retrieve secure User information using the given alias from the infostore indicated by its infoStoreLocation.

Return value

List, all pieces of secure information with the given Alias.

Exceptions

IOException

6.23.8.8 Get domain information from the secure repository

Method Syntax

Java sample code public List getSecureDomainInfo(String secureInfoAlias) throws SecurityManagerException, BadPropertyException ; Method description

This method is employed to retrieve secure Domain information using the given alias from the infostore indicated by its domainInfoStoreLocation.

Return value

List, all pieces of secure information with the given Alias

Exceptions

6.23.9 Authentication

6.23.10 Trust verification

6.23.10.1 Digital Signature verification

6.23.11 Secure information storage

6.23.11.1 Store a license

Interface SecurityManager (see Error: Reference source not found)

Method Syntax

+ addLicense (secureInfoAlias:String, license:RELLicense): void

Java sample code public interface SecurityManager { public void addLicense(String secureInfoAlias, RELLicense license) throws IOException, SecurityManagerException, BadPropertyException; } Method description

This method is used to store a license in the secure repository managed by the SecurityManager. The license to be stored is associated to an alias which will be required in order to retrieve the license from the SecurityManager later on by using the method specified in Error: Reference source not found. The alias to be used is either the content ID or the content element ID, depending on whether the license governs a content item or a content element.

Parameters

License An object of type RELLicense as specified in Error: Reference source not found

Return value

Exceptions

IOException This exception is thrown if problems occurred while writing to the secure repository.

6.23.11.2 Store usser information

Method Syntax

+ addSecureInfo(String secureInfoAlias, String secureInfo): void

Java sample code public void addSecureInfo(String secureInfoAlias, String secureInfo) throws IOException, SecurityManagerException, DeviceContextException, BadPropertyException ; Method description

This method is employed to store User information with the given alias into the License infostore indicated by its licenseInfoStoreLocation.

Parameters secureInfoAlias alias for the entry of the secure information. secureInfo secure License information.

Return value

Exceptions

IOException

6.23.11.3 Store a key into the secure repository

Method Syntax

+ addSecretKey(String keyAlias, String algorithm, int keysize, String pwdKeyStore, String pwdKeyEntry): void

Java sample code public void addSecretKey(String keyAlias, String algorithm, int keysize, String pwdKeyStore, String pwdKeyEntry) throws KeyStoreException, NoSuchAlgorithmException, CertificateException, IOException, NoSuchProviderException, BadPropertyException, DeviceContextException ; Method description

This method is employed to add a secret key(symmetric key) to the keystore, which is to be used for symmetric cipher.

Parameters keyAlias alias for the entry of the secret key. algorithm the symmetric algorithm used to generate a secret key. keysize the size of the key you want, which must be supported by the given algorithm. pwdKeyStore password for the keystore. pwdKeyEntry password for the key entry.

Return value

Exceptions

KeyStoreException

IOException

NoSuchProviderException

6.23.11.4 Create a Private Key for a new user and store it into the secure repository

+ createUserEntry (String keyAlias, String password, PrivateKeyEntry privateKeyEntry): void

Java sample code public void createUserEntry (String keyAlias, String password, PrivateKeyEntry privateKeyEntry) throws IOException, NoSuchAlgorithmException, InvalidKeyException, CertificateException, NoSuchProviderException, SignatureException, KeyStoreException, JAXBException, DeviceContextException, BadPropertyException, SecurityManagerException ; Method description

This method is used to add a new user entry in the KeyStore. If the privateKeyEntry parameter is null, a new public/private key pair and a self certificate will be created.

Parameters keyAlias The alias used to Store the new entry in the KeyStore.

Password The password for retrieving the entry in the KeyStore associated to the alias specified. privateKeyEntry The PrivateKeyEntry to store in the KeyStore associated to the username. If this parameter is null, a test privateKeyEntry will be generated. The PrivateKeyEntry, if specified, shall contain an RSA key pair and the signature shall be of type "MD5WithRSA".

Return value

Exceptions

IOException

InvalidKeyException

SignatureException

NoSuchProviderException

KeyStoreException

JAXBException

Method Syntax

+ importCertificate(String keyAlias, String password, FileInputStream fis): String

Java sample code public String importCertificate(String keyAlias, String password, FileInputStream fis) throws NoSuchAlgorithmException, CertificateException, KeyStoreException, UnrecoverableEntryException, IOException, UnsupportedFeatureException, BadPropertyException, DeviceContextException ; Method description

This method is employed to import an X509 Certificate belonging to another Device in a Device's Key Store. The alias of the new Certificate will be the Name in the X500Name structure part of the X509 Certificate.

Parameters keyAlias the KeyAlias for the new Certificate. If null, the Name in the X500Name structure part of the X509 Certificate will be used, to which the '#' is added, plus the certificate serial number. password The password necessary to retrieve the data from the KeyStore. fis The FileInputStream of the Certificate File.

Return value

String, the keyAlias employed

Exceptions

KeyStoreException

IOException

6.23.11.6 Store a certificate from a KeyInfo in the secure repository

Interface SecurityManager

Method Syntax

+ importCertificate (String keyAlias, String password, KeyInfo keyInfo): boolean

© ISO/IEC 2009 — All rights reserved 135 ISO/IEC CD 23006-2 Java sample code public boolean importCertificate (String keyAlias, String password, KeyInfo keyInfo) throws Base64DecodingException, JAXBException, CertificateException, NoSuchAlgorithmException, KeyStoreException, UnrecoverableEntryException, IOException, DeviceContextException, BadPropertyException Method description

This method is employed to import an X509 Certificate belonging to another Device in a Device's Key Store.

Parameters keyAlias the KeyAlias for the new Certificate. password The password to get access to the KeyStore. keyInfo The KeyInfo element containing the Certificate.

Return value

Boolean, TRUE if the operation is concluded successfully.

Exceptions

Base64DecodingException

JAXBException

KeyStoreException

IOException

6.23.11.7 Store domain information in the secure repository

Method Syntax

+ addSecureDomainInfo(String secureInfoAlias, String secureInfo): void

Java sample code public void addSecureDomainInfo(String secureInfoAlias, String secureInfo) throws IOException, SecurityManagerException, DeviceContextException, BadPropertyException ; Method description

This method is employed to store Domain information with the given alias into the Domain infostore indicated

Parameters secureInfoAlias alias for the entry of the secure information. secureInfo secure Domain information.

Return value

Exceptions

IOException

6.23.12 Security Information deletion

6.23.12.1 Delete a trusted certificate from the secure repository

Method Syntax

+ deleteCertificate(String keyAlias, String password): void

Java sample code public void deleteCertificate(String keyAlias, String password) throws IOException, NoSuchAlgorithmException, CertificateException, KeyStoreException, UnrecoverableEntryException, BadPropertyException, DeviceContextException ; Method description

This method is employed to delete a trusted certificate from the keyStore giving in input a valid alias.

Parameters keyAlias The alias needed to retrieve the Certificate. password The KeyStore password.

Return value void.

Exceptions

IOException

KeyStoreException

6.23.12.2 Delete a license from the secure repository

Method Syntax

+ deleteLicenses(String secureInfoAlias, String secureInfo): void

Java sample code public void deleteLicenses(String secureInfoAlias, String secureInfo) throws IOException, SecurityManagerException, DeviceContextException, BadPropertyException ; Method description

This method is employed to delete License information with the given alias from the License infostore indicated by its licenseInfoStoreLocation.

Return value

Exceptions

IOException

6.23.12.3 Delete user information from the secure repository

Method Syntax

+ deleteSecureInfo(String secureInfoAlias, String secureInfo): void

138 © ISO/IEC 2009 — All rights reserved Java sample code public void deleteSecureInfo(String secureInfoAlias, String secureInfo) throws IOException, SecurityManagerException, DeviceContextException, BadPropertyException ; Method description

This method is employed to delete User information with the given alias from the License infostore indicated by its licenseInfoStoreLocation.

Return value

Exceptions

IOException

6.23.12.4 Delete domain information from the secure repository

Method Syntax

+ deleteSecureDomainInfo(String secureInfoAlias, String secureInfo): void

Java sample code public void deleteSecureDomainInfo(String secureInfoAlias, String secureInfo) throws IOException, SecurityManagerException, DeviceContextException, BadPropertyException ; Method description

This method is employed to delete Domain information with the given alias from the Domain infostore indicated by its domainInfoStoreLocation.

Parameters secureInfoAlias alias for the entry of the secure information. secureInfo secure Domain information.

Return value

Exceptions

IOException

6.23.13 Miscellanea

6.23.13.1 Verify a REL Principal

Method Syntax

+ verifyPrincipal(String keyAlias, String password, Principal principal): boolean

Java sample code public boolean verifyPrincipal(String keyAlias, String password, Principal principal) throws SecurityManagerException, BadPropertyException, UnsupportedFeatureException ; Method description

This method is used to verify the existence of a certificate expressed as an REL Principal in the secure repository.

Return value

Boolean

Exceptions

6.23.13.2 Method to generate and embed the digital signature for an XML document

Interface -

Method Syntax

+ addXMLSignature(String xmlDocument, String digestMethod, String signatureMethod, PrivateKey privateKey, Certificate certificate): String

140 © ISO/IEC 2009 — All rights reserved Java sample code public String addXMLSignature(String xmlDocument, String digestMethod, String signatureMethod, PrivateKey privateKey, Certificate certificate) throws Exception ; Method description

This method is employed to generate a digital signature and embed it into an XML document. It assumes that the digital signature will be computed over the whole XML document and embedded into it in a element at the end of the XML document. Moreover, the input Certificate will be also embedded into the resulting signed XML document in a element inside the element where the signature is embedded.

Parameters xmlDocument XML document to be signed. digestMethod Digest method applied to the whole XML document to get the digest to be signed (e.g. http://www.w3.org/2000/09/xmldsig#sha1). signatureMethod Signature method applied over the digest (e.g. http://www.w3.org/2000/09/xmldsig#rsa-sha1). privateKey Private key to be used to compute the signature. certificate X509 certificate which includes the public key corresponding to the private key used to compute the signature.

Return value String, the XML document including the digital signature.

Exceptions

Exception

6.23.13.3 Method to verify the digital signature for an XML document

Interface -

Method Syntax

+ verifyXMLSignature(String xmlDocument): Boolean

Java sample code public boolean verifyXMLSignature(String xmlDocument, String keyAlias, String password) throws Exception ; Method description

This method is employed to verify the signature present in a XML document, assuming that the public key is embedded in the XML document (e.g. in the XMLDSIG KeyInfo-X509Data- X509Certificate element).

Parameters xmlDocument XML document that includes the XML signature to be checked

Return value

Exceptions

Exception

6.23.13.4 Method to authenticate a User with Password

Interface -

Method Syntax

+ authenticateUser(String userName, String password): String

Java sample code public String authenticateUser(String userName, String password) throws Exception; Method description

This method is employed to retrieve a SAML token that contains the credentials of the user, and which is digitally signed by a trusted entity. The SAML token can be used to authenticate the user against any other service in the system. The token may have a validity period or may be also restricted to be used just once.

Parameters userName Name or nick of the user in the system. password Password used by the user to prove his identity.

Return value

String, an XML piece that represents the SAML token, which contains the credentials of the user.

Exceptions

Exception

6.23.13.5 Method to authenticate user with password and user certificate

Interface -

Method Syntax

+ authenticateUser(String userName, String password, X509Certificate userCertificate): String

Java sample code public String authenticateUser(String userName, String password, X509Certificate userCertificate) throws Exception; Method description

This method is employed to retrieve a SAML token that contains the credentials of the user, and

142 © ISO/IEC 2009 — All rights reserved which is digitally signed by a trusted entity. The SAML token can be used to authenticate the user against any other service in the system. The token may have a validity period or may be also restricted to be used just once.

With respect to the previous method, this method is assumed to be run over SSL, using a x509 certificate that identifies the user. This certificate can be optionally sent as an input argument. The authentication service will determine the x509 certificate that has been used, it will extract the user information and it will consult an external OCSP service to determine whether it is or not revoked. If the certificate is not revoked and the user credentials are correct, it will return the corresponding SAML token.

Parameters userName Name or nick of the user in the system. password Password used by the user to prove his identity. userCertificate The userCertificate corresponding to the user that is requesting authentication

Return value

String, an XML piece that represents the SAML token, which contains the credentials of the user.

Exceptions

Exception

Note: Other authentication alternatives may be also accepted, as the authentication in each transaction based on user/password or based on an X509 client Certificate.

6.23.13.6 Method to estimate the fingerprint of a tool

Interface -

Method Syntax

+ estimateToolFingerprint (): String

Java sample code public String estimateToolFingerprint () throws Exception; Method description

This method is employed to extract relevant features about the device (operating system) and/or the software tool that is requesting the authorisation of a user action. This information can be used to be registered during the first usage attempt of the tool in the system so that it can be later checked for integrity.

Return value

String, an XML piece that represents the relevant features about the device (operating system) and/or the software tool.

Exceptions

Exception

6.23.13.7 Method to enable or certify the operation of a tool

Interface -

Method Syntax

+ certifyTool (String toolFingerprint, String userToken): String

Java sample code public CertificationResult certifyTool (String toolFingerprint, String userToken) throws Exception; Method description

This method is employed to check the integrity of a software tool prior to its first usage. Some features regarding the device (operating system) and/or the software tool that is requesting the authorisation of a user action will be registered so that they can be later checked for integrity.

Parameters toolFingerprint An XML piece that represents the relevant features about the device (operating system) and/or the software tool. userToken An XML piece that represents the SAML token, which contains the credentials of the user.

Return value

CertificationResult, a class that contains the following information:

- Int certificationResult: the result of the certifyTool process

- Byte[] toolPKCS12: an X509 certificate and private key that identify the certified tool. The X509 certificate includes a unique tool identifier and an enabling code that can be used for the selfVerify process.

Exceptions

Exception

6.23.13.8 Method to verify locally the integrity of a tool

Interface -

Method Syntax

+ selfVerifyTool (String toolFingerprint): String

Java sample code public String selfVerifyTool (String toolFingerprint) throws Exception; Method description

This method is employed to locally check the integrity of a software tool during its whole life operation. The features regarding the device are used to compute a security code and

Parameters toolFingerprint An XML piece that represents the relevant features about the device (operating system) and/or the software tool.

Return value

String, the result of the verifyTool process

Exceptions

Exception

6.23.13.9 Method to verify remotely the integrity of a tool

Interface -

Method Syntax

+ verifyTool (String toolFingerprint, String userToken): String

Java sample code public String verifyTool (String toolFingerprint, String userToken) throws Exception; Method description

This method is employed to remotely check the integrity of a software tool during its whole life operation. Some features regarding the device (operating system) and/or the software tool that is requesting the authorisation of a user action are sent to be compared to those registered in the certifyTool process.

Parameters toolFingerprint An XML piece that represents the relevant features about the device (operating system) and/or the software tool. userToken An XML piece that represents the SAML token, which contains the credentials of the user.

Return value

String, the result of the verifyTool process

Exceptions

Exception

6.23.13.10 Method to disable to operation of a tool

Interface -

Method Syntax

Java sample code public String disableTool () throws Exception; Method description

This method is employed to disable the operation of a software tool due to any problem detected during the verifyTool process. The tool will be deactivated in the device where it is running.

Return value

String, the result of the disableTool operation

Exceptions

Exception

6.24 MVCO Engine APIs

MPEG is standardizing an MPEG Media Value Chain Ontology (Part 19). Having digitally represented the Intellectual Property Model allows different MXM Devices to validate their IP operations against a common established model.

In practice, accessing the OWL file and reasoning over it is a non-trivial task, common to several Devices. MXM-MVCO is proposed as an API to facilitate this operation.

This API is based in methods using only basic datatypes (defining only the appropiate Exception), making its use inmediate and stratightforward.

Interface MVCOInterface

Method Syntax

+ Load(String sURI): boolean

Java sample code public boolean Load(String sURI) throws IOException; Method description

This method is employed to load a set of assertions from a URI. This method is additive, i.e., loading a second set of data does not replace the existing one.

Data loaded includes Users, IP Entities (Digital Items), Permissions and Actions performed.

Parameters sURI Any URI making reference to an existing data repository. It can be a file, for example: file:///test.owl, but also database or a remote location (http://abc.com/test.owl).

Return value

True on success

Exceptions

IOException If the URI is not reachable.

Method Syntax

+ Store(String sURI): boolean

Java sample code public boolean Store(String sURI) throws IOException; Method description

This method is employed to store a set of assertions from a URI

Parameters sURI Any URI making reference to an existing data repository. It can be a file, for example: file:///test.owl, but also database or a remote location (http://abc.com/test.owl).

Return value

True on success

Exceptions

IOException If the URI is not reachable.

6.24.1.3 Operation to unload the current data set.

Method Syntax

+ Unload(): boolean

Java sample code public boolean Unload(); Method description

This method is employed to unload the assertions in the ontology. No individuals will remain after calling this operation.

Parameters

Return value

True on success

Method Syntax

+ CreateUser(String sUserId): boolean

Java sample code public boolean CreateUser(String sUserId) throws ExistingIdException, BadIdException; Method description

This method is employed to create a new User, identified by a user id. The new User does not assume any role a priori.

Parameters sUserId Any User identification string, provided the following:

 It can only start with alphabetic characters: [a-z][A-Z]

 It can be made of alphanumeric characters [a-z][A-Z][0-9], explicitly excluding blank spaces, commas or any other non- alphanumeric character

Return value

True on success

Exceptions

ExistingIdException If the identifier already exists.

BadIdException The id string is malformed

Method Syntax

+ DeleteUser(String sUserId): boolean

Java sample code public boolean DeleteUser(String sUserId) throws ExistingIdException, BadIdException; Method description

This method is employed to unregister an existing User, identified by a user id.

Parameters sUserId Any User identification string, provided the following:

 It can only start with alphabetic characters: [a-z][A-Z]

 It can be made of alphanumeric characters [a-z][A-Z][0-9], explicitly excluding blank spaces, commas or any other non- alphanumeric character

Return value

True on success

Exceptions

ExistingIdException If the user identifier does not exist in the ontology.

BadIdException The id string is malformed

Method Syntax

+ ExecuteAction(String sActedBy, String sAction, String sIPEntity, String sNewIPEntity): boolean

Java sample code public boolean ExecuteUser(String sActedBy, String sAction, String sIPEntity, String sNewIPEntity) throws BadIdException, IllegalActionException, ExistingIdException; Method description

This method is employed for an User to execute an Action over an IPEntity, possible creating a new IPEntity.

Parameters sActedBy User id acting the action. sAction Action to be performed (e.g. “Render”, “CreateWork”) sIPEntity Existing IPEntity id over which the Action is executed sNewIPEntity New id to for the IPEntity to be created –if needed. This parameter may be an empty string, or a null.

Return value

True on success

Exceptions

IllegalActionException An operation cannot be performed over a given IPEntity.

ExistingIdException The given id points to a non-existing User, Action or IPEntity.

6.24.1.7 Operation to create a permission.

Method Syntax

+ CreatePermission(String sIssuedBy, String sAction, String sActedOver, String sActedBy): boolean

Java sample code public boolean CreatePermission(String sIssuedBy, String sAction, String sActedOver, String sActedBy) throws BadIdException, IllegalActionException, ExistingIdException; Method description

This method is employed for an User to generate the permission to execute an Action over an IPEntity, by other User.

Parameters sIssuedBy User id issuing the permission. sAction Action to be performed (e.g. “Render”, “CreateWork”) sActedOver Existing IPEntity id over which the Action is authorised to be executed sActedBy User id of the authorised User.

Return value

True on success

Exceptions

IllegalActionException An operation cannot be performed over the given IPEntity.

BadIdException An id string is malformed, either in the User, the Action or the IPEntity

Method Syntax

+ Query(String sSPARQL): Vector

Java sample code public Vector Query(String sSPARQL) throws MalformedQueryException; Method description

This method is employed to retrieve information on the ontology. The operation always retrieves information.

Note that along 2009 “SPARQL Update” is likely to be declared W3C recommendation. If this happens, queries could change the ontology, radically altering the scope of this function.

Parameters sSPARQL String with the SPARQL query. This string has to be formed according to the W3C recommendation2.

Return value

A vector with the strings returned as a response to the query, if this was successful, or empty vector i fit was not.

Exceptions

MalformedQueryException The query execution returned an error.

2 http://www.w3.org/TR/rdf-sparql-query/

Method Syntax

+ Validate(String sAction, String sActedOver, String sActedBy): boolean

Java sample code public boolean Validate(String sAction, String sActedOver, String sActedBy) throws BadIdException, IllegalActionException, ExistingIdException; Method description

This method is employed to validate an action, giving a boolean answer (yes/no).

Parameters sAction Action to be authorised (e.g. “Render”, “CreateWork”) sActedOver Existing IPEntity id over which the Action is being validated. sActedBy User id of the User under validation.

Return value

True if the operation is validated.

Exceptions

IllegalActionException An operation cannot be performed over the given IPEntity.

Method Syntax

+ getUsers(): Vector

Java sample code public Vector getUsers(); Method description

This method is employed to retrieve the list of existing Users

Return value

A vector with the String of the User id´s registered in the ontology.

Exceptions

6.24.1.11 Operation to get the list of registered IPEntities.

Method Syntax

+ getIPEntities(): Vector

Java sample code public Vector getIPEntities(); Method description

This method is employed to retrieve the list of existing IPEntities

Return value

A vector with the String of the IPEntities id´s registered in the ontology.

Exceptions

Method Syntax

+ getRightsOwner(String sIPEntity): String

Java sample code public boolean getRightsOwner(String sAction, String sActedOver, String sActedBy) throws BadIdException, ExistingIdException; Method description

This method retrieves the rights Owner of a given IPEntity. It does not retrieve which users have been authorised in valid Parmissions.

This method is redundant and given for convenience, as the query could be performed by means of the Query method.

Parameters sIPEntity IPEntity to be queried

Return value

User id owner of the IPEntity rights.

Exceptions

Method Syntax

+ getOrigin(String sIPEntity): String

Java sample code public String getOrigin(String sIPEntity) throws BadIdException, ExistingIdException; Method description

This method returns the IPEntity that has given rise to the current IPEntity. If the IPEntity is a Work, a null will be returned.

This method is redundant and given for convenience, as the query could be performed by means of the Query method.

Parameters sIPEntity IPEntity to be queried

Return value

IPEntity id from which the given IPEntity id comes from.

Exceptions

6.25.1 Domain Management

<> DomainManagement + createDomain(dmdURI:String, credential:DomainCredentialType, domainExpiration:ValidityTimeMetered, maxNumOfDevices:Long, maxNumOfUsers:Long, maxFrequencyOfUpdateDevice:Duration, maxFrequencyOfUpdateUser:Duration):String + renewDomain(dmdURI: String, credential:DomainCredentialType, domainID:String, domainExpiration:ValidityTimeMetered, maxNumOfDevices:Long, maxNumOfUsers:Long, maxFrequencyOfUpdateDevice:Duration, maxFrequencyOfUpdateUser:Duration):void + deleteDomain(dmdURI:String, credential:DomainCredentialType, domainID:String):void + addDevice(dmdURI:String, credential:DomainCredentialType, domainID:String, expiration:ValidityTimeMetered):void + addUser(dmdURI:String, credential:DomainCredentialType, domainID:String, userID :String, expiration:ValidityTimeMetered):void + renewDevice(dmdURI:String, credential:DomainCredentialType, domainID:String, expiration: ValidityTimeMetered):void + renewUser(dmdURI:String, credential:DomainCredentialType, domainID:String, userID:String, expiration: ValidityTimeMetered):void + leaveDevice(dmdURI:String, credential:DomainCredentialType, domainID:String):void + leaveUser(dmdURI:String, credential:DomainCredentialType, domainID:String, userID :String):void

DomainManagementException Exception

6.25.1.1 Create Domain

Creation of a Domain

Interface DomainManagement

Method Syntax

+ createDomain(dmdURI:String, credential:DomainCredentialType, domainExpiration: ValidityTimeMetered, maxNumOfDevices:Long, maxNumOfUsers:Long, maxFrequencyOfUpdateDevice:Duration, maxFrequencyOfUpdateUser:Duration):String

Java sample code public interface DomainManagement { public String createDomain(String dmdURI, DomainCredentialType credential, ValidityTimeMetered domainExpiration, Long maxNumOfDevices,Long maxNumOfUsers, Duration maxFrequencyOfUpdateDevice, Duration maxFrequencyOfUpdateUser) throws DomainManagementException } Method description

This method is used to create a Domain which is managed by the specified Domain Management Device (DMD). Using this method, Domain administrator can specify the conditions for Domain initialisation. If the Domain creation is successful, this method returns the Domain ID given by the Domain Identification Device (DoID).

Parameters dmdURI The URI of DMD which will create the Domain

© ISO/IEC 2009 — All rights reserved 159 ISO/IEC CD 23006-2 and manage the newly created Domain credential The Domain administrator’s credential. With this credential, DMD checks if the Domain administrator has enough privilege to create the Domain, and the management of the newly created Domain request this credential domainExpiration The valid period of the newly created Domain. maxNumOfDevices The maximum number of the Devices which can be added to the newly created Domain maxNumOfUsers The maximum number of the Users which can be added to the newly created Domain maxFrequencyOfUpdateDevice The shortest duration permitted between a device leaving and re-registering with this Domain maxFrequencyOfUpdateUser The shortest duration permitted between a User leaving and re-registering with this Domain

Return value

The Domain ID given by the Domain Identification Device (DoID).

Exceptions

DomainManagementException

6.25.1.2 Renew Domain

Renewal of a Domain

Method Syntax

+ renewDomain(dmdURI: String, credential:DomainCredentialType, domainID:String, domainExpiration:ValidityTimeMetered, maxNumOfDevices:Long, maxNumOfUsers:Long, maxFrequencyOfUpdateDevice:Duration, maxFrequencyOfUpdateUser:Duration):void

Java sample code public interface DomainManagement { public void renewDomain(String dmdURI, DomainCredentialType credential, String domainID,ValidityTimeMetered domainExpiration, Long maxNumOfDevices, Long maxNumOfUsers, Duration maxFrequencyOfUpdateDevice, DurationaxFrequencyOfUpdateUser) throws DomainManagementException } Method description

This method is used to renew the specified Domain. Using this method, Domain administrator can renew the conditions of the Domain. This method requires the Domain administrator’s credential.

Parameters dmdURI The URI of DMD which is managing the Domain to be renewed

160 © ISO/IEC 2009 — All rights reserved credential The Domain administrator’s credential. With this credential, DMD checks if the Domain administrator has enough privilege to renew the Domain domainID The ID of the Domain to be renewed domainExpiration The valid period of the renewed Domain maxNumOfDevices The maximum number of the Devices in the renewed Domain maxNumOfUsers The maximum number of the Users in the renewed Domain maxFrequencyOfUpdateDevice The shortest duration permitted between a device leaving and re- registering with the renewed Domain maxFrequencyOfUpdateUser The shortest duration permitted between a User leaving and re- registering with the renewed Domain

Return value void

Exceptions

6.25.1.3 Delete Domain

Cancellation of a Domain

Method Syntax

+ deleteDomain(dmdURI:String, credential:DomainCredentialType, domainID:String):void

Java sample code public interface DomainManagement { public void deleteDomain(String dmdURI, DomainCredentialType credentialType, String domainID) throws DomainManagementException } Method description

This method is used to delete the specified Domain. This method requires the Domain administrator’s credential.

Parameters dmdURI The URI of DMD which is managing the Domain to be deleted credential The Domain administrator’s credential, with which DMD checks if the Domain administrator has enough privilege to delete the Domain domainID The ID of the Domain to be deleted

Return value

Exceptions

6.25.1.4 Add Device

Add a Device to a Domain

Method Syntax

+ addDevice(dmdURI:String, credential:DomainCredentialType, domainID:String, expiration:ValidityTimeMetered):RELLicense

Java sample code public interface DomainManagement {

public RELLicense addDevice(String dmdURI, DomainCredentialType credential, String domainID,ValidityTimeMetered expiration) throws DomainManagementException

Method description

This method is used to add a Device to the specified Domain. If this addition process is successful, the Device acquires the Domain membership license from DMD. This method requires the Domain member’s credential.

Parameters dmdURI The URI of DMD which is managing the Domain to which the Device is added credential The Domain member credential, with which DMD checks if this request has enough privilege to add the Device domainID The ID of the Domain to which the Device is added expiration the expiration date of the Domain membership

Return value

The domain membership license.

Exceptions

6.25.1.5 Add User

Add a User to a Domain

Method Syntax

+ addUser(dmdURI:String, credential:DomainCredentialType, domainID:String, userID:String, expiration:ValidityTimeMetered):RELLicense

Java sample code public interface DomainManagement { public RELLicense addUser(String dmdURI, DomainCredentialType credential, String domainID, String userID, ValidityTimeMetered expiration) throws DomainManagementException } Method description

This method is used to add a User to the specified Domain. If this addition process is successful, the User acquires the Domain membership license from DMD. This method requires the Domain member’s credential.

Parameters dmdURI The URI of DMD which is managing the Domain to which the User is added credential The Domain member credential, with which DMD checks if the User has enough privilege to be added domainID The ID of the Domain to which the User is added userID The ID of the User to which the User is added expiration the expiration date of the Domain membership

Return value

Exceptions

6.25.1.6 Renew Device

Renew membership of a Device of a Domain

Method Syntax

+ renewDevice(dmdURI:String, credential:DomainCredentialType, domainID:String, expiration: ValidityTimeMetered):RELLicense

Java sample code public interface DomainManagement { public void renewDevice(String dmdURI, DomainCredentialType credential, String domainID,ValidityTimeMetered expiration) throws DomainManagementException } Method description

This method is used to renew the Device in the specified Domain. If this addition process is successful, the Device acquires the Domain membership license from DMD. This method requires the Domain member’s credential.

Parameters dmdURI The URI of DMD which is managing the Domain, the Device of which is renewed credential The Domain member credential, with which DMD checks if the Device has enough privilege to be renewed domainID The ID of the Domain, the Device of which is renewed expiration the new expiration date of the Domain membership

Return value

Exceptions

6.25.1.7 Renew User

Renew membership of a User of a Domain

Method Syntax

+ renewUser(dmdURI:String, credential:DomainCredentialType, domainID:String, userID:String, expiration: ValidityTimeMetered):RELLicense

Java sample code public interface DomainManagement { public RELLicense renewUser(String dmdURI, DomainCredentialType credential, String domainID, String userID, ValidityTimeMetered expiration) throws DomainManagementException } Method description

This method is used to renew the User in the specified Domain. If this addition process is successful, the User acquires the Domain membership license from DMD. This method requires the Domain member’s credential.

Parameters dmdURI The URI of DMD which is managing the Domain, the User of which is renewed credential The Domain member credential, with which DMD checks if the User has enough privilege to be renewed domainID The ID of the Domain, the User of which is renewed

Return value

Exceptions

6.25.1.8 Leave Device

Remove a Device from a Domain

Method Syntax

+ leaveDevice(dmdURI:String, credential:DomainCredentialType, domainID:String):void

Java sample code public interface DomainManagement { public void leaveDevice(String dmdURI, DomainCredentialType credential, String domainID) throws DomainManagementException } Method description

This method is used to remove a Device from the specified Domain. If this addition process is successful, the Device loses the Domain membership license. This method requires the Domain member’s credential.

Parameters dmdURI The URI of DMD which is managing the Domain, the Device of which is removed credential The Domain member credential, with which DMD checks if the Device has enough privilege to be removed domainID The ID of the Domain, the Device of which is removed

Return value void

Exceptions

6.25.1.9 Leave User

Remove a User from a Domain

+ leaveUser(dmdURI:String, credential:DomainCredentialType, domainID:String, userID:String):void

Java sample code public interface DomainManagement { public void leaveUser(String dmdURI, DomainCredentialType credential, String domainID, String userID) throws DomainManagementException } Method description

This method is used to remove a User from the specified Domain. If this addition process is successful, the User loses the Domain membership license. This method requires the Domain member’s credential.

Parameters dmdURI The URI of DMD which is managing the Domain, the Device of which is removed credential The Domain member credential, with which DMD checks if the User has enough privilege to be removed domainID The ID of the Domain, the Device of which is removed userID The ID of the User to be removed

Return value void

Exceptions

6.25.1.10 RequestLocalDomainID

Request a domain identification service for the identification of a new domain

Method Syntax

+ requestLocalDomainID():RELLicense

Java sample code public interface DomainManagement { public void requestLocalDomainID() throws DomainManagementException } Method description

This method is used to request a domain identification service for the identification of a new domain. If this addition process is successful, the domain identification service returns an unique identification.

Return value

The Domain ID given by the Domain Identification Device (DoID).

6.25.2 Domain Access

This section comprises of the APIs to query the DMD for the status of a Domain

<> DomainAccess

+ requestDomainManageInfo (dmdURI:String, domainID :String, credential:DomainCredentialType ):void

DomainAccessException Exception

6.25.2.1 RequestDomainPublicInfo

Request DMD(Domain Management Device ) for information about a specific Domain.

Tipically License Provider Device or a Content Creation Device issues this request.

Interface DomainAccess

Method Syntax

+ requestDomainPublicInfo(dmdURI:String, domainID:String):DomainPublicInfo

Java sample code public interface DomainManagement { public DomainPublicInfo requestDomainPublicInfo (String dmdURI,String domainID) throws DomainManagementException } Method description

This method is used to request Domain Management Device (DMD) for the information about a specific Domain. (e.g. how many Devices are part of the Domain, when is the Domain expiring, what is the Domain Public Key, etc.). If the request was successful, it returns DomainPublicInfo with the given domain ID.

Return value

DomainPublicInfo which includes

DomainID,DomainKey,Registration,Expiration,MaximumNumberOfUsers, MaximumFrequencyOfUpdateUser, UserID,expiration of the user,MaximumNumberOfDevices,MaximumFrequencyOfUpdateDevice,DeviceID and expiration of the device.

DomainAccessException

6.25.3 Domain Usage

Collection of interface functions to access and manage the Domain usage information and the Domain rights information in the local storage

<> DomainUsage + getDomainLicense (domainID :String):RELLicense + storeDomainLicense (domainLicense :RELLicense):void + deleteDomainLicense (domainID :String) :void + updateDomainLicense (domainLicense :RELLicense) :void + startDomainUse (domainID :String, contentGroupID :List, startTime :XMLGregorianCalendar) :void + endDomainUse(domainID :String, endTime:XMLGregorianCalendar):void

DomainUsageException Exception

6.25.3.1 Get Domain License

Read Domain license from local storage

Interface DomainUsage

Method Syntax

+ getDomainLicense(domainID:String):RELLicense

Java sample code public interface DomainUsage { public void getDomainLicense(String domainID) throws DomainUsageException } Method description

This method is used to read a Domain license which is locally stored in the End User Device (EUD). Using this method, EUD can use the Domain license when the EUD wants to access a content licensed to the Domain. If getDomainLicense is successfully done, this method returns the Domain license.

Parameters

Return value

The license for the domain which has the given DomainID.

Exceptions

DomainUsageException

6.25.3.2 Store Domain License

Write domain license to local storage

Method Syntax

+ storeDomainLicense(strDomainID:String, DomainLicense:RELLicense):void

Java sample code public interface DomainUsage { public void storeDomainLicense(String strDomainID, RELLicense domainLicense) throws DomainUsageException } Method description

This method is used to write a Domain license to a local storage in the End User Device (EUD). This method is most likely used after addDevice method. Using this method, EUD can store the Domain license for later use in preparation of an access to content licensed to the Domain.

Parameters domainLicense Domain license.

Return value none

Exceptions

6.25.3.3 Delete Domain License

Delete Domain license from local storage

Method Syntax

+ deleteDomainLicense(domainID:String) :void

Java sample code

This method is used to delete a Domain license from a local storage in the End User Device (EUD). This method is most likely used after leaveDevice method.

Parameters domainID The string representation of Domain indentification.

Return value none

Exceptions

6.25.3.4 Update Domain License

Update domain license in the local storage

Method Syntax

+ updateDomainLicense(strDomainID:String, domainLicense:RELLicense) :void

Java sample code public interface DomainUsage { public void updateDomainLicense(String strDomainID, RELLicense domainLicense) throws DomainUsageException } Method description

This method is used to update a Domain license in a local storage in the End User Device (EUD). This method is most likely used after renewDevice method. Using this method, EUD can overwrite the domain license stored in the local storage which has the same domain ID with the given Domain license.

Parameters domainLicense Domain license.

Return value none

Exceptions

This method is used by an application, e.g. an End User Device part of a Domain to signal MXM to start recording usage data in the secure storage

Method Syntax

+ startDomainUse(domainID:String, contentGroupID:List, startTime:XMLGregorianCalendar) :void

Java sample code public interface DomainUsage { public void startDomainUse(String domainID, List contentGroupID, XMLGregorianCalendar startTime) throws DomainUsageException } Method description

This method is used to write usage data in a local storage in the End User Device (EUD). This method must be called when the EUD starts the usage of a content with Domain license. Using this method, EUD can write a new record of usage data in the local storage.

Parameters domainID The string representation of Domain indentification of the Domain that the content belongs. contentGroupID ContentGroupID of a content licensed to the Domain that EUD used. startTime Time when EUD starts the usage of a Domain licensed content.

Return value none

Exceptions

6.25.3.6 End Domain Use

This method is used by an application, e.g. an End User Device part of a Domain to signal MXM to stop recording usage data in the secure storage

Method Syntax

+ endDomainUse(domainID:String, endTime:XMLGregorianCalendar):void

Java sample code public interface DomainUsage { public void endDomainUse(String domainID, XMLGregorianCalendar startTime) throws DomainUsageException } Method description

This method is used to finalize a record of usage data in a local storage in the End User Device (EUD). This method must be called when the EUD ends the usage of a content with Domain license. Using this method, EUD can search for a usage data record with the given Domain ID and finalize it with given endTime.

Parameters domainID The string representation of Domain indentification of the Domain that a content belongs. endTime Time when EUD ends the usage of a Domain licensed content.

Return value none

Exceptions

6.25.4 UnlicensedSimultaneousUseNotice

Send a notification to DMD when an unlicensed simultaneous usage was detected at EUD.

Method Syntax

+ unlicensedSimultaneousUseNotice(useData:UseData):void

Java sample code public interface DomainUsage { public void unlicensedSimultaneousUseNotice (UseData useData) throws DomainUsageException } Method description

This method is used to send a notification to the Domain Manage Device(DMD). This method must be called when an unlicensed simultaneous usage was detected at the End User Device (EUD). Using this method, DMD can make decision if the domain license should sustain its validity at the next domain renewal.

Parameters useData A set of records that is created at each usage of a domain licensed content. Each record includes the identification of a device that used the content, contentGroupID of the content and the information about when the content was used.

Return value none

Exceptions

6.26 Rendering Engine APIs

6.26.1 getNumberOfScreens

Interface Interface MXMDevice{

Void getNumberOfScreens(Int numberOfScreens);

Method Syntax

+ getNumberOfScreens(Int numberOfScreens):

C sample code

Method description

This method queries the number of screens available.

Parameters numberOfScreens: Number of screens.

Return value

Exceptions

6.26.2 getScreen

Interface Interface MXMDevice{

MXMScreen getScreen(Int indexOfScreen);

Method Syntax

+ getScreen(Int indexOfScreen):

C sample code

Method description

This method returns an interface to one of the screens.

Return value

Exceptions

6.26.3 getAspectRatio

Interface Interface MXMScreen{

Void getAspectRatio(Int aspectX, Int aspectY);

Method Syntax

+ getAspectRatio(Int aspectX, Int aspectY):

C sample code

Method description

This method queries the aspect ratio of the output device, e.g. a 16:9 display.

Parameters aspectX: Nominator. aspectY: Denominator.

Return value

Exceptions

6.26.4 getNativeResolution

Interface Interface MXMScreen{

Void getNativeResolution(Int resolutionX, Int resolutionY);

Method Syntax

C sample code

Method description

This method queries the native pixel resolution of the output device, e.g. a 1920x1080 display.

Parameters resolutionX: Horizontal number of pixels in output. resolutionY: Vertical number of pixels in output.

Return value

Exceptions

6.26.5 setResolution

Interface Interface MXMView{

Void setResolution(Int resolutionX, Int resolutionY);

Method Syntax

+ setResolution(Int resolutionX, Int resolutionY):

C sample code

Method description

This method overrides the default resolution that will be used to initialize the new MXMView. Default is the same resolution as the parent MXMView or the resolution of the area that the view covers within its parent MXMView.

Parameters resolutionX: Horizontal number of pixels in buffer. resolutionY: Vertical number of pixels in buffer.

Return value

Exceptions

6.26.6 setPixelFormat

Void setPixelFormat(Bool rgb, Bool alpha, Bool indexed);

Method Syntax

+ setPixelFormat(Bool rgb, Bool alpha, Bool indexed):

C sample code

Method description

This method overrides the default pixel format that will be used to initialize the new MXMView. No explicit format may be selected, but the best format of the platform will be chosen.

Parameters rgb: Whether RGB or YUV will be used. alpha: Whether an alpha channel will be used. indexed: Whether the pixels will use a lookup table.

Return value

Exceptions

6.26.7 setPosition

Void setPosition(Int positionX, Int positionY);

Method Syntax

+ setPosition(Int positionX, Int positionY):

C sample code

Method description

Parameters positionX: Horizontal position within parent MXMView. positionY: Vertical position within parent MXMView.

Return value

Exceptions

6.26.8 setSize

Void setSize(Int sizeX, Int sizeY);

Method Syntax

+ setSize(Int sizeX, Int sizeY):

C sample code

Method description

This method overrides the output size used to display within the parent MXMView. Default is the same as the size of the MXMView..

Parameters sizeX: Horizontal number of pixels in buffer. sizeY: Vertical number of pixels in buffer.

Return value

Exceptions

6.26.9 initialize

Void initialize(MXMView parentView) raise(Exceptions);

Method Syntax

+ initialize(MXMView parentView):

C sample code

Method description

This method is used to intialize the MXMView based on the default settings or values as overridden by above methods.

Parameters parentView: Specifies the parent MXMView or MXMScreen used to show this view. When no parentView is specified, the new view will be placed within the system's root view (default screen).

Return value

Exceptions

6.26.10 setEventHandler

Interface Interface MXMBox{

Void setEventHandler(MXMEventHandler eventHandler);

Method Syntax

+ setEventHandler(MXMEventHandler eventHandler):

C sample code

Method description

This method places an event handler to be called for input events belonging to this box.

Parameters eventHandler: Event handler of application.

Return value

6.26.11 setSource

Interface Interface MXMVideoBox{

Void setSource(Int videoID);

Method Syntax

+ setSource(Int decoderID):

C sample code

Method description

This method selects the video source which to display.

Parameters videoID: ID of video source.

Return value

Exceptions

6.26.12 renderGeometry

Interface Interface MXMGraphicsBox{

Void renderGeometry(MeshBuffer geometry);

Method Syntax

+ renderGeometry(MeshBuffer geometry):

C sample code

This method is used to render a geometry within the view. The given geometry will be rendered to fill the complete view. To render within a portion of a view, a sub view has to be created.

Parameters geometry: The MeshBuffer to be rendered.

Return value

Exceptions

6.26.13 showAnimation

Void showAnimation(MeshBuffer geometry, VertexBuffer[] animation);

Method Syntax

+ showAnimation(MeshBuffer geometry, VertexBuffer[] animation):

C sample code

Method description

This method is used to show an animation within the view. The given animation will be rendered to fill the complete view. To render within a portion of a view, a sub view has to be created. This method creates a new thread to run the animation and do subsequent renderings.

Parameters geometry: The MeshBuffer to be rendered. animation: A VertexBuffer vector with length equals the number of frames to be rendered and used to update the VertexBuffer component of the geometry.

Return value

Exceptions

Void showBBAAnimation(MeshBuffer geometry, BBABuffer animation);

Method Syntax

+ showBBAAnimation(MeshBuffer geometry, BBABuffer animation):

C sample code

Method description

This method is used to show an animation of an object using BBA within the view. The given animation will be rendered to fill the complete view. To render within a portion of a view, a sub view has to be created. This method creates a new thread to run the animation and do subsequent renderings.

Parameters geometry: The MeshBuffer to be rendered. animation: A BBABuffer used to update the VertexBuffer component of the geometry.

Return value

Exceptions

7 MXM Application APIs

7.1.1 Open

This method is used to open a Digital Item or a file conforming to ISO/IEC 21000-9 in order to access to the data it contains.

Interface DRMManager (see Error: Reference source not found)

Method Syntax

+ open (file : File): void

Java sample code public interface DRMManager { public DCIParser open(File file) throws ContentParsingException, BadPropertyException, MalformedContentElementException; } Method description

This method is used to open either an XML file containing a Digital Item or to extract the Digital Item from a file

Parameters file Either a file containing a Digital Item conforming to ISO/IEC 21000-2 as restricted by ISO/IEC 23000-5, or an ISO/IEC 21000-9 file containing a Digital Item.

Return value

An instance of DCIParser (see Error: Reference source not found) providing an easy access to the data contained in the Digital Item.

Exceptions

ContentParsingException This exception is thrown if an error occurs while extracting the DCI from the DCF (if the file in input was an ISO/IEC 21000-9 file

BadPropertyException This exception is thrown if the properties used to configure the DRMManager class were not correctly set.

MalformedContentElementException This exception is thrown if the file in input is not a valid XML or an ISO/IEC 21000-9 files.

7.1.2 CanAccessContentElement

This method is used to determine whether a content element part of a content item that was previously opened by the DRMManager can be accessed or not.

Interface DRMManager (see Error: Reference source not found)

Method Syntax

+ canAccessContentElement (contentElementID : string, rightElement : RightElement): UseContentElementResult

Java sample code public interface DRMManager { public UseContentElementResult canAccessContentElement(String contentElementID, RightElement rightElement) throws UnsupportedFeatureException, BadPropertyException, SecurityManagerException, LicenseAuthorisationException; } Method description

This method is used to determine whether a content element part of a content item that was previously opened by the DRMManager can be accessed or not. If yes (e.g. a license is available, a decryption key is available, etc.), then the DRMManager will also configure the media framework used to access the resource (if required) by creating an appropriate media chain including one or more IPMP Tools in order to use the resource as per useType. MXM will look for a license granting the right which is needed to access the content item in the Digital Item. If no license exist, then it will search it in the SecurityManager. If a valid license is found, and the content element to acces is protected, MXM will set-up the IPMP Tools specified in the IPMP Information Descriptors of the proteted content element, authenticate them, initialise them with decryption keys and other information from the IPMP Information Descriptor so that the content element can be accessed (e.g. the media framework can proceed with rendering the content).

Parameters

182 © ISO/IEC 2009 — All rights reserved contentElementID The identifier of the content element to be accessed. This method assumes that the content item that was previously opened contains a content element with the specified contentElementID. rightElement The type of access required (e.g. play, governedCopy, etc.). See Error: Reference source not found for more information.

Return value

An object of type UseContentElementResult (see Error: Reference source not found) containing the result of whether the content element can be accessed in the way specified by useType. If yes, the returned object will contain all the information necessary to access the content element (its location, etc.), while in case the action is not allowed, the return parameter will contain the reason while the access was denied.

Exceptions

UnsupportedFeatureException This exception is thrown if an error occurs while accessing the content element and it licenses

BadPropertyException This exception is thrown if the properties used to configure the DRMManager class were not correctly set.

MalformedContentElementException This exception is thrown if the content element to access is not valid

SecurityManagerException This exception is thrown if an error occurs while retrieving licenses and/or security information from the SecurityManager

LicenseAuthorisationException This exception is thrown if an error occurred while validating a license against a query

7.1.3 Play

7.1.4 PresentDigitalItem

7.1.5 Adapt(namespaceURI:string, ued:string, resourceURI:string)

7.1.6 ProcessDigitalItem

MXM Interfaces

A.1 ContentMetadataEngine

A.2 Mpeg7

A.3 Mpeg7Parser

A.4 MXMEngineResponse

A.5 MXMUseEnvDescr

MXM Exceptions

B.1 ContentMetadataEngineException

B.2 MXMDescrException

[1] ISO/IEC 23001-3, Information technology -- MPEG systems technologies -- Part 3: XML IPMP messages [2] “XML-Encryption Syntax and Processing” - W3C Recommendation 10 December 2002. http://www.w3.org/TR/xmlenc-core/. [3] “XML-Signature Syntax and Processing” - W3C Recommendation 12 February 2002. http://www.w3.org/TR/xmldsig-core/. [4] “XML SchemaXML Schema Part 1: Structures Second Edition W3C Recommendation 28 October 2004”, http://www.w3.org/2001/XMLSchema [5] Document Object Model (DOM) Requirements. W3C Working Draft 19-April-2001, http://www.w3.org/TR/DOM-Requirements [6] W3C Candidate Recommendation, “XML Path Language (XPath) 2.0”, 3 November 2005, http://www.w3.org/TR/xpath20/ [7] IETF, Network Working Group, Request for Comments: 2459 "Internet X.509 Public Key Infrastructure Certificate and CRL Profile", http://www.ietf.org/rfc/rfc2459.txt