OpenCable' Application Platform Specification OCAP Home ...
Upcoming SlideShare
Loading in...5
×
 

OpenCable' Application Platform Specification OCAP Home ...

on

  • 1,110 views

 

Statistics

Views

Total Views
1,110
Views on SlideShare
1,109
Embed Views
1

Actions

Likes
0
Downloads
6
Comments
0

1 Embed 1

http://www.lmodules.com 1

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

OpenCable' Application Platform Specification OCAP Home ... OpenCable' Application Platform Specification OCAP Home ... Document Transcript

  • OpenCable™ Application Platform Specification OCAP Home Networking Extension OC-SP-OCAP-HNEXT1.0-I01-050519 ISSUED SPECIFICATION Notice This document is the result of a cooperative effort undertaken at the direction of Cable Television Laboratories, Inc. for the benefit of the cable industry and its customers. This document may contain references to other documents not owned or controlled by CableLabs. Use and understanding of this document may require access to such other documents. Designing, manufacturing, distributing, using, selling, or servicing products, or providing services, based on this document may require intellectual property licenses from third parties for technology referenced in the document. Neither CableLabs nor any member company is responsible to any party for any liability of any nature whatsoever resulting from or arising out of use or reliance upon this document, or any document referenced herein. This document is furnished on an "AS IS" basis and neither CableLabs nor its members provides any representation or warranty, express or implied, regarding the accuracy, completeness, or fitness for a particular purpose of this document, or any document referenced herein. If you, or the company or organization that you represent, has an existing agreement with CableLabs concerning the use of this document, or subsequently enters into another agreement with CableLabs concerning the use of this document (e.g., the OCAP Implementers Agreement), your rights and obligations with respect to this document, and the rights and obligations of the company or organization that you represent, SHALL be as set forth therein. © Copyright 2005 Cable Television Laboratories, Inc. All rights reserved.
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Document Status Document Control Number: OC-SP-OCAP-HNEXT1.0-I01-050519 Reference: OCAP Home Networking Extension Revision History: I01-050519 - Released May 19, 2005 Date: May 19, 2005 Status Code: Work in Draft Issued Closed Process Distribution Restrictions: CableLabs CL CL Public only Reviewers Vendor Key to Document Status Codes Work in Process An incomplete document, designed to guide discussion and generate feedback, that may include several alternative requirements for consideration. Draft A document in specification format considered largely complete, but lacking review by cable industry and vendors. Drafts are susceptible to substantial change during the review process. Issued A stable document, which has undergone rigorous member and vendor review and is suitable for product design and development, cross-vendor interoperability, and for certification testing. Closed A static document, reviewed, tested, validated, and closed to further engineering change requests to the specification through CableLabs. Trademarks: DOCSIS®, eDOCSIS™, PacketCable™, CableHome®, CableOffice™, OpenCable™, CableCARD™, and CableLabs® are trademarks of Cable Television Laboratories, Inc ii CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Table of Contents 1 SCOPE ..............................................................................................................................................................1 1.1 OCAP HOME NETWORKING EXTENSION PURPOSE ...........................................................................................1 1.2 OCAP HOME NETWORKING EXTENSION REQUIREMENTS ................................................................................1 1.3 OCAP HOME NETWORKING ENVIRONMENT .....................................................................................................2 1.4 OCAP HOME NETWORKING APPLICATION AREAS (INFORMATIVE) .................................................................3 1.4.1 Connected Device and Content Discovery .............................................................................................3 1.4.2 Presenting Content .................................................................................................................................3 1.4.3 Remote Rendering...................................................................................................................................3 2 REFERENCES.................................................................................................................................................5 2.1 NORMATIVE REFERENCES .................................................................................................................................5 2.2 INFORMATIVE REFERENCES...............................................................................................................................6 3 GLOSSARY .....................................................................................................................................................7 4 ACRONYMS ....................................................................................................................................................9 5 CONVENTIONS............................................................................................................................................11 5.1 SPECIFICATION LANGUAGE .............................................................................................................................11 5.2 ORGANIZATION................................................................................................................................................11 6 OCAP HOME NETWORKING...................................................................................................................13 6.1 INTRODUCTION ................................................................................................................................................13 6.2 DEVICE DISCOVERY ........................................................................................................................................14 6.2.1 Device Discovery Process ....................................................................................................................14 6.3 CONTENT DISCOVERY AND LISTING ...............................................................................................................14 6.3.1 Content Discovery and Listing Process................................................................................................14 6.4 CONTENT MANAGEMENT ................................................................................................................................14 6.4.1 Content Management Process ..............................................................................................................14 6.4.2 Content Management APIs ...................................................................................................................15 6.5 REMOTE OPERATIONS .....................................................................................................................................15 6.5.1 Remote Rendering.................................................................................................................................15 6.6 PERMISSIONS ...................................................................................................................................................16 6.6.1 Unsigned Applications..........................................................................................................................16 6.6.2 Signed Application................................................................................................................................16 6.6.3 Monitor Applications ............................................................................................................................16 6.7 OCAP HOME NETWORKING API ....................................................................................................................16 6.7.1 Additions to OCAP 1.0 Packages .........................................................................................................17 6.7.2 OCAP Home Networking Packages .....................................................................................................17 7 SECURITY.....................................................................................................................................................19 7.1 HOME NETWORK PERMISSION ........................................................................................................................19 CableLabs® iii View slide
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification 8 MINIMUM PLATFORM CAPABILITIES ............................................................................................... 21 ANNEX A ORG.OCAP.HN ............................................................................................................................ 23 org.ocap.hn ................................................................................................23 ContentManagementModule .............................................................................................................. 25 ContentServer ..................................................................................................................................... 28 Device ................................................................................................................................................ 30 HomeNetPermission .......................................................................................................................... 37 NetActionEvent .................................................................................................................................. 39 NetActionHandler .............................................................................................................................. 42 NetActionRequest .............................................................................................................................. 43 NetList................................................................................................................................................ 45 NetManager ........................................................................................................................................ 47 NetModule ......................................................................................................................................... 50 NetModuleChangeEvent .................................................................................................................... 54 NetModuleChangeListener ................................................................................................................ 56 NetModuleEvent ................................................................................................................................ 57 NetModuleEventListener ................................................................................................................... 60 NotAuthorizedException ................................................................................................................... 61 PropertyFilter ..................................................................................................................................... 62 RemoteMediaRendererModule .......................................................................................................... 64 RemoteMediaStorage ......................................................................................................................... 66 RemoteNetModule ............................................................................................................................. 67 RemoteRecordingManager ................................................................................................................ 68 RemoteRecordingResourceUsage ...................................................................................................... 69 RemoteResourceUsage ...................................................................................................................... 70 RemoteTimeShiftManager ................................................................................................................. 71 RemoteTimeShiftResourceUsage ...................................................................................................... 72 ANNEX B ORG.OCAP.HN.CONTENT........................................................................................................ 73 org.ocap.hn.content ....................................................................................73 AudioResource ................................................................................................................................... 74 ContentContainer ............................................................................................................................... 76 ContentDatabase ................................................................................................................................ 80 ContentDirectory ................................................................................................................................ 84 ContentEntry ...................................................................................................................................... 90 ContentItem ........................................................................................................................................ 93 ContentListEvent ............................................................................................................................. 104 ContentListListener .......................................................................................................................... 106 ContentResource .............................................................................................................................. 107 DatabaseException ........................................................................................................................... 112 Metadata ........................................................................................................................................... 114 MetadataNode .................................................................................................................................. 127 RecordingContentItem ..................................................................................................................... 130 VideoResource ................................................................................................................................. 134 ANNEX C ORG.OCAP.HN.CONTENT.NAVIGATION .......................................................................... 135 org.ocap.hn.content.navigation ................................................................135 ContentDatabaseFilter ...................................................................................................................... 136 ContentList ....................................................................................................................................... 137 DatabaseQuery ................................................................................................................................. 139 iv CableLabs® View slide
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 DeviceFilter ......................................................................................................................................144 ANNEX D ORG.OCAP.HN.UTIL ................................................................................................................147 org.ocap.hn.util ........................................................................................147 MultiLevelComparator .....................................................................................................................148 Searchable .........................................................................................................................................150 SearchableItem ..................................................................................................................................152 SearchableList ...................................................................................................................................154 TreeListAbstraction ..........................................................................................................................157 ANNEX E ORG.OCAP.HN.SERVICE ........................................................................................................161 org.ocap.hn.service ..................................................................................161 RemoteService .................................................................................................................................. 162 ANNEX F UPNP MAPPINGS (NORMATIVE)..........................................................................................163 CableLabs® v
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. vi CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 List of Figures FIGURE 1-1: DIGITAL HOME ENTERTAINMENT SYSTEM..................................................................................2 CableLabs® vii
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. viii CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 List of Tables TABLE 2-1 OCAP HN NORMATIVE REFERENCES ...................................................................................................5 TABLE 2-2 OCAP HN INFORMATIVE REFERENCES ...............................................................................................6 CableLabs® ix
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. x CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 1 Scope This document defines a minimal profile specification for a Home Networking software environment for digital cable receivers, with or without local storage. This platform is a modular extension to the OpenCable Application Platform 1.0 (OCAP 1.0) [2]. The OCAP 1.0 Specification and the OCAP Home Networking Extensions Specification were developed by Cable Television Laboratories, Inc. (CableLabs®) in conjunction with representatives from a number of its member cable operating companies, as well as leading software and hardware firms. The OCAP Home Networking Extensions Specification is based on the OCAP 1.0 Profile and includes that Specification in its entirety. 1.1 OCAP Home Networking Extension Purpose OCAP Home Networking Extension specification describes an application interface that includes all required Application Program Interfaces (APIs), content and data formats, and protocols up to the application level. Applications developed to the OCAP Home Networking Extension (HN) Specification will be executed on OpenCable-compliant host devices. The OCAP HN Specification allows cable operators to deploy their applications and services on all OpenCable-compliant host devices connected to their networks. The OCAP Home Networking platform SHALL be applicable to a wide variety of hardware and operating systems to allow Consumer Electronics (CE) manufacturers flexibility in implementation. A primary objective in defining OCAP Home Networking is to enable competing implementations of the OCAP Home Networking platform by CE manufacturers. 1.2 OCAP Home Networking Extension Requirements The OCAP Home Networking platform has been designed to meet specific requirements that are not commonly applied to other Home Networking environments. Some of these requirements are related to content protection obligations that cable operators face, to the fact that broadcast event descriptions might be maintained by applications, and to the fact that the platform supports DVR applications deployed by different service providers that have no a priori knowledge of each other and therefore may compete for resources. CableLabs® 1
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification 1.3 OCAP Home Networking Environment The OCAP Home Networking extensions have been designed to provide OCAP home networking applications access to digital entertainment content available on devices connected to a cable service subscriber’s home network. This includes content stored on the home networking-capable OpenCable Host device hosting the applications, as well as on other home networking-capable OpenCable Hosts and non-OpenCable Host devices connected to the home network. The OCAP Home Networking APIs assume that the Host and at least some of the other devices connected to the home network implement a set of protocols supporting the following functions: • Advertisement and discovery of connected devices • Advertisement and discovery of digital entertainment content stored on devices • Communication of information about a device’s capability to serve and/or receive digital entertainment content • Communication of information necessary to establish the transfer of digital entertainment content across the home network • Communication of playback control, file operations, and other commands needed to support the user’s enjoyment of digital entertainment content If these protocols are not implemented by two or more devices connected to the home network, features supported by the OCAP Home Networking extensions are not useable. Specification of the protocols supporting the functions described above is out of scope for the OCAP Home Networking Extension specification. Figure 1-1 illustrates a possible home network environment in which the OpenCable Host, implementing OCAP Home Network Extensions, can share digital entertainment content with other devices connected to the home network. Figure 1-1: Digital Home Entertainment System 2 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 1.4 OCAP Home Networking Application Areas (informative) The information in this section is informative to the OCAP Home Networking Extensions Specification. This section identifies the applications and services that could be made available to the viewer when using an OCAP Home Networking-compliant terminal. The descriptions of the applications are intended to demonstrate the scope of services required from OCAP 1.0. 1.4.1 Connected Device and Content Discovery A critical application enabled by this platform is the discovery of connected devices and/or their audio or video content. Discovery of content available on the home network and its presentation to the user is the first step in setting up a transfer of content from a source (server) device to a rendering device, over a home network. 1.4.2 Presenting Content Presentation of discovered multimedia content to the user offers ample opportunity for application innovation. How the content listing is organized, how it is displayed, how an item is selected, options offered for filtering and managing it, and presentation of metadata, are some of the ways an application can differentiate itself and provide value for the end user. 1.4.3 Remote Rendering One of the important applications of home networking is the ability to have digital entertainment content that is stored on one device transferred across the home network and rendered on another device. This involves selection of content on a source (server) device, selection of a rendering device, negotiation of file format and codec, and transfer of the file over the home network. CableLabs® 3
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. 4 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 2 References This section provides the normative and informative references used to create this specification. 2.1 Normative References Note: Information contained in these normative references is required for all implementations. Notwithstanding, intellectual property rights may be required to use or implement these normative references. The following documents contain provisions which, through reference in this text, constitute provisions of the present document. References are either specific (identified by date of publication, edition number, version number, etc.) or non-specific: • For a specific reference, subsequent revisions do not apply. • For a non-specific reference, the latest version applies. The following provisions apply to particular sources of documents in Table 2-1, Note column: [1] CableLabs specifications are available from: http://www.opencable.com/specifications/ Table 2-1 lists the normative references for this specification: Table 2-1 OCAP HN Normative References Index References Edition Description Note [1] OC-SP-SEC-I05- OpenCable System Security Specification 040831 Cable Television Laboratories, Inc. [2] OC-SP-OCAP1.0-I15- OCAP 1.0 OpenCable Application Platform Specification, 050415 OCAP 1.0 Profile Cable Television Laboratories, Inc. [3] OC-SP-HOST2.0- v2.0 OpenCable Host Device Core Functional CFR-I04-050415 Requirements [4] FIPS-46-3 99 Oct 25 Data Encryption Standard (DES) [5] FIPS-140-2 01 May 25 Security Requirements for Cryptographic Modules [6] FIPS-197 2001 November 26 Advanced Encryption Standard (AES) [7] ISO/IEC CD 21000- July 2001 Information Technology - Mutimedia Framework - 2:2001 Part 2: Digital Item Declaration [8] UPnP Content June 25, 2002 Content Directory:1 Service Template Version Directory Service 1.01 for UPnP Version 1.0 [9] OC-SP-OCAP-DVR- OCAP Digital Video Recorder (DVR) Extension [1] I02-050524 Cable Television Laboratories, Inc. [10] UPnP Media Server June 25, 2002 Media Server:1 Device Template Version 1.01 for UPnP Version 1.0. [11] UPnP Media June 25, 2002 Media Renderer:1 Device Template Version 1.01 Renderer for UPnP Version 1.0 [12] ETSI TS 101 812 June 2003 Digital Video Broadcasting (DVB); Multimedia v1.3.1 (2003-06) Home Platform (MHP) Specification 1.0.3. [13] CHILA CableLabs CableCARD-Host Interface License [1] Cable Television Laboratories, Inc. CableLabs® 5
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification 2.2 Informative References Table 2-2 lists the informative references for this specification: Table 2-2 OCAP HN Informative References Index References Edition Description Note [14] UPnP Forum www.upnp.org 6 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 3 Glossary The following definitions are used in this specification: Connected Device A physical device that is currently connected to a communication network and is compliant with protocols specified or referred to in this specification enabling it to be discoverable by OCAP Home Networking applications through OCAP Home Networking APIs. Content Streaming media, file-based media, applications, and data including metadata, that are discoverable by OCAP applications through OCAP Home Networking APIs. Content Resource Properties Information about content such as file name, file size, date created, and metadata. Content Usage Rules As defined in CHILA and DFAST Device Capability The ability of a given device to perform a specific function, such as server, data store, or renderer. Device Property A specific attribute of a given device. Device Type As defined in the XML Device Schema acquired via the discovery process or as defined in the CableLabs OpenCable Host specification. Discovery The process by which OCAP HN applications find, directly or by proxy, devices and content that are exposed to OCAP applications. Home Network A communication system over which Connected Devices may be discovered and content shared. Legacy Device A set-top box with embedded security. OCAP Home Network An Internet Protocol (IP)-based communication network in a cable television service subscriber's home that allows the discovery and sharing of content among devices capable of storing, receiving or transferring data within the confines of the subscriber’s local area network (LAN) itself. The OCAP Home Network does not support or allow the transfer of copy-protected content beyond the physical boundaries of the subscriber’s home LAN. The OCAP Home Network extensions build upon and references underlying protocols and other capabilities defined (or to be defined) by the OpenCable specifications and/or other CableLabs specifications. The physical network media are irrelevant to specification of the OCAP Home Networking extensions. Although this specification is largely independent of the underlying network protocols, references to those protocols may appear in portions of this specification. OCAP Home Network Application An OCAP application as defined in [2] designed to use OCAP Home Networking APIs to provide the cable subscriber value by enabling the sharing of digital entertainment content (content) stored on Connected Devices, including but not limited to providing the following services: discovering Connected Devices, discovering content stored on Connected Devices, organizing and presenting to a user information about content stored on Connected Devices, and directing content on one Connected Device to be transferred to and rendered on another Connected Device. OCAP Home Network Implementation A hardware and software environment that conforms to the OCAP Home Networking Extensions specification. CableLabs® 7
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification OCAP Home Network Platform The hardware, software, policies, and requirements definitions embodied in the OCAP HN and related specifications. Remote Rendering Content rendered on a device other than where the content is stored or transferred from. Rendering Display of coded content (audio, video, or still image). 8 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 4 Acronyms The following acronyms are used in this specification: API Application Programming Interface CCI Copy Control Information CHILA CableLabs CableCARD-Host Interface License Agreement DFAST Dynamic Feedback Arrangement Scrambling Technique DLNA Digital Living Network Alliance DVR Digital Video Recorder HN Home Network or Home Networking ISO International Organization for Standardization IETF Internet Engineering Task Force LAN Local Area Network OCAP OpenCable Application Platform PVR Personal Video Recorder RFC Request for Comments UPnP Universal Plug and Play URI Uniform Resource Identifier CableLabs® 9
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. 10 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 5 Conventions The following conventions are used in this manual: • The following font type is used to indicate code examples, names of properties, and other information that MUST be entered exactly as-is: code example font • Boldfaced text is used as emphasis. • Italicized text is used to indicate section titles when referenced within the text. 5.1 Specification Language The following words are used throughout this document to define the significance of particular requirements: MUST/SHALL This word, or the adjective REQUIRED, means that the item is an absolute requirement of this specification. MUST NOT/SHALL NOT This phrase means that the item is an absolute prohibition of this specification. SHOULD This word, or the adjective RECOMMENDED, means that valid reasons may exist in particular circumstances to ignore this item, but the full implications should be understood and the case carefully weighed before choosing a different course. SHOULD NOT This phrase means that there may exist valid reasons in particular circumstances when the listed behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label. MAY this word, or the adjective OPTIONAL, means that this item is truly optional. One vendor may choose to include the item because a particular marketplace requires it or because it enhances the product, for example; another vendor may omit the same item. Other text is descriptive or explanatory. 5.2 Organization This document uses the OpenCable Application Platform Specification, OCAP 1.0 Profile Cable Television Laboratories, Inc. [2] as its base. Where applicable, OCAP Home Networking sections reference the corresponding section within OCAP 1.0 [2]. The org.ocap.hn API package is defined in Annex A, org.ocap.hn. CableLabs® 11
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. 12 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 6 OCAP Home Networking This chapter describes the OCAP Home Networking (HN) platform. The OCAP HN APIs are defined and described in more detail in Annex A, org.ocap.hn, Annex B, org.ocap.hn.content, Annex C, org.ocap.hn.content.navigation, Annex D, org.ocap.hn.util, and Annex E, org.ocap.hn.service. 6.1 Introduction This specification fully defines a Home Networking extension to OCAP 1.0 [2]. Implementers of this specification SHALL also fully implement OCAP 1.0 [2]. OCAP 1.0 [2] and this Home Networking extension platform are related in such a way that OCAP 1.0 [2] implementations have no build-time or run-time dependencies on the Home Networking extensions, while OCAP Home Network Implementations depend on the full implementation of OCAP 1.0 [2]. An OpenCable Host that implements the OCAP Home Networking extension MAY or MAY NOT implement the OCAP DVR extension as well. OCAP Home Networking extensions rely upon support in the OCAP Home Network Implementation and in Connected Devices of a set of compatible, IP-based device and Content Discovery LAN communication protocols to expose information about the Connected Devices, their capabilities, and the digital entertainment Content they store, if any. If the hardware and software platform that implements the OCAP Home Networking APIs and Connected Devices do not implement these protocols, then information about the devices, their capabilities, and stored Content is not conveyed to the OCAP Home Network Application through the implementation and the OCAP Home Networking APIs. Connected Devices that implement device and Content Discovery LAN communication protocols compliant with protocols supported by the OCAP Home Network implementation, are referred to as protocol-compliant devices. Definition of the IP-based device and Content Discovery LAN communication protocols is outside the scope of this OCAP Home Networking Extension specification. IP-based device and Content Discovery LAN communication protocols are specified in the OpenCableHost 2.0 Home Networking Extension specification. It is assumed that Content stored on the OpenCable Host, using OCAP DVR functionality, could be exposed to protocol compliant devices sharing the IP-based communication network, and Content exposed by protocol compliant devices sharing the IP-based communication network, could be moved or copied to DVR Content storage resources on the OpenCable Host device. This specification defines a platform to enable applications to discover devices on a Home Network, gain listings of Content resources on Connected Devices, and perform certain operations on Content resources, such as Rendering, copying, and deleting. These functions are considered basic capabilities of a home networking platform, and the platform is limited in scope to support these basic functions. Advanced functions, such as device specific operations, are not supported by this platform. This chapter describes the platform in a textual format, and places normative requirements on implementations. Annexes to this specification define the platform APIs, and contains detailed API descriptions and normative statements. The OCAP Home Networking APIs assume that the OpenCable Host platform, in which they are implemented, provides an interface to an Internet Protocol (IP)-based communication network in a cable service subscriber’s premises. CableLabs recognizes that many of the supporting functions required by OCAP Home Networking APIs are supported by UPnP™ Forum specifications, such as the UPnP Media Server [10], UPnP Media Renderer [11] and UPnP Content Directory Service [8] Standardized Device Control Protocol specifications. The mapping between OCAP Home Networking APIs and UPnP services and actions is described in Annex F, UPnP Mappings (Normative). CableLabs® 13
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification 6.2 Device Discovery OCAP Home Network Applications are provided with the ability to detect the presence of Connected Devices on the OCAP Home Network, discover the properties and capabilities of those devices, and detect changes in the status of those devices. Device information acquired by the OCAP Home Network Implementation is exposed to OCAP applications, in particular to OCAP Home Network Applications, through the OCAP Home Networking APIs. 6.2.1 Device Discovery Process The process used by the OCAP Home Network Implementation for discovering devices connected on the Home Network includes the following activities: a) Maintaining a list of Connected Devices. b) Maintaining metadata for each Connected Device, such that its type, sub-devices, capabilities, properties, and supported functionalities may be exposed to applications. c) Generating application events when devices are added or removed from the list of Connected Devices. 6.3 Content Discovery and Listing OCAP Home Networking APIs provide OCAP Home Network Applications with the ability to detect the presence of Content resources accessible on devices connected on the OCAP Home Network. Content information acquired by the OCAP Home Network Implementation is exposed to OCAP applications through the OCAP Home Networking APIs. 6.3.1 Content Discovery and Listing Process The process for discovering Content on Connected Devices on the Home Network include the following activities: a) Generating, on application request, a list of Content resources available on a Connected Device. b) Generating, on application request, a list of Content resources available on all Connected Devices. c) Generating, on application request, metadata associated with Content resource. d) Generating application events when Content resources are added, removed, or modified from a list of Content resources. 6.4 Content Management OCAP Home Network Applications are provided with the ability to manage Content by copying or moving it from one device to another, or by deleting Content on one device from another remote device. A move is a copy where the original Content is deleted after the Content has been successfully moved. 6.4.1 Content Management Process The process for managing Content on Connected Devices on the Home Network includes the following activities: a) Causing, on application request, the deletion of Content resources available on a Connected Device. b) Causing, on application request, Content resources available on a Connected Device, to be copied onto another Connected Device, where resources are available on the destination Connected Device. Note: The copy and delete functions provide the capability to perform a move function, where a Content resource is first copied, then deleted from its origin. 14 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 c) Causing, on application request, that metadata be associated with a Content resource. d) Generating, on application request, logical groupings of Content resources. Note: These groupings are meant to provide similar functionality as directories and volumes on typical file systems. Content can be copied remotely using a two or three device configuration. In a two-device configuration, the OCAP application controlling an action enabled by OCAP Home Networking APIs runs on either device, and controls the Content copy from one device to another. In a three device configuration, the controlling application operates in one device, and invokes a copy command from a second device to a third device. In general, a Content copy is referred to as a PULL, when the receiving device instigates the copy, and a PUSH, when the transmitting device instigates the copy. In OCAP HN, a controlling application can cause either technique to be used by an implementation based on the source and destination arguments passed to the Content management API. Copying and deleting are operations with potential useage or useability considerations requiring special permissions, as defined in Section 6.6, Permissions. 6.4.1.1 RecordedService Copy When Content to be copied has a source that is specified using a Locator [2], which indicates a RecordedService [2], the service must be encoded into a common format. The OCAP Home Network Implementation SHALL encode the service into a single MPEG-2 transport stream representing the same information that was recorded, including all audio, video, and data elementary streams. The transport stream SHALL comply with OCAP 1.0 [2], transport protocols. It is implementation specific, whether the original recording is stored in this form so that encoding is not necessary when a network copy is instigated. 6.4.2 Content Management APIs Content management APIs are available in both synchronous and asynchronous forms. For synchronous form, see the ContentEntry methods, which copy and delete in Annex B, org.ocap.hn.content. For asynchronous form, see the ContentManagementModule in Annex A, org.ocap.hn. 6.5 Remote Operations OCAP Home Networking applications are provided with the ability to perform a number of operations effecting Content resources stored on devices connected to the OCAP Home Network, including Content management operations, and Rendering. 6.5.1 Remote Rendering Remote Rendering is the display or output of a Content resource on a Connected Device, other than the device on which the application causing theRemote Rendering is executing. 6.5.1.1 Remote Rendering Process The process undertaken by the OCAP Home Network Implementation for remotely Rendering Content on Connected Devices on the Home Network includes the following activities: a) Causing, on application request, the Remote Rendering of a Content resource on any Connected Device that is capable of Rendering Content resources of that type. b) Controlling, on application request, the Remote Rendering of a Content resource, including pause and skip functions. CableLabs® 15
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification 6.6 Permissions The Java security model includes the means to restrict access to an API and to applications that have been requested and granted specific permissions. However, security and permissions added by the recording and storage APIs cannot be conveyed across a Home Network because information such as orgId and extended file permissions might not be conveyed by the device Discovery protocol supported by the OCAP Home Network Implementation. To compensate, the HomeNetPermission class is defined as part of the OCAP Home Networking Extensions specification (see Annex A) to grant playback access to remote recordings, and remote LogicalStorageVolume instances are given default access permission of org.ocap.storage.ExtendedFileAccessPermission.readWorldAccessRight [2], [13] only. This implies: (1) HomeNetPermission over-rides orgId access for playback, as passed to the recording API; (2) recordings and LogicalStorageVolume instances that were not set with readWorldAccessRight by the owner application, will not be accessible via the Home Network by any application. Therefore, when an application creates Content directory listings from remote recordings, directories, and files, only those items set with readWorldAccessRight will appear in the listings. Implementations SHALL NOT include items in such listings that do not have readWorldAccessRight. Since HomeNetPermission over-rides orgId access for playback, OCAP Home Network Application developers are encouraged to grant HomeNetPermission only when absolutely necessary. 6.6.1 Unsigned Applications Unsigned applications SHALL NOT be granted access to a Home Network via the HN API in the org.ocap.hn name space. 6.6.2 Signed Application Signed applications MAY perform home networking actions, via the OCAP Home Networking API, in the org.ocap.hn name space. Some of the method calls in the OCAP Home Networking API require org.ocap.hn.HomeNetPermission, which MUST be provided by the applications permission request file. See Section 7.1, Home Network Permission. 6.6.3 Monitor Applications There is no MonitorAppPermission for home networking. However, HomeNetPermission provides powerful capabilities and should only be granted to the most trusted of applications, such as a monitor application. 6.7 OCAP Home Networking API The OCAP Home Network Platform extends the OCAP-J API defined in OCAP 1.0 [2]. The additional packages, classes, and interfaces are listed here. For a complete definition and description of the APIs, see Annexes A through E. An implementation of the OCAP Home Network Platform SHALL include all of the packages, classes, and interfaces defined in OCAP 1.0 [2], as well as the following packages, classes, and interfaces. 16 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 6.7.1 Additions to OCAP 1.0 Packages The OCAP Home Network Platform adds no Java interfaces and classes to packages defined in OCAP 1.0 [2]. 6.7.2 OCAP Home Networking Packages The following packages are defined by the OCAP Home Network Platform: org.ocap.hn org.ocap.hn.content org.ocap.hn.content.navigation org.ocap.hn.services org.ocap.hn.util These packages are described in Annexes A through E. CableLabs® 17
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. 18 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 7 Security The OCAP Home Network Platform may not be permitted to share all digital entertainment Content that is stored on the OpenCable Host device or other Connected Devices. Content can only be shared according to CCI bits, as defined in the OpenCable Host 2.0 specification [3]. OCAP Home Networking API methods, which cause Content to be streamed or moved to a remote device, SHALL fail if the request violates copy protection signaling, or other security requirements imposed by OpenCable security specifications. These security aspects are transparent to applications and the OCAP Home Networking API does not provide methods for application access and control of them. 7.1 Home Network Permission In addition to device authorizations, this specification defines the org.ocap.hn.HomeNetPermission class. This class can be used to grant permissions for various OCAP Home Networking API methods. See the Annexes containing APIs for method details where SecurityException can be thrown. For granting purposes, the HomeNetPermission is added to the permission request file (PRF) of an application. Referring to the PRF DTD definition given in OCAP 1.0 [2], Section 14.2.2.1.1, this specification modifies the permissionrequestfile ELEMENT and adds the ocap:homenetpermission as follows: <!ELEMENT permissionrequestfile (file?, capermission?, applifecyclecontrol?, returnchannel?, tuning?, servicesel?, userpreferences?, network?, dripfeed?, persistentfilecredential*, ocap:monitorapplication*, ocap:servicetypepermission*, ocap:homenetpermission*)> The ocap:homenetpermission ELEMENT SHALL be added after the ocap:servicetypepermission in the PRF as follows: <!ELEMENT ocap:homenetpermission EMPTY> <!ATTLIST ocap:homenetpermission ocap:type (contentmanagement | volumemanagement | remoterendering | contentlisting) ocap:value (true | false) "false" > CableLabs® 19
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. 20 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 8 Minimum Platform Capabilities The OCAP Home Network platform SHALL implement the OpenCable Host 2.0 specification [3], with Home Networking Extension to be defined. CableLabs® 21
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. 22 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Annex A org.ocap.hn This annex presents the org.ocap.hn APIs. Package org.ocap.hn Class Summary Interfaces ContentManagementModul This interface represents a NetModule that provides content management capabilities e for the purposes of network copying, moving, deleting, and renaming directories, files, or all components of a recorded service. ContentServer Class representing a NetModule which serves content, for example, a UPnP CDS - Content Directory Service. Device The Device interface represents a Homenetwork device that supports homenetwork NetModules. NetActionHandler This interface represents a handler passed to asynchronous methods NetActionRequest All asynchronous actions in the Home networking API return an ActionRequest. NetList A list comprising of homenetwork elements such as Device or NetModule. NetModule NetModule is an abstraction of functionality that is provided by a Device. NetModuleChangeListene NetModuleChange callback interface. r NetModuleEventListener NetModuleEvent callback interface. RemoteMediaRendererMod This interface provides management for Remote Media Renderer capabilities for the ule purposes of streaming content between servers and renderers on the home network. RemoteMediaStorage This interface represents a Home Networking Module that contains one or more MediaStorageVolumes RemoteNetModule RemoteRecordingManager This interface represents a Home Networking Module that provides scheduled recording service on a remote DVR device. RemoteRecordingResourc This interface represents a group of resources required to perform a recording requested eUsage by an application running on a remote device. RemoteResourceUsage This interface represents a group of resources required to perform an action requested by an application running on a remote device. RemoteTimeShiftManager This interface represents a Home Networking Module that contains one or more TimeShift buffers. RemoteTimeShiftResourc This interface represents a group of resources required to perform a time-shifting eUsage request initiated by an application running on a remote device. Classes A org.ocap.hn CableLabs® 23
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Class Summary HomeNetPermission The HomeNetPermission class represents permission to execute privileged home networking operations only signed applications MAY be granted. NetActionEvent This class represents an event generated in response to an action. NetManager The NetManager is a singleton class that registers all the Devices and NetModules within a home network. NetModuleChangeEvent Entity for NetModuleChange event. NetModuleEvent Entity for NetModule Event. PropertyFilter The filter for (key,value) pair filtering mechanism. Exceptions NotAuthorizedException Exception indicating that the application has no permission to perform certain action. 24 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn ContentManagementModule Declaration public interface ContentManagementModule extends NetModule All Superinterfaces: NetModule Description This interface represents a NetModule that provides content management capabilities for the purposes of network copying, moving, deleting, and renaming directories, files, or all components of a recorded service. All methods in this interface are asynchronous. The implementation SHALL generate an NetActionEvent when an asynchronous method completes or times out. Time outs are implementation specific. Each event SHALL contain an event type defined in NetActionEvent. Member Summary Methods NetActionRequest copy(javax.tv.locator.Locator source, javax.tv.locator.Locator dest, NetActionHandler handler) Copies a file or a recorded service from one device to another. NetActionRequest delete(javax.tv.locator.Locator target, NetActionHandler handler) Deletes a file or a recorded service on a remote device. NetActionRequest move(javax.tv.locator.Locator source, javax.tv.locator.Locator dest, NetActionHandler handler) Moves a file or a recorded service from one device to another. Methods copy(Locator, Locator, NetActionHandler) public org.ocap.hn.NetActionRequest copy(javax.tv.locator.Locator source, javax.tv.locator.Locator dest, org.ocap.hn.NetActionHandler handler) throws SecurityException Copies a file or a recorded service from one device to another. Possible action item types that can be generated by this method include; NetActionEvent.COMPLETED, NetActionEvent.ERROR_TIMED_OUT, NetActionEvent.ERROR_INVALID_PARAMETER, and NetActionEvent.ERROR_UNAUTHORIZED. Addresses following requirements: Parameters: source - Location where the item is to be copied from. dest - Location where the item is to be copied to. A org.ocap.hn CableLabs® 25
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification handler - Action response will be notified to this handler. Returns: Action request for app query and control of a pending transaction. Throws: java.lang.SecurityException - if the application does not have HomeNetPermission(“contentmanagement”) permission in its permission request file, or if the application does not have ExtendedFileAccessPermission for reading from the source or writing to the destination. java.lang.IllegalArgumentException - if the source or destination locators are not valid. delete(Locator, NetActionHandler) public org.ocap.hn.NetActionRequest delete(javax.tv.locator.Locator target, org.ocap.hn.NetActionHandler handler) throws SecurityException Deletes a file or a recorded service on a remote device. Possible action event types that can be generated by this method include; NetActionEvent.COMPLETED, NetActionEvent.ERROR_TIMED_OUT, NetActionEvent.ERROR_INVALID_PARAMETER, and NetActionEvent.ERROR_UNAUTHORIZED. Parameters: target - Location of the item is to be deleted. handler - Action response will be notified to this handler. Returns: Action request for app query and control of a pending transaction. Throws: java.lang.SecurityException - if the application does not have HomeNetPermission(“contentmanagement”) permission in its permission request file, or if the application does not have ExtendedFileAccessPermission for writing to the target. java.lang.IllegalArgumentException - if the target locator is not valid. move(Locator, Locator, NetActionHandler) public org.ocap.hn.NetActionRequest move(javax.tv.locator.Locator source, javax.tv.locator.Locator dest, org.ocap.hn.NetActionHandler handler) throws SecurityException Moves a file or a recorded service from one device to another. Possible action event types that can be generated by this method include; NetActionEvent.COMPLETED, NetActionEvent.ERROR_TIMED_OUT, NetActionEvent.ERROR_INVALID_PARAMETER, and NetActionEvent.ERROR_UNAUTHORIZED. Parameters: source - Location where the item is to be moved from. dest - Location where the item is to be moved to. handler - Action response will be notified to this handler. Returns: Action request for app query and control of a pending transaction. 26 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Throws: java.lang.SecurityException - if the application does not have HomeNetPermission(“contentmanagement”) permission in its permission request file, or if the application does not have ExtendedFileAccessPermission for reading from the source or writing to the destination. java.lang.IllegalArgumentException - if the source or destination locators are not valid. A org.ocap.hn CableLabs® 27
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn ContentServer Declaration public interface ContentServer extends NetModule All Superinterfaces: NetModule Description Class representing a NetModule which serves content, for example, a UPnP CDS - Content Directory Service. Member Summary Methods Device getDevice() java.util.Enumeration getKeys() java.lang.String getName() java.lang.String getProperty(java.lang.String key) getRootContainer() org.ocap.hn.content.Co ntentContainer void subscribe(NetModuleEventListener listener) void unsubscribe(NetModuleEventListener listener) Methods getDevice() public org.ocap.hn.Device getDevice() Description copied from interface: org.ocap.hn.NetModule Returns the device that provides this NetModule. Overrides: getDevice in interface NetModule getKeys() public java.util.Enumeration getKeys() Description copied from interface: org.ocap.hn.NetModule Returns the property keys supported by this NetModule. Overrides: getKeys in interface NetModule 28 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 getName() public java.lang.String getName() getProperty(String) public java.lang.String getProperty(java.lang.String key) Description copied from interface: org.ocap.hn.NetModule Returns the property value for specified key. Overrides: getProperty in interface NetModule getRootContainer() public org.ocap.hn.content.ContentContainer getRootContainer() subscribe(NetModuleEventListener) public void subscribe(org.ocap.hn.NetModuleEventListener listener) Description copied from interface: org.ocap.hn.NetModule Subscribes to the event of this NetModule. When NetModule status change (version change, internal states change), NetModule listeners will be notified. If listener has already been registered, then no action is performed. Overrides: subscribe in interface NetModule unsubscribe(NetModuleEventListener) public void unsubscribe(org.ocap.hn.NetModuleEventListener listener) Description copied from interface: org.ocap.hn.NetModule Unsubscribe to the event of this NetModule. If listener is not registered yet, then no action is performed. Overrides: unsubscribe in interface NetModule A org.ocap.hn CableLabs® 29
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn Device Declaration public interface Device Description The Device interface represents a Homenetwork device that supports homenetwork NetModules. A Device is a hierarchical structure with root device being the physical appliance, such as an OCAP_Terminal or an OCAP_HOST. The valid device types for an OCAP root device are OCAP_HOST and OCAP_Terminal. A root device may contain a number of sub-devices. Each sub-device may support one or more NetModule(s) whereas each NetModule only represents one sub-device. A NetModule is some functional unit in the device and examples of NetModules are ContentList, ContentManager, etc. A device may also have certain capabilities and properties associated with it. An application can retrieve these capabilities and properties by using property filters Member Summary Fields static CAP_REMOTE_STORAGE_SUPPORTED java.lang.String A constant indicating remote storage capability. static CAP_STREAMING_SUPPORTED java.lang.String A constant indicating streaming capability of the device. static CAP_TUNER_SUPPORTED java.lang.String A constant indicating if the device has a tuner. static PROP_FRIENDLY_NAME java.lang.String A constant for a friendly name of the device. static PROP_LOCATION java.lang.String A constant indicates device property: location of the device. static PROP_MANUFACTURER java.lang.String A constant indicating the manufacturer of this device. static PROP_MANUFACTURER_URL java.lang.String A constant providing URL to the manufacturer’s web site. static PROP_MIDDLEWARE_PROFILE java.lang.String A constant indicates device property: middleware profile. static PROP_MIDDLEWARE_VERSION java.lang.String A constant indicates device property: middleware version. static PROP_MODEL_DESCRIPTION java.lang.String A constant providing description of the device. static PROP_MODEL_NAME java.lang.String A constant indicates device property: model name. static PROP_MODEL_NUMBER java.lang.String A constant indicates device property: model number. static PROP_MODEL_URL java.lang.String A constant indicates device property: model URL. static PROP_PRESENTATION_URL java.lang.String A constant indicates device property: presentation URL. static PROP_SERIAL_NUMBER java.lang.String A constant indicates device property: serial number. 30 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Member Summary static PROP_UDN java.lang.String A constant indicates device property: unique device name. static PROP_UPC java.lang.String A constant indicates device property: universal product code. static TYPE_BINARY_LIGHT java.lang.String A constant indicates device type: Binary Light (on/off). static TYPE_DIMMABLE_LIGHT java.lang.String A constant indicates device type: Dimmable Light (light intensity control). static TYPE_HVAC_SYSTEM java.lang.String A constant indicates device type: Heater-Vent-Air Conditioning System. static TYPE_HVAC_ZONE_THERMOSTAT java.lang.String A constant indicates device type: Heater-Vent-Air Conditioning Thermostat. static TYPE_INTERNET_GATEWAY_DEVICE java.lang.String A constant indicates device type: Internet gateway device. static TYPE_LAN_DEVICE java.lang.String A constant indicates device type: LAN device. static TYPE_MEDIA_RENDERER java.lang.String A constant indicates device type: Media Renderer. static TYPE_MEDIA_SERVER java.lang.String A constant indicates device type: Media Server. static TYPE_OCAP_HOST java.lang.String A constant indicates device type: OCAP Host. static TYPE_OCAP_TERMINAL java.lang.String A constant indicates device type: OCAP terminal. static TYPE_PRINTER java.lang.String A constant indicates device type: Printer. static TYPE_REMOTE_UI_CLIENT_DEVICE java.lang.String A constant indicates device type: Remote UI Client Device, Allows for basic operations on a Remote UI client including: user interface connection management, optionally user interface availability management and optionally basic user interaction. static TYPE_REMOTE_UI_SERVER_DEVICE java.lang.String A constant indicates device type: Remote UI Server Device. static TYPE_SCANNER java.lang.String A constant indicates device type: Scanner. static TYPE_WAN_CONNECTION_DEVICE java.lang.String A constant indicates device type: WAN connection device. static TYPE_WAN_DEVICE java.lang.String A constant indicates device type: WAN device. static TYPE_WLAN_ACCESS_POINT_DEVICE java.lang.String A constant indicates device type: WAN access point device. Methods java.util.Enumeration getCapabilities() Returns capabilities of this device in Enumeration. java.util.Enumeration getKeys() Returns all property keys supported by this device in Enumeration. java.lang.String getName() Returns the name of this device. NetModule getNetModule(java.lang.String moduleId) Returns the NetModule by module id. NetList getNetModuleList() Returns the list of NetModules supported by this device. java.lang.String getProperty(java.lang.String key) Returns property of this device specified by a key. A org.ocap.hn CableLabs® 31
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Member Summary NetList getSubDevices() Returns a list of sub devices hosted by this device. int getType() Returns the type of this device, for example, MediaRenderer, MediaServer, etc. Fields CAP_REMOTE_STORAGE_SUPPORTED public static final java.lang.String CAP_REMOTE_STORAGE_SUPPORTED A constant indicating remote storage capability. CAP_STREAMING_SUPPORTED public static final java.lang.String CAP_STREAMING_SUPPORTED A constant indicating streaming capability of the device. CAP_TUNER_SUPPORTED public static final java.lang.String CAP_TUNER_SUPPORTED A constant indicating if the device has a tuner. PROP_FRIENDLY_NAME public static final java.lang.String PROP_FRIENDLY_NAME A constant for a friendly name of the device. PROP_LOCATION public static final java.lang.String PROP_LOCATION A constant indicates device property: location of the device. PROP_MANUFACTURER public static final java.lang.String PROP_MANUFACTURER A constant indicating the manufacturer of this device. PROP_MANUFACTURER_URL public static final java.lang.String PROP_MANUFACTURER_URL A constant providing URL to the manufacturer’s web site. PROP_MIDDLEWARE_PROFILE public static final java.lang.String PROP_MIDDLEWARE_PROFILE A constant indicates device property: middleware profile. 32 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 PROP_MIDDLEWARE_VERSION public static final java.lang.String PROP_MIDDLEWARE_VERSION A constant indicates device property: middleware version. PROP_MODEL_DESCRIPTION public static final java.lang.String PROP_MODEL_DESCRIPTION A constant providing description of the device. PROP_MODEL_NAME public static final java.lang.String PROP_MODEL_NAME A constant indicates device property: model name. PROP_MODEL_NUMBER public static final java.lang.String PROP_MODEL_NUMBER A constant indicates device property: model number. PROP_MODEL_URL public static final java.lang.String PROP_MODEL_URL A constant indicates device property: model URL. PROP_PRESENTATION_URL public static final java.lang.String PROP_PRESENTATION_URL A constant indicates device property: presentation URL. PROP_SERIAL_NUMBER public static final java.lang.String PROP_SERIAL_NUMBER A constant indicates device property: serial number. PROP_UDN public static final java.lang.String PROP_UDN A constant indicates device property: unique device name. PROP_UPC public static final java.lang.String PROP_UPC A constant indicates device property: universal product code. TYPE_BINARY_LIGHT public static final java.lang.String TYPE_BINARY_LIGHT A constant indicates device type: Binary Light (on/off). A org.ocap.hn CableLabs® 33
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification TYPE_DIMMABLE_LIGHT public static final java.lang.String TYPE_DIMMABLE_LIGHT A constant indicates device type: Dimmable Light (light intensity control). TYPE_HVAC_SYSTEM public static final java.lang.String TYPE_HVAC_SYSTEM A constant indicates device type: Heater-Vent-Air Conditioning System. TYPE_HVAC_ZONE_THERMOSTAT public static final java.lang.String TYPE_HVAC_ZONE_THERMOSTAT A constant indicates device type: Heater-Vent-Air Conditioning Thermostat. TYPE_INTERNET_GATEWAY_DEVICE public static final java.lang.String TYPE_INTERNET_GATEWAY_DEVICE A constant indicates device type: Internet gateway device. TYPE_LAN_DEVICE public static final java.lang.String TYPE_LAN_DEVICE A constant indicates device type: LAN device. TYPE_MEDIA_RENDERER public static final java.lang.String TYPE_MEDIA_RENDERER A constant indicates device type: Media Renderer. TYPE_MEDIA_SERVER public static final java.lang.String TYPE_MEDIA_SERVER A constant indicates device type: Media Server. TYPE_OCAP_HOST public static final java.lang.String TYPE_OCAP_HOST A constant indicates device type: OCAP Host. TYPE_OCAP_TERMINAL public static final java.lang.String TYPE_OCAP_TERMINAL A constant indicates device type: OCAP terminal. TYPE_PRINTER public static final java.lang.String TYPE_PRINTER A constant indicates device type: Printer. 34 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 TYPE_REMOTE_UI_CLIENT_DEVICE public static final java.lang.String TYPE_REMOTE_UI_CLIENT_DEVICE A constant indicates device type: Remote UI Client Device, Allows for basic operations on a Remote UI client including: user interface connection management, optionally user interface availability management and optionally basic user interaction. TYPE_REMOTE_UI_SERVER_DEVICE public static final java.lang.String TYPE_REMOTE_UI_SERVER_DEVICE A constant indicates device type: Remote UI Server Device. See Also: TYPE_REMOTE_UI_CLIENT_DEVICE TYPE_SCANNER public static final java.lang.String TYPE_SCANNER A constant indicates device type: Scanner. TYPE_WAN_CONNECTION_DEVICE public static final java.lang.String TYPE_WAN_CONNECTION_DEVICE A constant indicates device type: WAN connection device. TYPE_WAN_DEVICE public static final java.lang.String TYPE_WAN_DEVICE A constant indicates device type: WAN device. TYPE_WLAN_ACCESS_POINT_DEVICE public static final java.lang.String TYPE_WLAN_ACCESS_POINT_DEVICE A constant indicates device type: WAN access point device. Methods getCapabilities() public java.util.Enumeration getCapabilities() Returns capabilities of this device in Enumeration. Capabilities are defined in Device. Returns: An enumeration of String objects representing capabilities of this device. getKeys() public java.util.Enumeration getKeys() Returns all property keys supported by this device in Enumeration. Returns: An enumeration of String objects representing all property keys supported by this device A org.ocap.hn CableLabs® 35
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification getName() public java.lang.String getName() Returns the name of this device. It is the responsibility of the implementation to assure that the device name is unique within a home network. The naming rule is proprietary. For example, “LivingRoom:OCAP_HOST1”. Returns: name of this device getNetModule(String) public org.ocap.hn.NetModule getNetModule(java.lang.String moduleId) Returns the NetModule by module id. Module id is unique within a device. Parameters: moduleId - unique id of a NetModule Returns: NetModule by id, if specified NetModule is not supported by this device, then null is returned. getNetModuleList() public org.ocap.hn.NetList getNetModuleList() Returns the list of NetModules supported by this device. Returns: NetList supported by this device getProperty(String) public java.lang.String getProperty(java.lang.String key) Returns property of this device specified by a key. Minimum supported keys are defined in Device, like PROP_MANUFACTURER, PROP_MODEL_NUMBER, etc. Parameters: key - key of the property Returns: property value specified by the key getSubDevices() public org.ocap.hn.NetList getSubDevices() Returns a list of sub devices hosted by this device. Returns: list of sub-devices. getType() public int getType() Returns the type of this device, for example, MediaRenderer, MediaServer, etc. All OCAP-HN device types are defined in Device. Returns: type of this device 36 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn HomeNetPermission Declaration public final class HomeNetPermission extends java.security.BasicPermission java.lang.Object | +--java.security.Permission | +--java.security.BasicPermission | +--org.ocap.hn.HomeNetPermission All Implemented Interfaces: java.security.Guard, java.io.Serializable Description The HomeNetPermission class represents permission to execute privileged home networking operations only signed applications MAY be granted. A HomeNetPermission consists of a permission name, representing a single privileged operation. The name given in the constructor may end in “.*” to represent all permissions beginning with the given string, such as “*” to allow all HomeNetPermission operations. The following table lists all HomeNetPermission permission names. Permission Name What the Permission Allows Description contentmanagement Provides management of local or remote This permission allows the caller to copy, move, delete content content as well as allocate and delete logical volumes on any network device. remoterendering Allows content rendering on remote devices Applications with this permission can stream content from one home network device to another and cause it to be rendered on the destination device. contentlisting Provides listing of content on remote devices Applications with this permission can discover and query lists of content stored on or streamable from remote devices. Other permissions may be added as necessary. Member Summary Constructors HomeNetPermission(java.lang.String name) Constructor for the HomeNetPermission A org.ocap.hn CableLabs® 37
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Constructors HomeNetPermission(String) public HomeNetPermission(java.lang.String name) Constructor for the HomeNetPermission Parameters: name - The name of this permission (see table in class description). 38 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn NetActionEvent Declaration public class NetActionEvent extends java.util.EventObject java.lang.Object | +--java.util.EventObject | +--org.ocap.hn.NetActionEvent All Implemented Interfaces: java.io.Serializable Description This class represents an event generated in response to an action. NetActionEvent instances can only be created by the implementation. Renamed to NetActionEvent as there is already an ActionEvent in java.awt.event Member Summary Fields static int ACTION_CANCELED ACTION_CANCELED is returned by getActionStatus() when the action has been canceled. static int ACTION_COMPLETED Action status for a completed action static int ACTION_FAILED ACTION_FAILED is returned by getActionStatus() when the action has failed. static int ACTION_NEEDS_MORE_TIME ACTION_NEEDS_MORE_TIME is returned by getActionStatus() when the action needs more time to complete. static int ERROR_INVALID_PARAMETER Error code returned when an action was created with invalid parameters. static int ERROR_TIMED_OUT Error code returned when the operation timed out. static int ERROR_UNAUTHORIZED Error code returned when the requested action couldn’t be executed because of missing permissions. Constructors protected NetActionEvent(java.lang.Object source, NetActionRequest request, java.lang.Object response) Two argument constructor. Methods NetActionRequest getActionRequest() Returns the ActionRequest which identifies the action instance int getActionStatus() Returns the state of the requested action A org.ocap.hn CableLabs® 39
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Member Summary java.lang.Object getResponse() Returns the response of the Action. Fields ACTION_CANCELED public static final int ACTION_CANCELED ACTION_CANCELED is returned by getActionStatus() when the action has been canceled. See Also: getActionStatus() ACTION_COMPLETED public static final int ACTION_COMPLETED Action status for a completed action See Also: getActionStatus() ACTION_FAILED public static final int ACTION_FAILED ACTION_FAILED is returned by getActionStatus() when the action has failed. See Also: getActionStatus() ACTION_NEEDS_MORE_TIME public static final int ACTION_NEEDS_MORE_TIME ACTION_NEEDS_MORE_TIME is returned by getActionStatus() when the action needs more time to complete. This event should be sent after 15 seconds to indicate that the action is still executed but might need more time. It is up to the application to cancel the action or wait. See Also: getActionStatus() ERROR_INVALID_PARAMETER public static final int ERROR_INVALID_PARAMETER Error code returned when an action was created with invalid parameters. ERROR_TIMED_OUT public static final int ERROR_TIMED_OUT Error code returned when the operation timed out. ERROR_UNAUTHORIZED public static final int ERROR_UNAUTHORIZED Error code returned when the requested action couldn’t be executed because of missing permissions. 40 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Constructors NetActionEvent(Object, NetActionRequest, Object) protected NetActionEvent(java.lang.Object source, org.ocap.hn.NetActionRequest request, java.lang.Object response) Two argument constructor. Parameters: source - - Action that instigated the response.response - An object representing the response to the action and which is specific to the action. Methods getActionRequest() public org.ocap.hn.NetActionRequest getActionRequest() Returns the ActionRequest which identifies the action instance Returns: the ActionRequest getActionStatus() public int getActionStatus() Returns the state of the requested action Returns: See Also: ACTION_CANCELED, ACTION_COMPLETED, ACTION_FAILED, ACTION_NEEDS_MORE_TIME getResponse() public java.lang.Object getResponse() Returns the response of the Action. Object is dependent on the Action. Returns: The response to an asynchronous action. A org.ocap.hn CableLabs® 41
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn NetActionHandler Declaration public interface NetActionHandler Description This interface represents a handler passed to asynchronous methods Member Summary Methods void notify(NetActionEvent event) Notifies the application of an action event. Methods notify(NetActionEvent) public void notify(org.ocap.hn.NetActionEvent event) Notifies the application of an action event. This method is called by the implementation when a response to an action or a failure for the action is detected. 42 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn NetActionRequest Declaration public interface NetActionRequest Description All asynchronous actions in the Home networking API return an ActionRequest. The ActionRequest can be used a) to cancel any pending action or, b) to identify which Action got completed. See Also: NetActionHandler, NetActionEvent Member Summary Fields static int ACTION_COMPLETED Comment for ACTION_COMPLETED static int ACTION_FAILED Comment for ACTION_FAILED static int ACTION_PENDING Comment for ACTION_PENDING Methods boolean cancel() Cancels the Action associated with this ActionRequest. int getActionStatus() Returns the current status of the requested action float getProgress() Returns the progress of the action in percent (0.0 - 1.0). Fields ACTION_COMPLETED public static final int ACTION_COMPLETED Comment for ACTION_COMPLETED ACTION_FAILED public static final int ACTION_FAILED Comment for ACTION_FAILED ACTION_PENDING public static final int ACTION_PENDING Comment for ACTION_PENDING A org.ocap.hn CableLabs® 43
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Methods cancel() public boolean cancel() Cancels the Action associated with this ActionRequest. Returns false if the action can’t be canceled. Returns: false if action can’t be canceled. getActionStatus() public int getActionStatus() Returns the current status of the requested action Returns: the current action status getProgress() public float getProgress() Returns the progress of the action in percent (0.0 - 1.0). If the progress of an action can’t be determined, -1.0 shall be returned. Returns: the progress of the action (0.0 - 1.0) or -1.0 if the progress can’t be determined. 44 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn NetList Declaration public interface NetList Description A list comprising of homenetwork elements such as Device or NetModule. The application may retrieve such a list from NetManager, getNetModules * or getDevices. The application may refine the list by applying a PropertyFilter . Member Summary Methods boolean contains(java.lang.Object element) Indicates whether an element is included in this NetList. NetList filterElement(PropertyFilter filter) Applies a new PropertyFilter to this element list and returns a new list. java.lang.Object getElement(int index) Returns the element indexed by a number. java.util.Enumeration getElements() Returns all elements in this NetList in Enumeration. int indexOf(java.lang.Object element) Returns the index of an element in this element list. int size() Returns the size of this list. Methods contains(Object) public boolean contains(java.lang.Object element) Indicates whether an element is included in this NetList. Parameters: element - the element to check wether it is in the list Returns: true if the element is in the list; otherwise false. filterElement(PropertyFilter) public org.ocap.hn.NetList filterElement(org.ocap.hn.PropertyFilter filter) Applies a new PropertyFilter to this element list and returns a new list. Parameters: filter - new filter Returns: new element list generated by new filter A org.ocap.hn CableLabs® 45
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification See Also: PropertyFilter getElement(int) public java.lang.Object getElement(int index) Returns the element indexed by a number. Parameters: index - specified index of the element Returns: element indexed by the number getElements() public java.util.Enumeration getElements() Returns all elements in this NetList in Enumeration. In Homenetwork, NetList can be used to retrieve a list of Devices or a list of NetModules. In either case, a corresponding type of object is returned. Returns: An enumeration of Device or NetModule elements indexOf(Object) public int indexOf(java.lang.Object element) Returns the index of an element in this element list. Parameters: element - to be checked Returns: index of an element in this list. If there is no such element in this list, returns -1. size() public int size() Returns the size of this list. Returns: size of the element list 46 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn NetManager Declaration public abstract class NetManager java.lang.Object | +--org.ocap.hn.NetManager Description The NetManager is a singleton class that registers all the Devices and NetModules within a home network. It maintains an implementation dependent database of devices and NetModules. The NetManager may be used to retrieve list of NetModule and Device in the network. The application can filter the list by specifying a name or by applying filtering rules. For example, “modelNumber = h6315, location = LivingRoom”. Application can monitor availability of NetModules by registering as a listener to NetManager instance. Member Summary Constructors NetManager() Methods abstract void addNetModuleChangeListener(NetModuleEventListener listener) Adds a NetModule change listener to NetManager. abstract Device getDevice(java.lang.String name) Returns device by name. abstract NetList getDeviceList(PropertyFilter filter) Returns devices that match all properties set by a given filter. static NetManager getInstance() Returns the singleton NetManager. abstract NetModule getNetModule(java.lang.String name) Returns NetModule by name. abstract NetList getNetModuleList(PropertyFilter filter) Returns NetModules that match all properties set by a given filter. abstract void removeNetModuleChangeListener(NetModuleEventListener listener) Removes a NetModule change listener from NetManager. Constructors NetManager() public NetManager() A org.ocap.hn CableLabs® 47
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Methods addNetModuleChangeListener(NetModuleEventListener) public abstract void addNetModuleChangeListener(org.ocap.hn.NetModuleEventListener listener) Adds a NetModule change listener to NetManager. Listener will receive a NetModuleEvent when a new NetModule is registered or an old NetModule is removed from home network. If listener is already registered, no action is performed. Parameters: listener - Listener which listens to NetModule change events on home network See Also: removeNetModuleChangeListener(NetModuleEventListener) getDevice(String) public abstract org.ocap.hn.Device getDevice(java.lang.String name) Returns device by name. This name is unique device name. For example, “BallRoom:DVD_PLAYER1”. Parameters: name - Device name Returns: Device matching the specified name getDeviceList(PropertyFilter) public abstract org.ocap.hn.NetList getDeviceList(org.ocap.hn.PropertyFilter filter) Returns devices that match all properties set by a given filter. Parameters: filter - Filter to select out devices from all connected devices Returns: List of devices satisfying filter getInstance() public static org.ocap.hn.NetManager getInstance() Returns the singleton NetManager. This is the entry point for home network. Returns: Singleton instance of NetManager getNetModule(String) public abstract org.ocap.hn.NetModule getNetModule(java.lang.String name) Returns NetModule by name. This name is composed of unique device name and module ID. For example, “LivingRoom:OCAP_HOST1:ContentListing1”, where LivingRoom:OCAP_HOST1 is the device name and ContentListing1 is a unique moduleID within this device. Parameters: name - NetModule name Returns: NetModule with the specified name 48 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 getNetModuleList(PropertyFilter) public abstract org.ocap.hn.NetList getNetModuleList(org.ocap.hn.PropertyFilter filter) Returns NetModules that match all properties set by a given filter. Parameters: filter - Filter to select out NetModules from all available NetModules Returns: List of NetModules satisfying filter removeNetModuleChangeListener(NetModuleEventListener) public abstract void removeNetModuleChangeListener(org.ocap.hn.NetModuleEventListener listener) Removes a NetModule change listener from NetManager. If the listener is not registered yet, no action is performed. Parameters: listener - Listener which listens to NetModule change events on home network See Also: addNetModuleChangeListener(NetModuleEventListener) A org.ocap.hn CableLabs® 49
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn NetModule Declaration public interface NetModule All Known Subinterfaces: ContentManagementModule, ContentServer, RemoteMediaRendererModule, RemoteMediaStorage, RemoteRecordingManager, RemoteTimeShiftManager Description NetModule is an abstraction of functionality that is provided by a Device. It is a group of related actions. A NetModule is always associated with a homenetwork Device. Application may monitor a NetModule’s status by subscribing as a listener to this NetModule. Member Summary Fields static CONTENT_LIST java.lang.String A constant indicating content listing NetModule. static CONTENT_MANAGER java.lang.String A constant indicating content manager NetModule. static CONTENT_RENDERER java.lang.String A constant indicating content renderer NetModule. static CONTENT_SERVER java.lang.String A constant indicating content server NetModule. static PROP_CONTROL_URL java.lang.String A constant providing URL for NetModule control. static PROP_DESCRIPTION_URL java.lang.String A constant providing URL for NetModule description. static PROP_EventSub_URL java.lang.String A constant providing URL for NetModule event. static PROP_NETMODULE_ID java.lang.String A constant indicating NetModuleID. Methods Device getDevice() Returns the device that provides this NetModule. java.util.Enumeration getKeys() Returns the property keys supported by this NetModule. java.lang.String getNetModuleId() Returns the id of this NetModule, which is unique within the device. java.lang.String getNetModuleType() Returns the type of this NetModule. java.lang.String getProperty(java.lang.String key) Returns the property value for specified key. void subscribe(NetModuleEventListener listener) Subscribes to the event of this NetModule. 50 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Member Summary void unsubscribe(NetModuleEventListener listener) Unsubscribe to the event of this NetModule. Fields CONTENT_LIST public static final java.lang.String CONTENT_LIST A constant indicating content listing NetModule. CONTENT_MANAGER public static final java.lang.String CONTENT_MANAGER A constant indicating content manager NetModule. CONTENT_RENDERER public static final java.lang.String CONTENT_RENDERER A constant indicating content renderer NetModule. CONTENT_SERVER public static final java.lang.String CONTENT_SERVER A constant indicating content server NetModule. PROP_CONTROL_URL public static final java.lang.String PROP_CONTROL_URL A constant providing URL for NetModule control. PROP_DESCRIPTION_URL public static final java.lang.String PROP_DESCRIPTION_URL A constant providing URL for NetModule description. PROP_EventSub_URL public static final java.lang.String PROP_EventSub_URL A constant providing URL for NetModule event. PROP_NETMODULE_ID public static final java.lang.String PROP_NETMODULE_ID A constant indicating NetModuleID. A org.ocap.hn CableLabs® 51
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Methods getDevice() public org.ocap.hn.Device getDevice() Returns the device that provides this NetModule. Returns: device that offers this NetModule getKeys() public java.util.Enumeration getKeys() Returns the property keys supported by this NetModule. Returns: An enumeration of String object representing property keys for this NetModule getNetModuleId() public java.lang.String getNetModuleId() Returns the id of this NetModule, which is unique within the device. An example could be, ContentListing1. Returns: id of this NetModule getNetModuleType() public java.lang.String getNetModuleType() Returns the type of this NetModule. The allowed types are defined as constant field in NetModule, for example, CONTENT_MANAGER, CONTENT_LIST. Returns: type of this NetModule getProperty(String) public java.lang.String getProperty(java.lang.String key) Returns the property value for specified key. Parameters: key - specified property key Returns: property value for specified key subscribe(NetModuleEventListener) public void subscribe(org.ocap.hn.NetModuleEventListener listener) Subscribes to the event of this NetModule. When NetModule status change (version change, internal states change), NetModule listeners will be notified. If listener has already been registered, then no action is performed. Parameters: listener - The listener to be notified when NetModule event happens unsubscribe(NetModuleEventListener) public void unsubscribe(org.ocap.hn.NetModuleEventListener listener) 52 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Unsubscribe to the event of this NetModule. If listener is not registered yet, then no action is performed. Parameters: listener - The listener to be removed from the NetModule event listener pool A org.ocap.hn CableLabs® 53
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn NetModuleChangeEvent Declaration public class NetModuleChangeEvent extends java.util.EventObject java.lang.Object | +--java.util.EventObject | +--org.ocap.hn.NetModuleChangeEvent All Implemented Interfaces: java.io.Serializable Description Entity for NetModuleChange event. Application can register to HomeNetwork to monitoring NetModule change information. Member Summary Fields static int SERVICE_AVAILABLE static int SERVICE_BUSY static int SERVICE_LOST Constructors NetModuleChangeEvent(int type, java.lang.Object source) Methods java.lang.Object getSource() Returns module which just changed int getType() Returns module change type Fields SERVICE_AVAILABLE public static final int SERVICE_AVAILABLE SERVICE_BUSY public static final int SERVICE_BUSY SERVICE_LOST public static final int SERVICE_LOST 54 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Constructors NetModuleChangeEvent(int, Object) public NetModuleChangeEvent(int type, java.lang.Object source) Methods getSource() public java.lang.Object getSource() Returns module which just changed Overrides: getSource in class EventObject Returns: module which just changed getType() public int getType() Returns module change type Returns: module change type A org.ocap.hn CableLabs® 55
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn NetModuleChangeListener Declaration public interface NetModuleChangeListener Description NetModuleChange callback interface. When a NetModule is added/removed/changed, system will call moduleChanged() method to notify listeners. Member Summary Methods void notify(NetModuleChangeEvent event) Callback function for module change event. Methods notify(NetModuleChangeEvent) public void notify(org.ocap.hn.NetModuleChangeEvent event) Callback function for module change event. Callee will be notified when module change happens Parameters: event - module change event 56 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn NetModuleEvent Declaration public class NetModuleEvent extends java.util.EventObject java.lang.Object | +--java.util.EventObject | +--org.ocap.hn.NetModuleEvent All Implemented Interfaces: java.io.Serializable Description Entity for NetModule Event. There are two types of NetModule events: one that is generated by the NetManager when a NetModule is added or removed from the home network. Application may register as a listener to NetManager to receive such events. The other NetModuleEvent is generated by the NetModule itself when its internal state changes. Application should register as a listener with a particular NetModule for such events. In both scenarios, the NetModule that was the source of the event is returned. Member Summary Fields static int MODULE_ADDED A constant indicating new module is registered to home network. static int MODULE_BUSY A constant indicating a module is busy and cannot respond to request now. static int MODULE_REMOVED A constant indicating a module is removed from home network. static int MODULE_UPDATED A constant indicating a module is updated from home network. static int STATE_CHANGE A constant indicating a module’s internal status changed. Constructors NetModuleEvent(int type, java.lang.Object source) Constructs a NetModuleEvent by specifying type and source. Methods java.lang.Object getSource() Returns module event source, which is always a NetModule. int getType() Returns module event type, as defined in NetModuleEvent. A org.ocap.hn CableLabs® 57
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Fields MODULE_ADDED public static final int MODULE_ADDED A constant indicating new module is registered to home network. MODULE_BUSY public static final int MODULE_BUSY A constant indicating a module is busy and cannot respond to request now. MODULE_REMOVED public static final int MODULE_REMOVED A constant indicating a module is removed from home network. MODULE_UPDATED public static final int MODULE_UPDATED A constant indicating a module is updated from home network. STATE_CHANGE public static final int STATE_CHANGE A constant indicating a module’s internal status changed. Constructors NetModuleEvent(int, Object) public NetModuleEvent(int type, java.lang.Object source) Constructs a NetModuleEvent by specifying type and source. Parameters: type - NetModule change type, allowed type are defined in NetModuleEvent source - NetModule where the change happens. Methods getSource() public java.lang.Object getSource() Returns module event source, which is always a NetModule. Overrides: getSource in class EventObject Returns: module event source 58 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 getType() public int getType() Returns module event type, as defined in NetModuleEvent. Returns: module event type A org.ocap.hn CableLabs® 59
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn NetModuleEventListener Declaration public interface NetModuleEventListener Description NetModuleEvent callback interface. When a NetModule is registered or removed from NetManager, or if the internal status of a NetModule changes, then system will notify all registered listeners. Member Summary Methods void notify(NetModuleEvent event) Callback function for NetModule event. Methods notify(NetModuleEvent) public void notify(org.ocap.hn.NetModuleEvent event) Callback function for NetModule event. Callee will be notified when NetModule event happens Parameters: event - NetModule event 60 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn NotAuthorizedException Declaration public class NotAuthorizedException extends java.lang.Exception java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--org.ocap.hn.NotAuthorizedException All Implemented Interfaces: java.io.Serializable Description Exception indicating that the application has no permission to perform certain action. Member Summary Constructors NotAuthorizedException() Constructs a NotAuthorizedException object. NotAuthorizedException(java.lang.String reason) Constructs a NotAuthorizedException object with a reason. Constructors NotAuthorizedException() public NotAuthorizedException() Constructs a NotAuthorizedException object. NotAuthorizedException(String) public NotAuthorizedException(java.lang.String reason) Constructs a NotAuthorizedException object with a reason. Parameters: reason - reason for this exception A org.ocap.hn CableLabs® 61
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn PropertyFilter Declaration public class PropertyFilter java.lang.Object | +--org.ocap.hn.PropertyFilter Description The filter for (key,value) pair filtering mechanism. If a device or a NetModule has same value on all of the specified keys, it is regarded as a match. Member Summary Constructors PropertyFilter(java.util.Properties prop) Constructs a PropertyFilter object. Methods boolean accept(java.lang.Object element) Checks whether an element is accepted by this filter, the element must be either NetModule or Device. void addProperty(java.lang.String key, java.lang.String value) Adds a (key,value) pair to the filter. boolean contains(java.lang.String key) Checks whether a key is in the list. void removeKey(java.lang.String key) Remove a key from the filter, if the key is not in the property list, no action is taken. void removeKeys(java.lang.String keys) Remove keys from the filter, if a key is not in the property list, it is disregarded; while others are processed as normal. Constructors PropertyFilter(Properties) public PropertyFilter(java.util.Properties prop) Constructs a PropertyFilter object. Parameters: prop - Initial properties for this Property filter 62 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Methods accept(Object) public boolean accept(java.lang.Object element) Checks whether an element is accepted by this filter, the element must be either NetModule or Device. If a NetModule/Device’s properties share the same value as all properties from this filter, it is accepted and true is returned; otherwise, false is returned. Parameters: element - element to be checked against Returns: true if the element is accepted by the PropertyFilter addProperty(String, String) public void addProperty(java.lang.String key, java.lang.String value) Adds a (key,value) pair to the filter. If the key is already in the list, no action is taken. Parameters: key - new key which will be used for filtering value - value for the new key contains(String) public boolean contains(java.lang.String key) Checks whether a key is in the list. Parameters: key - key to be checked against Returns: true if key is in the list; otherwise false removeKey(String) public void removeKey(java.lang.String key) Remove a key from the filter, if the key is not in the property list, no action is taken. Parameters: key - key to be removed from list removeKeys(String[]) public void removeKeys(java.lang.String[] keys) Remove keys from the filter, if a key is not in the property list, it is disregarded; while others are processed as normal. Parameters: keys - keys to be removed from the list A org.ocap.hn CableLabs® 63
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn RemoteMediaRendererModule Declaration public interface RemoteMediaRendererModule extends NetModule All Superinterfaces: NetModule Description This interface provides management for Remote Media Renderer capabilities for the purposes of streaming content between servers and renderers on the home network. The interface is designed to be independent of underlying protocols, (UPnP, etc.), and underlying mechanisms such as setting up the connection and negotiating protocols are implementation specific below the API level. Member Summary Methods javax.media.Player createRemotePlayer(javax.tv.locator.Locator sourceLocator) Returns player for this remote renderer java.util.Enumeration getSupportedMimeTypes() Returns MIME types supported by the media renderer boolean isSupportedMimeType(java.lang.String mimeType) Checks to see if the mime type is supported Methods createRemotePlayer(Locator) public javax.media.Player createRemotePlayer(javax.tv.locator.Locator sourceLocator) throws NoPlayerException, SecurityException Returns player for this remote renderer Parameters: sourceLocator - Locator of content to be played Returns: player for this renderer Throws: java.lang.SecurityException - if the application does not have HomeNetPermission “remoterendering” javax.media.NoPlayerException - if the player cannot be created getSupportedMimeTypes() public java.util.Enumeration getSupportedMimeTypes() throws SecurityException 64 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Returns MIME types supported by the media renderer Returns: MIME types supported by the media renderer Throws: java.lang.SecurityException - if the application does not have HomeNetPermission “remoterendering” isSupportedMimeType(String) public boolean isSupportedMimeType(java.lang.String mimeType) throws SecurityException Checks to see if the mime type is supported Parameters: mimeType - mime type to be checked for support Returns: false if mime type is not supported Throws: java.lang.SecurityException - if the application does not have HomeNetPermission “remoterendering” A org.ocap.hn CableLabs® 65
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn RemoteMediaStorage Declaration public interface RemoteMediaStorage extends NetModule All Superinterfaces: NetModule Description This interface represents a Home Networking Module that contains one or more MediaStorageVolumes Member Summary Methods MediaStorageVolume[] getMediaStorageVolumes() Gets the MediaStorageVolumes on a remote device. Methods getMediaStorageVolumes() public MediaStorageVolume[] getMediaStorageVolumes() Gets the MediaStorageVolumes on a remote device. Returns: an array of MediaStorageVolumes that are present on the remote device; Null if there are no media storage volumes on the remote device. 66 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn RemoteNetModule Declaration public interface RemoteNetModule A org.ocap.hn CableLabs® 67
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn RemoteRecordingManager Declaration public interface RemoteRecordingManager extends NetModule All Superinterfaces: NetModule Description This interface represents a Home Networking Module that provides scheduled recording service on a remote DVR device. Member Summary Methods RecordingManager getRecordingManager() Returns an instance of a RecordingManager that may be used by applications to schedule and manage recordings on a remote DVR device. Methods getRecordingManager() public RecordingManager getRecordingManager() Returns an instance of a RecordingManager that may be used by applications to schedule and manage recordings on a remote DVR device. Returns: the Remote recording manager corresponding to the home networking device 68 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn RemoteRecordingResourceUsage Declaration public interface RemoteRecordingResourceUsage extends RemoteResourceUsage All Superinterfaces: RemoteResourceUsage Description This interface represents a group of resources required to perform a recording requested by an application running on a remote device. A org.ocap.hn CableLabs® 69
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn RemoteResourceUsage Declaration public interface RemoteResourceUsage All Known Subinterfaces: RemoteRecordingResourceUsage, RemoteTimeShiftResourceUsage Description This interface represents a group of resources required to perform an action requested by an application running on a remote device. Member Summary Methods Device getDevice() Gets the Device from which the request originated. Methods getDevice() public org.ocap.hn.Device getDevice() Gets the Device from which the request originated. Returns: the device on which the application that initiated the request was running. 70 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn RemoteTimeShiftManager Declaration public interface RemoteTimeShiftManager extends NetModule All Superinterfaces: NetModule Description This interface represents a Home Networking Module that contains one or more TimeShift buffers. Member Summary Methods getTimeShiftBuffers() TimeShiftBufferOption[ Gets the time-shift buffers on a remote device. ] Methods getTimeShiftBuffers() public TimeShiftBufferOption[] getTimeShiftBuffers() Gets the time-shift buffers on a remote device. Returns: an array of TimeShiftBufferOptions that are present on the remote device; Null if there are no time-shift buffers on the remote device. A org.ocap.hn CableLabs® 71
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn RemoteTimeShiftResourceUsage Declaration public interface RemoteTimeShiftResourceUsage extends RemoteResourceUsage All Superinterfaces: RemoteResourceUsage Description This interface represents a group of resources required to perform a time-shifting request initiated by an application running on a remote device. 72 CableLabs® A org.ocap.hn
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Annex B org.ocap.hn.content This annex presents the org.ocap.hn.content APIs. Package org.ocap.hn.content Class Summary Interfaces AudioResource Interface implemented by subclasses of ContentResource to identify that a content contains audio. ContentEntry This interface represents a basic entry in a ContentContainer. ContentListListener Listener interface for classes which are interested in changes to a ContentList. Metadata Interface which should be implemented by classes which have metadata. VideoResource Interface implemented by subclasses of ContentResource to identify that a content contains video/still image material. Classes ContentContainer This interface represents a Container. ContentDatabase This class represents the Content database containing all content entries accessible from this OCAP device. ContentDirectory This class represents a container that contains one or more content entries. ContentItem This class represents a piece of content. ContentListEvent Event which will be sent to registered ContentListListeners when ContentItems have been added/removed. ContentResource Abstract class representing a media stream/file. MetadataNode Base class for all Metadata. RecordingContentItem This class represents a content entry that is also a RecordingListEntry. Exceptions DatabaseException Exception that is thrown when a database error occurs B org.ocap.hn.content CableLabs® 73
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content AudioResource Declaration public interface AudioResource Description Interface implemented by subclasses of ContentResource to identify that a content contains audio. Member Summary Methods int getBitsPerSample() Returns the number of bits per sample or -1 if not known. java.lang.String getISO3Language() Returns the language of the audio content. java.lang.String getLanguage() Returns the language of the audio content. int getNumberOfChannels() Returns the number of audio channels, for example, 1 for mono, 2 for stereo, 6 for DTS 5.1 and 7 for DTS 6.1 int getSampleFrequency() Returns the sample frequency in Hz of this audio content or -1 if not known. Methods getBitsPerSample() public int getBitsPerSample() Returns the number of bits per sample or -1 if not known. Returns: the number of bits per sample or -1 if not known. getISO3Language() public java.lang.String getISO3Language() Returns the language of the audio content. Returns a three letter language code as defined by ISO 639- 2. http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt Returns: the language of the audio getLanguage() public java.lang.String getLanguage() Returns the language of the audio content. Returns a two letter language code as defined by ISO 639-1. http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt Returns: the language of the audio 74 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 getNumberOfChannels() public int getNumberOfChannels() Returns the number of audio channels, for example, 1 for mono, 2 for stereo, 6 for DTS 5.1 and 7 for DTS 6.1 Returns: the sample frequency of the content of -1 if not known. getSampleFrequency() public int getSampleFrequency() Returns the sample frequency in Hz of this audio content or -1 if not known. Returns: the sample frequency of the content of -1 if not known. B org.ocap.hn.content CableLabs® 75
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content ContentContainer Declaration public abstract class ContentContainer implements ContentEntry java.lang.Object | +--org.ocap.hn.content.ContentContainer All Implemented Interfaces: ContentEntry Direct Known Subclasses: ContentDirectory Description This interface represents a Container. This container can be a directory (ContentDirectory ) or a piece of content (ContentItem ) which contains several resources (ContentResource ) Member Summary Constructors ContentContainer() Methods boolean addContentEntry(ContentEntry entry) Adds a ContentEntry to this container. boolean contains(ContentEntry entry) Checks whether the given ContentEntry is in this ContentContainer. boolean deleteContainer(boolean recursive) Deletes this ContentContainer. int getComponentCount() Returns the number of ContentEntry(s) in this Container. java.util.Enumeration getEntries() Returns an Iterator over all entries in this ContentDirectory getEntries(org.ocap.hn.content.navigation.ContentDatabaseFilt org.ocap.hn.content.na er filter, boolean traverse) vigation.ContentList Returns a ContentList which contains the filtered ContentItems of this ContentDirectory. ContentEntry getEntry(int n) Returns the nth ContentEntry in this container. int getIndex(ContentEntry n) Returns the index of the specified ContentEntry or -1 if the ContentEntry does not exist in this container boolean isEmpty() Returns true if this component does not contain any entries. ContentEntry[] toArray() Returns an array of all ContentEntry in this ContentDirectory including other ContentContainers 76 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Constructors ContentContainer() public ContentContainer() Methods addContentEntry(ContentEntry) public boolean addContentEntry(org.ocap.hn.content.ContentEntry entry) Adds a ContentEntry to this container. Parameters: entry - the ContentEntry to add Returns: true if the ContentEntry got added to this container contains(ContentEntry) public boolean contains(org.ocap.hn.content.ContentEntry entry) Checks whether the given ContentEntry is in this ContentContainer. Returns true if the ContentEntry is in this container, false otherwise Parameters: entry - the ContentEntry to check for Returns: true if the ContentEntry is contained in this container deleteContainer(boolean) public boolean deleteContainer(boolean recursive) throws IOException, SecurityException Deletes this ContentContainer. If recursive is set to true all its ContentEntry (s), that is all its ContentContainer(s) and ContentItem s will be deleted as well. If recursive is set to false the same behavior is the same as ContentEntry.delete() . This is a recursive method (if the argument recursive set to true). That means the delete is done for all its elements and their elements. Note: this overrides the definition of ContentEntry The ContentContainer is no longer valid after this call. Implementations of this interface might override the behavior of this method. Note that this is a synchronous method. If an asynchronous method is required, org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) should be used. Parameters: recursive - if true, all entries and their entries will be deleted. Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. B org.ocap.hn.content CableLabs® 77
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification See Also: org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler), ContentEntry.delete() getComponentCount() public int getComponentCount() Returns the number of ContentEntry(s) in this Container. Returns: the number of ContentEntry(s). getEntries() public java.util.Enumeration getEntries() Returns an Iterator over all entries in this ContentDirectory Returns: iterator over all entries in this ContentDirectory getEntries(ContentDatabaseFilter, boolean) public org.ocap.hn.content.navigation.ContentList getEntries(org.ocap.hn.content.navigation.ContentDatabaseFilter filter, boolean traverse) Returns a ContentList which contains the filtered ContentItems of this ContentDirectory. If the boolean traverse is true, also returns the ContentItems of all its children ContentContainers. The list returned is filtered by the ContentDatabaseFilter. If the filter is null, all items are returned. Parameters: filter - a ContentDatabaseFilter to filter the ContentItems. If the filter is null, all entries are returned traverse - if true entries in the sub containers are returned as well. If set to false, only entries from the current ContentDirectory are returned Returns: a ContentList filtered by the org.ocap.hn.content.navigation.ContentDatabaseFilter getEntry(int) public org.ocap.hn.content.ContentEntry getEntry(int n) Returns the nth ContentEntry in this container. Parameters: Returns: the nth ContentEntry Throws: java.lang.ArrayIndexOutOfBoundsException - if the nth value does not exist. getIndex(ContentEntry) public int getIndex(org.ocap.hn.content.ContentEntry n) Returns the index of the specified ContentEntry or -1 if the ContentEntry does not exist in this container Parameters: n - the ContentEntry to check for 78 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Returns: the index of the ContentEntry or -1 if it doesn’t exist in this container isEmpty() public boolean isEmpty() Returns true if this component does not contain any entries. Returns: true if the container is empty toArray() public org.ocap.hn.content.ContentEntry[] toArray() Returns an array of all ContentEntry in this ContentDirectory including other ContentContainers Returns: array containing all entries of this ContentDirectory B org.ocap.hn.content CableLabs® 79
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content ContentDatabase Declaration public abstract class ContentDatabase implements org.ocap.hn.util.Searchable java.lang.Object | +--org.ocap.hn.content.ContentDatabase All Implemented Interfaces: org.ocap.hn.util.Searchable Description This class represents the Content database containing all content entries accessible from this OCAP device. Member Summary Constructors ContentDatabase() Methods abstract void deleteEntry(ContentEntry entry) Deletes the specified ContentEntry and removes it from the database. abstract getEntries(org.ocap.hn.content.navigation.ContentDatabaseFilt org.ocap.hn.content.na er filter) vigation.ContentList Returns a filtered org.ocap.hn.content.navigation.ContentList . abstract getEntries(org.ocap.hn.content.navigation.ContentDatabaseFilt org.ocap.hn.content.na er filter, java.lang.String metadataKeys) vigation.ContentList Returns a filtered org.ocap.hn.content.navigation.ContentList . abstract getEntries(org.ocap.hn.ContentServer dev) org.ocap.hn.content.na Returns a org.ocap.hn.content.navigation.ContentList from the vigation.ContentList specified org.ocap.hn.ContentServer . abstract getEntries(org.ocap.hn.ContentServer dev, org.ocap.hn.content.na org.ocap.hn.content.navigation.ContentDatabaseFilter filter, vigation.ContentList java.lang.String metadataKeys) Returns a org.ocap.hn.content.navigation.ContentList from the specified org.ocap.hn.ContentServer filtered by the org.ocap.hn.content.navigation.ContentDatabaseFilter filter. static ContentDatabase getInstance() Returns an instance of the ContentDatabase. abstract requestEntries(org.ocap.hn.ContentServer devices, org.ocap.hn.NetActionR org.ocap.hn.content.navigation.ContentDatabaseFilter filter, equest org.ocap.hn.NetActionHandler handler) Request the creation of a ContentList which contains entries from the list of ContentServers specified by the array devices and filtered by the ContentDatabaseFilter filter. 80 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Constructors ContentDatabase() public ContentDatabase() Methods deleteEntry(ContentEntry) public abstract void deleteEntry(org.ocap.hn.content.ContentEntry entry) Deletes the specified ContentEntry and removes it from the database. Parameters: entry - the entry to delete. Throws: java.lang.SecurityException See Also: ContentEntry.delete() getEntries(ContentDatabaseFilter) public abstract org.ocap.hn.content.navigation.ContentList getEntries(org.ocap.hn.content.navigation.ContentDatabaseFilter filter) throws DatabaseException Returns a filtered org.ocap.hn.content.navigation.ContentList . Only entries which were accepted by the org.ocap.hn.content.navigation.ContentDatabaseFilter are part of the returned org.ocap.hn.content.navigation.ContentList . If the org.ocap.hn.content.navigation.ContentDatabaseFilter is null the returned org.ocap.hn.content.navigation.ContentList contains all entries. This is a synchronous method. Use requestEntries(ContentServer[], ContentDatabaseFilter, NetActionHandler) for asynchronous behavior Parameters: filter - the org.ocap.hn.content.navigation.ContentDatabaseFilter or null if all entries should be returned. Returns: a filtered org.ocap.hn.content.navigation.ContentList Throws: DatabaseException getEntries(ContentDatabaseFilter, String[]) public abstract org.ocap.hn.content.navigation.ContentList getEntries(org.ocap.hn.content.navigation.ContentDatabaseFilter filter, java.lang.String[] metadataKeys) throws DatabaseException Returns a filtered org.ocap.hn.content.navigation.ContentList . Only entries which were accepted by the org.ocap.hn.content.navigation.ContentDatabaseFilter are part of the returned org.ocap.hn.content.navigation.ContentList . If the B org.ocap.hn.content CableLabs® 81
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content.navigation.ContentDatabaseFilter is null the returned org.ocap.hn.content.navigation.ContentList contains all entries. This is a synchronous method. Use requestEntries(ContentServer[], ContentDatabaseFilter, NetActionHandler) for asynchronous behavior Parameters: filter - the org.ocap.hn.content.navigation.ContentDatabaseFilter or null if all entries should be returned. metadataKeys - array specifying which Metadata keys and values should be present in the ContentItems listed in the ContentList Returns: ContentList filtered by filter. Throws: DatabaseException getEntries(ContentServer) public abstract org.ocap.hn.content.navigation.ContentList getEntries(org.ocap.hn.ContentServer dev) throws DatabaseException Returns a org.ocap.hn.content.navigation.ContentList from the specified org.ocap.hn.ContentServer . This is a synchronous method. Use requestEntries(ContentServer[], ContentDatabaseFilter, NetActionHandler) for asynchronous behavior Parameters: dev - the org.ocap.hn.ContentServer . Returns: a filtered org.ocap.hn.content.navigation.ContentList Throws: DatabaseException getEntries(ContentServer, ContentDatabaseFilter, String[]) public abstract org.ocap.hn.content.navigation.ContentList getEntries(org.ocap.hn.ContentServer dev, org.ocap.hn.content.navigation.ContentDatabaseFilter filter, java.lang.String[] metadataKeys) throws DatabaseException Returns a org.ocap.hn.content.navigation.ContentList from the specified org.ocap.hn.ContentServer filtered by the org.ocap.hn.content.navigation.ContentDatabaseFilter filter. The ContentItems returned in the ContentList will only contain the Metadata for the keys specified by the String array metadataKeys This is a synchronous method. Use requestEntries(ContentServer[], ContentDatabaseFilter, NetActionHandler) for asynchronous behavior Parameters: dev - the ContentServer for which the ContentList should be returned. filter - ContentDatabaseFilter to filter the content list. If null the ContentList will contain all entries 82 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 metadataKeys - array specifying which Metadata keys and values should be present in the ContentItems listed in the ContentList Returns: ContentList from ContentServer dev filtered by filter. Throws: DatabaseException getInstance() public static org.ocap.hn.content.ContentDatabase getInstance() Returns an instance of the ContentDatabase. The database contains all known and accessible content on the network. This is a synchronous call. Returns: instance of the ContentDatabase. requestEntries(ContentServer[], ContentDatabaseFilter, NetActionHandler) public abstract org.ocap.hn.NetActionRequest requestEntries(org.ocap.hn.ContentServer[] devices, org.ocap.hn.content.navigation.ContentDatabaseFilter filter, org.ocap.hn.NetActionHandler handler) Request the creation of a ContentList which contains entries from the list of ContentServers specified by the array devices and filtered by the ContentDatabaseFilter filter. If filter is null the list isn’t filtered. The ContentItems in ContentList which will be created will only contain the metadata keys/value pairs specified by the String array keys. If keys is null all metadata keys will be available. This is an asynchronous method. The caller gets informed via org.ocap.hn.NetActionHandler.notify(NetActionEvent) of the process. On success an NetActionEvent is created which NetActionEvent.getResponse() will return a org.ocap.hn.content.navigation.ContentList Parameters: devices - array of ContentServers for which the content should be listed filter - ContentDatabaseFilter for filtering the content or null if no filtering is required handler - NetActionHandler which gets informed once the ContentList is created. Returns: NetActionRequest to identify action. B org.ocap.hn.content CableLabs® 83
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content ContentDirectory Declaration public class ContentDirectory extends ContentContainer java.lang.Object | +--org.ocap.hn.content.ContentContainer | +--org.ocap.hn.content.ContentDirectory All Implemented Interfaces: ContentEntry Description This class represents a container that contains one or more content entries. ContentDirectory is analogous to a file storage system such as is implemented by personal computer operating systems. Member Summary Constructors ContentDirectory() Methods boolean addContentEntry(ContentEntry entry) void copyTo(ContentContainer container) Copies the ContentContainerDirectory including all its ContentEntry (s), that is all its ContentDirectory(s) and ContentItem s, to another ContentDirectory . boolean createContentContainer(java.lang.String name) Creates a new ContentDirectory as a subdirectory of this ContentContainer. boolean delete() Deletes this ContentDirectory if it is empty, but does not delete this ContentDirectory if it is not empty. boolean deleteContainer(boolean recursive) Deletes this ContentDirectory. int getComponentCount() long getContentSize() Returns the size of the ContentDirectory and all its content including all its subdirectories in bytes or -1 if not known. java.util.Date getCreationDate() Returns the creation date of this ContentDirectory or NULL if not known. java.util.Enumeration getEntries() Returns an Iterator over all entries in this ContentDirectory getEntries(org.ocap.hn.content.navigation.ContentDatabaseFilt org.ocap.hn.content.na er filter, boolean traverse) vigation.ContentList Returns a ContentList which contains the filtered ContentItems of this ContentDirectory and if the boolean traverse is true also the ContentItems of all its children ContentContainers. getExtendedFileAccessPermissions() ExtendedFileAccessPerm issions 84 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Member Summary java.lang.String getName() Returns the name of this ContentDirectory. ContentContainer getParent() boolean isEmpty() boolean isLocal() void moveTo(ContentContainer container) Moves the ContentDirectory including all its ContentEntry (s), that is all its ContentDirectory(s) and ContentItem s, to another ContentDirectory . ContentEntry[] toArray() Returns an array of all ContentEntry in this ContentDirectory including other ContentContainers Constructors ContentDirectory() public ContentDirectory() Methods addContentEntry(ContentEntry) public boolean addContentEntry(org.ocap.hn.content.ContentEntry entry) Description copied from class: org.ocap.hn.content.ContentContainer Adds a ContentEntry to this container. Overrides: addContentEntry in class ContentContainer copyTo(ContentContainer) public void copyTo(org.ocap.hn.content.ContentContainer container) Copies the ContentContainerDirectory including all its ContentEntry (s), that is all its ContentDirectory(s) and ContentItem s, to another ContentDirectory . This is a recursive method, that means the copy is done for all its elements and their elements. Note: this overrides the definition of ContentEntry The provided ContentContainer has to be another ContentDirectory otherwise an IllegalArgumentException is thrown. Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.copy(Locator, Locator, NetActionHandler) should be used. Parameters: Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. java.lang.IllegalArgumentException - if the ContentContainer specified is not an ContentDirectory. B org.ocap.hn.content CableLabs® 85
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification See Also: org.ocap.hn.ContentManagementModule.copy(Locator, Locator, NetActionHandler) createContentContainer(String) public boolean createContentContainer(java.lang.String name) throws IOException, SecurityException Creates a new ContentDirectory as a subdirectory of this ContentContainer. Parameters: name - the name of the new ContentDirectory. Returns: true if a new ContentDirectory has been created, false otherwise Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. delete() public boolean delete() throws IOException, SecurityException Deletes this ContentDirectory if it is empty, but does not delete this ContentDirectory if it is not empty. Note: this overrides the definition of ContentEntry The ContentDirectory is not valid anymore after this call. Implementations of this interface might override the behavior of this method. Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) should be used. Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. See Also: org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler), deleteContainer(boolean) deleteContainer(boolean) public boolean deleteContainer(boolean recursive) throws IOException, SecurityException Deletes this ContentDirectory. If the argument recursive is set to true then all of this ContentDirectory’s ContentEntry (s) will be deleted. That is, if recursive is set to true, this ContentDirectory and all ContentDirectories and ContentItem s that it contains will be deleted. If recursive is set to false, the behavior is the same as delete() . Note: this overrides the definition of ContentEntry The ContentDirectory is not valid anymore after this call. Implementations of this interface might override the behavior of this method. 86 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) should be used. Overrides: deleteContainer in class ContentContainer Parameters: recursive - if true all entries and their entries will be deleted. Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. See Also: org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler), delete() getComponentCount() public int getComponentCount() Description copied from class: org.ocap.hn.content.ContentContainer Returns the number of ContentEntry(s) in this Container. Overrides: getComponentCount in class ContentContainer getContentSize() public long getContentSize() Returns the size of the ContentDirectory and all its content including all its subdirectories in bytes or - 1 if not known. Note that the size may have changed during the call to this method. This is an synchronous call. Returns: the content size in bytes of all its ContentResource s. getCreationDate() public java.util.Date getCreationDate() Returns the creation date of this ContentDirectory or NULL if not known. Returns: the Date the content was created getEntries() public java.util.Enumeration getEntries() Returns an Iterator over all entries in this ContentDirectory Overrides: getEntries in class ContentContainer Returns: iterator over all entries in this ContentDirectory getEntries(ContentDatabaseFilter, boolean) public org.ocap.hn.content.navigation.ContentList getEntries(org.ocap.hn.content.navigation.ContentDatabaseFilter filter, boolean traverse) B org.ocap.hn.content CableLabs® 87
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Returns a ContentList which contains the filtered ContentItems of this ContentDirectory and if the boolean traverse is true also the ContentItems of all its children ContentContainers. The list returned is filtered by the ContentDatabaseFilter. If the filter is null all items are returned. Overrides: getEntries in class ContentContainer Parameters: filter - a ContentDatabaseFilter to filter the ContentItems. If the filter is null all entries are returned traverse - if true entries in the sub containers are returned as well. If set to false only entries from the current ContentDirectory are returned Returns: a ContentList filtered by the org.ocap.hn.content.navigation.ContentDatabaseFilter getExtendedFileAccessPermissions() public ExtendedFileAccessPermissions getExtendedFileAccessPermissions() Description copied from interface: org.ocap.hn.content.ContentEntry Returns the file permissions of a ContentEntry. getName() public java.lang.String getName() Returns the name of this ContentDirectory. Note: this overrides the definition of ContentEntry Returns: The name of ContentItem getParent() public org.ocap.hn.content.ContentContainer getParent() Description copied from interface: org.ocap.hn.content.ContentEntry Returns the ContentContainer this ContentEntry belongs to. isEmpty() public boolean isEmpty() Description copied from class: org.ocap.hn.content.ContentContainer Returns true if this component does not contain any entries. Overrides: isEmpty in class ContentContainer isLocal() public boolean isLocal() Description copied from interface: org.ocap.hn.content.ContentEntry Returns true when the content is on the local device, false if it is hosted by another device on the network 88 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 moveTo(ContentContainer) public void moveTo(org.ocap.hn.content.ContentContainer container) Moves the ContentDirectory including all its ContentEntry (s), that is all its ContentDirectory(s) and ContentItem s, to another ContentDirectory . This is a recursive method, that means the move is done for all its elements and their elements. Note: this overrides the definition of ContentEntry The provided Content Container has to be another Content Directory otherwise an Illegal Argument Exception is thrown. Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.move(Locator, Locator, Net Action Handler) should be used. Parameters: Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. java.lang.IllegalArgumentException - if the ContentContainer specified is not an ContentDirectory. See Also: org.ocap.hn.ContentManagementModule.move(Locator, Locator, NetActionHandler) toArray() public org.ocap.hn.content.ContentEntry[] toArray() Returns an array of all ContentEntry in this ContentDirectory including other ContentContainers Overrides: toArray in class ContentContainer Returns: array containing all entries of this ContentDirectory B org.ocap.hn.content CableLabs® 89
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content ContentEntry Declaration public interface ContentEntry All Known Implementing Classes: ContentItem, ContentContainer Description This interface represents a basic entry in a ContentContainer. All classes implementing the ContentContainer have a list of ContentEntry (s). However in a ContentDirectory these ContentEntry (s) will always be a ContentItem s or other ContentDirectory s. Member Summary Methods void copyTo(ContentContainer container) Copies the ContentEntry to another ContentContainer . boolean delete() Deletes this ContentEntry. long getContentSize() Returns the size of the content in bytes or -1 if not known. java.util.Date getCreationDate() Returns the creation date of the content or NULL if not known. getExtendedFileAccessPermissions() ExtendedFileAccessPerm Returns the file permissions of a ContentEntry. issions java.lang.String getName() Returns the name of this ContentEntry. ContentContainer getParent() Returns the ContentContainer this ContentEntry belongs to. boolean isLocal() Returns true when the content is on the local device, false if it is hosted by another device on the network void moveTo(ContentContainer container) Moves the ContentEntry to another ContentContainer. Methods copyTo(ContentContainer) public void copyTo(org.ocap.hn.content.ContentContainer container) throws IOException, SecurityException, IllegalArgumentException Copies the ContentEntry to another ContentContainer . Implementations of this interface might override the behavior of this method. 90 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.copy(Locator, Locator, NetActionHandler) should be used. Parameters: Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. java.lang.IllegalArgumentException - if the ContentContainer specified is not valid to hold this ContentEntry (e.g. copying a PlaylistItem to a ContentDirectory would throw an IllegalArgumentException. See Also: org.ocap.hn.ContentManagementModule.copy(Locator, Locator, NetActionHandler) delete() public boolean delete() throws IOException, SecurityException Deletes this ContentEntry. The ContentEntry is not valid anymore after this call. Implementations of this interface might override the behavior of this method. Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) should be used. Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. See Also: org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) getContentSize() public long getContentSize() Returns the size of the content in bytes or -1 if not known. Returns: the content size in bytes getCreationDate() public java.util.Date getCreationDate() Returns the creation date of the content or NULL if not known. Returns: the Date the content was created getExtendedFileAccessPermissions() public ExtendedFileAccessPermissions getExtendedFileAccessPermissions() Returns the file permissions of a ContentEntry. Returns: the extended file access permissions of the ContentEntry B org.ocap.hn.content CableLabs® 91
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification getName() public java.lang.String getName() Returns the name of this ContentEntry. Returns: The name of content entry. getParent() public org.ocap.hn.content.ContentContainer getParent() Returns the ContentContainer this ContentEntry belongs to. Returns: The parent ContentContainer isLocal() public boolean isLocal() Returns true when the content is on the local device, false if it is hosted by another device on the network Returns: true if the content is local, false otherwise moveTo(ContentContainer) public void moveTo(org.ocap.hn.content.ContentContainer container) throws IOException, SecurityException, IllegalArgumentException Moves the ContentEntry to another ContentContainer. Implementations of this interface might override the behavior of this method. Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.move(Locator, Locator, NetActionHandler) should be used. Parameters: Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. java.lang.IllegalArgumentException - if the ContentContainer specified is not valid to hold this ContentEntry (e.g. copying a PlaylistItem to a ContentDirectory would throw an IllegalArgumentException. See Also: org.ocap.hn.ContentManagementModule.move(Locator, Locator, NetActionHandler) 92 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn.content ContentItem Declaration public abstract class ContentItem implements org.ocap.hn.util.SearchableItem, Metadata, ContentEntry java.lang.Object | +--org.ocap.hn.content.ContentItem All Implemented Interfaces: java.lang.Comparable, ContentEntry, Metadata, org.ocap.hn.util.SearchableItem Direct Known Subclasses: RecordingContentItem Description This class represents a piece of content. This can be audio, video or still image content. It is not directly linked to any file. This is done via the ContentResources. A ContentItem can have multiple ContentResources. The class itself implements Metadata but the real Metadata is stored in the MetadataNode. That means a call to getMetadata(“foo”) will be translated to getMetadataRoot().getMetadata(“foo”); All ContentItems can have the following base properties (accessible via #getMetadata) (See UPnP ContentDirectory 2.4.2 Base Properties) Key XML String Return type Mandatory Metadata.ID didl-lite:id java.lang.String Yes Metadata.TITLE dc:title java.lang.String Yes Metadata.CREATOR dc:creator java.lang.String No Member Summary Fields static int AUDIO_ITEM See UPnP ContentDirectory v1.06, chapter 7.1 audioItem : item In excess to the base properties AUDIO_ITEMS can have the following properties: static int AUDIO_ITEM_BOOK See UPnP ContentDirectory v1.06, chapter 7.1.3 audioBook: audioItem In excess to the base properties and the properties listed under AUDIO_ITEM AUDIO_ITEM_BOOK can have the following properties: B org.ocap.hn.content CableLabs® 93
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Member Summary static int AUDIO_ITEM_BROADCAST See UPnP ContentDirectory v1.06, chapter 7.1.2 audioBroadcast : audioItem In excess to the base properties and the properties listed under AUDIO_ITEM AUDIO_ITEM_BROADCAST can have the following properties: static int AUDIO_ITEM_TRACK See UPnP ContentDirectory v1.06, chapter 7.1.1 musicTrack: audioItem In excess to the base properties and the properties listed under AUDIO_ITEM AUDIO_ITEM_TRACK can have the following properties: static int IMAGE_ITEM See UPnP ContentDirectory v1.06, chapter 7.3 imageItem: item In excess to the base properties IMAGE_ITEM can have the following properties: static int IMAGE_ITEM_PHOTO See UPnP ContentDirectory v1.06, chapter 7.3.1 imageItem: photo In excess to the base properties and the properties of IMAGE_ITEM IMAGE_ITEM_PHOTO can have the following properties: static int VIDEO_ITEM See UPnP ContentDirectory v1.06, chapter 7.2 videoItem: item In excess to the base properties VIDEO_ITEM can have the following properties: static int VIDEO_ITEM_BROADCAST See UPnP ContentDirectory v1.06, chapter 7.2.2 videoBroadcast: item In excess to the base properties and the properties of VIDEO_ITEM VIDEO_ITEM_BROADCAST can have the following properties: static int VIDEO_ITEM_MOVIE See UPnP ContentDirectory v1.06, chapter 7.2.1 movie: videoItem In excess to the base properties and the properties of VIDEO_ITEM VIDEO_ITEM_MOVIE can have the following properties: static int VIDEO_ITEM_MUSIC_CLIP See UPnP ContentDirectory v1.06, chapter 7.2 videoItem: item In excess to the base properties and the properties of VIDEO_ITEM VIDEO_ITEM_BROADCAST can have the following properties: Constructors ContentItem() Methods boolean contains(ContentResource entry) Checks whether the given ContentResource is part of this ContentItem. void copyTo(ContentContainer container) Copies the ContentItem including all its ContentResource s to another ContentDirectory . boolean delete() Deletes this ContentItem including all its ContentResource s. int getContentClass() Returns the content class of this content item. ContentResource getContentResource(int n) Returns the nth ContentResource of this ContentItem. 94 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Member Summary ContentResource[] getContentResources() Returns an array of ContentResources which are part of this ContentItem. long getContentSize() Returns the size of the content in bytes or -1 if not known. getLocator() javax.tv.locator.Locat Returns a javax.tv.locator.Locator for this ContentItem. or MetadataNode getMetadataRoot() Returns the Metadata root object java.lang.String getName() Returns the name of this ContentItem. MetadataNode getParentNode() This method returns null int getResourceCount() Returns the number of ContentResource s which are associated with this ContentItem. int getResourceIndex(ContentResource r) Returns the index of the specified ContentResource or -1 if the ContentResource does not exist in this ContentItem java.util.Enumeration getResources() Returns an Iterator over all ContentResource s of this ContentItem. getService() org.ocap.hn.service.Re If this ContentItem is presentable as a JavaTV Service then this method returns a moteService javax.tv.service.Service which can be used to play this ContentItem. boolean hasAudio() Returns true if this content has audio boolean hasStillImage() Returns true if the ContentItem has a still image. boolean hasVideo() Returns true if the ContentItem has video associated with it. makeLocallyPresentable(org.ocap.hn.NetActionHandler handler) org.ocap.hn.NetActionR This method makes the content locally presentable. equest void moveTo(ContentContainer container) Moves the ContentItem including all its ContentResource s to another ContentDirectory . Fields AUDIO_ITEM public static final int AUDIO_ITEM See UPnP ContentDirectory v1.06, chapter 7.1 audioItem: item In excess to the base properties AUDIO_ITEMS can have the following properties: Key XML String Return type Mandatory Metadata.GENRE upnp:genre java.lang.String [] No Metadata.DESCRIPTION dc:description java.lang.String No B org.ocap.hn.content CableLabs® 95
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Metadata.LONG_DESCRIPTION upnp:longDescription java.lang.String No Metadata.PUBLISHER dc:publisher java.lang.String [] No Metadata.LANGUAGE dc:language java.lang.String [] No Metadata.RELATION dc:relation URI as a java.lang.String No Metadata.RIGHTS dc:rights java.lang.String [] No See Also: Metadata AUDIO_ITEM_BOOK public static final int AUDIO_ITEM_BOOK See UPnP ContentDirectory v1.06, chapter 7.1.3 audioBook: audioItem In excess to the base properties and the properties listed under AUDIO_ITEM AUDIO_ITEM_BOOK can have the following properties: Key XML String Return type Mandatory Metadata.STORAGE_MEDIUM upnp:storageMedium java.lang.String No Metadata.PRODUCER upnp:producer java.lang.String No Metadata.CONTRIBUTOR dc:contributor java.lang.String [] No Metadata.CREATION_DATE dc:date java.util.Date No AUDIO_ITEM_BROADCAST public static final int AUDIO_ITEM_BROADCAST See UPnP ContentDirectory v1.06, chapter 7.1.2 audioBroadcast: audioItem In excess to the base properties and the properties listed under AUDIO_ITEM AUDIO_ITEM_BROADCAST can have the following properties: Key XML String Return type Mandatory Metadata.REGION upnp:region java.lang.String No Metadata.RADIO_CALL_SIGN upnp:radioCallSign java.lang.String No Metadata.RADIO_STATION_ID upnp:radioStationID java.lang.String No Metadata.RADIO_BAND upnp:radioBand java.lang.String No Metadata.CHANNEL_NUMBER upnp:channelNr java.lang.Integer No AUDIO_ITEM_TRACK public static final int AUDIO_ITEM_TRACK See UPnP ContentDirectory v1.06, chapter 7.1.1 musicTrack: audioItem In excess to the base properties and the properties listed under AUDIO_ITEM AUDIO_ITEM_TRACK can have the following properties: 96 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Key XML String Return type Mandatory Metadata.ARTIST upnp:artist java.lang.String [] No Metadata.ALBUM upnp:album java.lang.String [] No Metadata.TRACK_NUMBER upnp:originalTrackNumber java.lang.Integer No Metadata.PLAYLIST upnp:playlist java.lang.String [] No Metadata.STORAGE_MEDIUM upnp:storageMedium java.lang.String No Metadata.CONTRIBUTOR dc:contributor java.lang.String [] No Metadata.CREATION_DATE dc:date java.util.Date No IMAGE_ITEM public static final int IMAGE_ITEM See UPnP ContentDirectory v1.06, chapter 7.3 imageItem: item In excess to the base properties IMAGE_ITEM can have the following properties: Key XML String Return type Mandatory Metadata.DESCRIPTION dc:description java.lang.String No Metadata.LONG_DESCRIPTION upnp:longDescription java.lang.String No Metadata.PUBLISHER dc:publisher java.lang.String [] No Metadata.RATING upnp:rating java.lang.String No Metadata.STORAGE_MEDIUM upnp:storageMedium java.lang.String No Metadata.RIGHTS dc:rights java.lang.String [] No IMAGE_ITEM_PHOTO public static final int IMAGE_ITEM_PHOTO See UPnP ContentDirectory v1.06, chapter 7.3.1 imageItem: photo In excess to the base properties and the properties of IMAGE_ITEM IMAGE_ITEM_PHOTO can have the following properties: Key XML String Return type Mandatory Metadata.ALBUM upnp:album java.lang.String [] No VIDEO_ITEM public static final int VIDEO_ITEM See UPnP ContentDirectory v1.06, chapter 7.2 videoItem: item In excess to the base properties VIDEO_ITEM can have the following properties: B org.ocap.hn.content CableLabs® 97
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Key XML String Return type Mandatory Metadata.GENRE upnp:genre java.lang.String [] No Metadata.DESCRIPTION dc:description java.lang.String No Metadata.LONG_DESCRIPTION upnp:longDescription java.lang.String No Metadata.PRODUCER upnp:producer java.lang.String [] No Metadata.RATING upnp:rating java.lang.String No Metadata.ACTOR upnp:actor java.lang.String [] No Metadata.DIRECTOR upnp:director java.lang.String [] No Metadata.PUBLISHER dc:publisher java.lang.String [] No Metadata.LANGUAGE dc:language java.lang.String [] No Metadata.RELATION dc:relation URI as a java.lang.String No VIDEO_ITEM_BROADCAST public static final int VIDEO_ITEM_BROADCAST See UPnP ContentDirectory v1.06, chapter 7.2.2 videoBroadcast: item In excess to the base properties and the properties of VIDEO_ITEM VIDEO_ITEM_BROADCAST can have the following properties: Key XML String Return type Mandatory Metadata.ICON_REF upnp:icon URI as a java.lang.String No Metadata.REGION upnp:region java.lang.String No Metadata.CHANNEL_NUMBER upnp:channelNr java.lang.Integer No VIDEO_ITEM_MOVIE public static final int VIDEO_ITEM_MOVIE See UPnP ContentDirectory v1.06, chapter 7.2.1 movie: videoItem In excess to the base properties and the properties of VIDEO_ITEM VIDEO_ITEM_MOVIE can have the following properties: Key XML String Return type Mandatory Metadata.STORAGE_MEDIUM upnp:storageMedium java.lang.String No Metadata.DVD_REGION_CODE upnp:DVDRegionCode java.lang.Integer No Metadata.CHANNEL_NAME upnp:channelName java.lang.String No Metadata.SCHEDULED_START_TIME upnp:scheduledStartTime java.util.Date No Metadata.SCHEDULED_END_TIME upnp:scheduledEndTime java.util.Date No 98 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 VIDEO_ITEM_MUSIC_CLIP public static final int VIDEO_ITEM_MUSIC_CLIP See UPnP ContentDirectory v1.06, chapter 7.2 videoItem: item In excess to the base properties and the properties of VIDEO_ITEM VIDEO_ITEM_BROADCAST can have the following properties: Key XML String Return type Mandatory Metadata.ARTIST upnp:artist java.lang.String [] No Metadata.STORAGE_MEDIUM upnp:storageMedium java.lang.String No Metadata.ALBUM upnp:album java.lang.String [] No Metadata.SCHEDULED_START_TIME upnp:scheduledStartTime java.util.Date No Metadata.SCHEDULED_END_TIME upnp:scheduledEndTime java.util.Date No Metadata.DIRECTOR upnp:director java.lang.String [] No Metadata.CONTRIBUTOR dc:contributor java.lang.String [] No Metadata.CREATION_DATE dc:date java.util.Date No Constructors ContentItem() public ContentItem() Methods contains(ContentResource) public boolean contains(org.ocap.hn.content.ContentResource entry) Checks whether the given ContentResource is part of this ContentItem. Returns true if the ContentEntry is part of this ContentItem, false otherwise Parameters: entry - the ContentResource to check for Returns: true if the ContentResource is part of this ContentItem copyTo(ContentContainer) public void copyTo(org.ocap.hn.content.ContentContainer container) throws IOException, SecurityException Copies the ContentItem including all its ContentResource s to another ContentDirectory . Note: this overrides the definition of ContentEntry If the provided ContentContainer is not a ContentDirectory an IllegalArgumentException is thrown. Note that this is a synchronous method. If an asynchronous method is required B org.ocap.hn.content CableLabs® 99
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.ContentManagementModule.copy(Locator, Locator, NetActionHandler) should be used. Specified By: copyTo in interface ContentEntry Parameters: Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. See Also: org.ocap.hn.ContentManagementModule.copy(Locator, Locator, NetActionHandler) delete() public boolean delete() throws IOException, SecurityException Deletes this ContentItem including all its ContentResource s. Note: this overrides the definition of ContentEntry The ContentEntry is not valid anymore after this call. Implementations of this interface might override the behavior of this method. Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) should be used. Specified By: delete in interface ContentEntry Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. See Also: org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) getContentClass() public int getContentClass() Returns the content class of this content item. Returns: The content class of this item. See Also: AUDIO_ITEM, AUDIO_ITEM_BOOK, AUDIO_ITEM_BROADCAST, AUDIO_ITEM_TRACK, IMAGE_ITEM, VIDEO_ITEM, VIDEO_ITEM_BROADCAST, VIDEO_ITEM_MOVIE, VIDEO_ITEM_MUSIC_CLIP, IMAGE_ITEM_PHOTO getContentResource(int) public org.ocap.hn.content.ContentResource getContentResource(int n) throws ArrayIndexOutOfBoundsException Returns the nth ContentResource of this ContentItem. Parameters: n - the index of the ContentResource 100 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Returns: the nth</sup ContentResource Throws: java.lang.ArrayIndexOutOfBoundsException - if the nth value does not exist. getContentResources() public org.ocap.hn.content.ContentResource[] getContentResources() Returns an array of ContentResources which are part of this ContentItem. Returns: array of ContentResources. getContentSize() public long getContentSize() Returns the size of the content in bytes or -1 if not known. The size returned is the sum of all its ContentResource s Specified By: getContentSize in interface ContentEntry Returns: the content size in bytes of all its ContentResource s. getLocator() public javax.tv.locator.Locator getLocator() Returns a javax.tv.locator.Locator for this ContentItem. Returns: a JavaTV locator getMetadataRoot() public org.ocap.hn.content.MetadataNode getMetadataRoot() Returns the Metadata root object Returns: the Metadata root object getName() public java.lang.String getName() Returns the name of this ContentItem. Note: this overrides the definition of ContentEntry Specified By: getName in interface ContentEntry Returns: The name of ContentItem getParentNode() public org.ocap.hn.content.MetadataNode getParentNode() This method returns null Specified By: getParentNode in interface Metadata See Also: Metadata.getParentNode() B org.ocap.hn.content CableLabs® 101
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification getResourceCount() public int getResourceCount() Returns the number of ContentResource s which are associated with this ContentItem. Returns: number of ContentResources. getResourceIndex(ContentResource) public int getResourceIndex(org.ocap.hn.content.ContentResource r) Returns the index of the specified ContentResource or -1 if the ContentResource does not exist in this ContentItem Parameters: r - the ContentResource to check for Returns: the index of the ContentResourc or -1 if it doesn’t exist in this ContentItem getResources() public java.util.Enumeration getResources() Returns an Iterator over all ContentResource s of this ContentItem. Returns: Iterator over ContentResource s getService() public org.ocap.hn.service.RemoteService getService() If this ContentItem is presentable as a JavaTV Service then this method returns a javax.tv.service.Service which can be used to play this ContentItem. In this case the method getLocator() will return null. If this ContentItem is not presentable as a Service this method will return null and the method getLocator() will return a JavaTV Locator which can be converted to be used to play this piece of content using a JMF player. Returns: a JavaTV service if this content is presentable as a Service, null otherwise hasAudio() public boolean hasAudio() Returns true if this content has audio Returns: true if the content type has audio hasStillImage() public boolean hasStillImage() Returns true if the ContentItem has a still image. Returns: true if the ContentItem has a still image. hasVideo() public boolean hasVideo() Returns true if the ContentItem has video associated with it. Returns: true if the ContentItem contains video. 102 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 makeLocallyPresentable(NetActionHandler) public org.ocap.hn.NetActionRequest makeLocallyPresentable(org.ocap.hn.NetActionHandler handler) This method makes the content locally presentable. This could include copying data from one device to another. This is a asynchronous call. Returns: true when the content has been made locally presentable. moveTo(ContentContainer) public void moveTo(org.ocap.hn.content.ContentContainer container) throws IOException, SecurityException Moves the ContentItem including all its ContentResource s to another ContentDirectory . Note: this overrides the definition of ContentEntry Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.move(Locator, Locator, NetActionHandler) should be used. Specified By: moveTo in interface ContentEntry Parameters: Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. See Also: org.ocap.hn.ContentManagementModule.move(Locator, Locator, NetActionHandler) B org.ocap.hn.content CableLabs® 103
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content ContentListEvent Declaration public class ContentListEvent extends java.util.EventObject java.lang.Object | +--java.util.EventObject | +--org.ocap.hn.content.ContentListEvent All Implemented Interfaces: java.io.Serializable Description Event which will be sent to registered ContentListListeners when ContentItems have been added/removed. Member Summary Fields static int CONTENT_ADDED Event ID indicating that content got added to a ContentList static int CONTENT_REMOVED Event ID indicating that content got removed from a ContentList Constructors ContentListEvent(java.lang.Object source) Creates a new ContentListEvent with the given object as the source ContentListEvent(java.lang.Object source, ContentItem content, int evt) Creates a new ContentListEvent with the given source object, the ContentItem involved and an event ID indicating whether the content got added or removed. Methods ContentItem getContent() Returns the ContentItem involved in this event. getContentList() org.ocap.hn.content.na Returns the ContentList. vigation.ContentList Fields CONTENT_ADDED public static final int CONTENT_ADDED Event ID indicating that content got added to a ContentList 104 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 CONTENT_REMOVED public static final int CONTENT_REMOVED Event ID indicating that content got removed from a ContentList Constructors ContentListEvent(Object) public ContentListEvent(java.lang.Object source) Creates a new ContentListEvent with the given object as the source Parameters: source - The source of this event. This must be a ContentList. ContentListEvent(Object, ContentItem, int) public ContentListEvent(java.lang.Object source, org.ocap.hn.content.ContentItem content, int evt) Creates a new ContentListEvent with the given source object, the ContentItem involved and an event ID indicating whether the content got added or removed. Parameters: source - The source of this event. This must be a ContentList. content - the ContentItem involved. evt - the Event ID, either CONTENT_ADDED or CONTENT_REMOVED. Methods getContent() public org.ocap.hn.content.ContentItem getContent() Returns the ContentItem involved in this event. Returns: the ContentItem involved. getContentList() public org.ocap.hn.content.navigation.ContentList getContentList() Returns the ContentList. This is the source object of the event. Returns: the ContentList a ContentItem was added to/removed from. B org.ocap.hn.content CableLabs® 105
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content ContentListListener Declaration public interface ContentListListener extends java.util.EventListener All Superinterfaces: java.util.EventListener Description Listener interface for classes which are interested in changes to a ContentList. Member Summary Methods void contentAdded(ContentListEvent evt) Called when a ContentItem has been added to the org.ocap.hn.content.navigation.ContentList void contentRemoved(ContentListEvent evt) Called when a ContentItem has been removed from the org.ocap.hn.content.navigation.ContentList Methods contentAdded(ContentListEvent) public void contentAdded(org.ocap.hn.content.ContentListEvent evt) Called when a ContentItem has been added to the org.ocap.hn.content.navigation.ContentList Parameters: evt - the ContentListEvent contentRemoved(ContentListEvent) public void contentRemoved(org.ocap.hn.content.ContentListEvent evt) Called when a ContentItem has been removed from the org.ocap.hn.content.navigation.ContentList Parameters: evt - the ContentListEvent 106 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn.content ContentResource Declaration public abstract class ContentResource java.lang.Object | +--org.ocap.hn.content.ContentResource Description Abstract class representing a media stream/file. Subclasses of this class can implement AudioResource and/or VideoResource depending on whether the content represents audio and/or video. Member Summary Fields static UNKNOWN_MIME_TYPE java.lang.String Constant for an unknown mime type Constructors ContentResource() Methods boolean delete() Deletes the binary representation of this ContentResource and the ContentResource is removed from its ContentItem. java.lang.String getAdditionalInfo() Returns additional info on the content. int getBitrate() Returns the Bitrate this content is encoded with or -1 if not known. java.lang.String getContentFormat() Returns the content format. long getContentSize() Returns the size of the content in bytes or -1 if not known. java.util.Date getCreationDate() Returns the creation date of the content or NULL if not known. javax.media.Time getDuration() Returns the duration of this content. getExtendedFileAccessPermissions() ExtendedFileAccessPerm Returns the file permissions of a ContentResource. issions java.lang.String getImportURI() Returns a URI (see rfc 2396) via which the resource can be imported. java.lang.String getLocation() Returns a String representation of the location of this ContentResource. java.lang.String getMimeType() Returns the mime type of this ContentResource. java.lang.String getNetwork() Returns the network on which the content is available. B org.ocap.hn.content CableLabs® 107
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Member Summary ContentItem getParent() Returns the ContentItem this resource belongs to. java.lang.String getProtection() Returns a String identifying the protection system used for the resource. java.lang.String getProtocol() Returns the protocol which can be used to retrieve the content. java.lang.Object getResourceProperty(java.lang.String key) Returns properties of the resource. boolean isLocal() Returns true when the content is on the local device, false if it is hosted by another device on the network Fields UNKNOWN_MIME_TYPE public static final java.lang.String UNKNOWN_MIME_TYPE Constant for an unknown mime type Constructors ContentResource() public ContentResource() Methods delete() public boolean delete() throws IOException, SecurityException Deletes the binary representation of this ContentResource and the ContentResource is removed from its ContentItem. The ContentItem itself is not deleted. The ContentResource is not valid anymore after this call. Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) should be used. Throws: java.lang.SecurityException - if the application is denied to perform the action java.io.IOException - if action fails due to an IO error. See Also: org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) getAdditionalInfo() public java.lang.String getAdditionalInfo() Returns additional info on the content. The returned String can be a wild card “*”. 108 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 <protocol> <network> “http-get” “*” “rtsp-rtp-udp” “*” “internal” Vendor-defined, may be “*” “iec61883” GUID and PCR index of the 1394 device ICANN domain Vendor-defined, may be “*” Returns: String with additional info on the resource getBitrate() public int getBitrate() Returns the Bitrate this content is encoded with or -1 if not known. Returns: the duration of the content of -1 if not known. getContentFormat() public java.lang.String getContentFormat() Returns the content format. The returned String can be a wild card “*”. <protocol> <network> “http-get” MIME-type “rtsp-rtp-udp” Name of RTP payload type “internal” Vendor-defined, may be “*” “iec61883” Name standardized by IEC61883 ICANN domain Vendor-defined, may be “*” Returns: String describing the content format getContentSize() public long getContentSize() Returns the size of the content in bytes or -1 if not known. Returns: the content size in bytes getCreationDate() public java.util.Date getCreationDate() Returns the creation date of the content or NULL if not known. Returns: the Date the content was created B org.ocap.hn.content CableLabs® 109
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification getDuration() public javax.media.Time getDuration() Returns the duration of this content. Returns: the duration of the content getExtendedFileAccessPermissions() public ExtendedFileAccessPermissions getExtendedFileAccessPermissions() Returns the file permissions of a ContentResource. Returns: the extended file access permissions of the ContentEntry getImportURI() public java.lang.String getImportURI() Returns a URI (see rfc 2396) via which the resource can be imported. Returns: URI via which the resource can be imported getLocation() public java.lang.String getLocation() Returns a String representation of the location of this ContentResource. Returns: the location of the ContentResource. getMimeType() public java.lang.String getMimeType() Returns the mime type of this ContentResource. If the mime type is not known UNKNOWN_MIME_TYPE will be returned. Returns: the mime type See Also: getContentFormat() getNetwork() public java.lang.String getNetwork() Returns the network on which the content is available. The returned String can be a wild card “*”. <protocol> <network> “http-get” “*” “rtsp-rtp-udp” “*” “internal” IP address of the device hosting the Connection manager “iec61883” GUID of the 1394 bus Isochronous Resource Manager ICANN domain Vendor-defined, may be “*” 110 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Returns: String describing the network on which the resource is available getParent() public org.ocap.hn.content.ContentItem getParent() Returns the ContentItem this resource belongs to. Returns: the ContentItem getProtection() public java.lang.String getProtection() Returns a String identifying the protection system used for the resource. Returns: Some identification of a protection system used for the resource. getProtocol() public java.lang.String getProtocol() Returns the protocol which can be used to retrieve the content. The returned String can be a wild card “*”. Possible protocols are • “http-get” • “rtsp-rtp-udp” • “internal” • “iec61883” • Registered ICANN domain name of vendor Returns: String representation of the protocol getResourceProperty(String) public java.lang.Object getResourceProperty(java.lang.String key) Returns properties of the resource. There is a set of defined properties which can be accessed via the methods in AudioResource and VideoResource . This method allows for custom or new properties. Parameters: key - the key of the property. Returns: the value of the property isLocal() public boolean isLocal() Returns true when the content is on the local device, false if it is hosted by another device on the network Returns: true if the content is local, false otherwise B org.ocap.hn.content CableLabs® 111
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content DatabaseException Declaration public class DatabaseException extends java.lang.Exception java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--org.ocap.hn.content.DatabaseException All Implemented Interfaces: java.io.Serializable Description Exception that is thrown when a database error occurs Member Summary Fields static int FIELD_IS_EMPTY static int FIELD_IS_WRONG_FORMAT static int FIELD_NAME_DOES_NOT_EXIST static int GENERAL_ERROR static int INVALID_PARAMETER_SPECIFIED static int QUERY_IS_INVALID static int REMOTE_QUERY_IS_INVALID static int UNABLE_TO_LOCATE_SERVICE Constructors DatabaseException(java.lang.String sMessage, int iNumber) Methods int getExceptionNumber() Returns the unique exception code related to the database. Fields FIELD_IS_EMPTY public static final int FIELD_IS_EMPTY FIELD_IS_WRONG_FORMAT public static final int FIELD_IS_WRONG_FORMAT 112 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 FIELD_NAME_DOES_NOT_EXIST public static final int FIELD_NAME_DOES_NOT_EXIST GENERAL_ERROR public static final int GENERAL_ERROR INVALID_PARAMETER_SPECIFIED public static final int INVALID_PARAMETER_SPECIFIED QUERY_IS_INVALID public static final int QUERY_IS_INVALID REMOTE_QUERY_IS_INVALID public static final int REMOTE_QUERY_IS_INVALID UNABLE_TO_LOCATE_SERVICE public static final int UNABLE_TO_LOCATE_SERVICE Constructors DatabaseException(String, int) public DatabaseException(java.lang.String sMessage, int iNumber) Methods getExceptionNumber() public int getExceptionNumber() Returns the unique exception code related to the database. Returns: the integer value with an exception code B org.ocap.hn.content CableLabs® 113
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content Metadata Declaration public interface Metadata All Known Implementing Classes: ContentItem, MetadataNode Description Interface which should be implemented by classes which have metadata. Member Summary Fields static ACTOR java.lang.String Name of an actor appearing in a video item. static ACTOR_AT_ROLE java.lang.String Role of an actor in the work. static ALBUM java.lang.String This identifies a ALBUM this piece of content belongs to. static ALBUM_ART java.lang.String Reference to album art. static ARTIST java.lang.String Name of an artist. static ARTIST_AT_ROLE java.lang.String Role of an artist in the work. static ARTIST_DISCOGRAPHY java.lang.String Reference to artist discography. static AUTHOR java.lang.String Name of an author. static AUTHOR_AT_ROLE java.lang.String Role of an author in the work (e&#x2E;g&#x2E; lyrics, music). static CHANNEL_NAME java.lang.String Used for identification of channels themselves, or information associated with a piece of recorded content. static CHANNEL_NUMBER java.lang.String Used for identification of tuner channels themselves or information associated with a piece of recorded content. static COMMENTS java.lang.String General-purpose tag where a user can annotate an object with some user-specific information. static CONTRIBUTOR java.lang.String Name of a contributor. static CREATION_DATE java.lang.String This identifies the CREATION_DATE of a piece of content. static CREATOR java.lang.String This identifies the CREATOR of a piece of content. static DESCRIPTION java.lang.String A brief description of the content item. 114 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Member Summary static DIRECTOR java.lang.String Name of a director. static DVD_REGION_CODE java.lang.String DVD region code. static GENRE java.lang.String Name of the genre to which an object belongs. static ICON_REF java.lang.String Reference to an icon which can be used to represent the content. static ID java.lang.String An identifier for the object. static LANGUAGE java.lang.String Language as defined by RFC 3066, e&#x2E;g&#x2E; “en-US”. static LONG_DESCRIPTION java.lang.String A long description of the content item. static LYRICS_REF java.lang.String Reference to lyrics of a track or album. static MEDIA_ID java.lang.String Unique identifier of an audio CD (e&#x2E;g&#x2E; freedb or cddb id). static PLAYLIST java.lang.String Name of a playlist this object belongs to. static PRODUCER java.lang.String Name of a producer. static PROPRIETARY_DATA java.lang.String This identifies proprietary data. static PUBLISHER java.lang.String Name of a publisher. static RADIO_BAND java.lang.String Radio station frequency band. static RADIO_CALL_SIGN java.lang.String Radio station call sign, e&#x2E;g&#x2E; “KSJO”. static RADIO_STATION_ID java.lang.String Some identification, e&#x2E;g&#x2E; “107&#x2E;7”, broadcast frequency of the radio station. static RATING java.lang.String Rating of the object’s resource, for ’parental control’ filtering purposes, such as “R”, “PG-13”, “X”. static REGION java.lang.String Some identification of the region, associated with the ’source’ of the object, e&#x2E;g&#x2E; “US”, “Latin America”, “Seattle”. static RELATION java.lang.String Reference to related resources. static RIGHTS java.lang.String Information about rights held in and over the resource, such as Intellectual Property Rights (IPR), Copyright, and various Property Rights. static SCHEDULED_END_TIME java.lang.String End time of a scheduled program. static SCHEDULED_START_TIME java.lang.String Start time of a scheduled program. static STORAGE_MEDIUM java.lang.String Indicates the type of storage medium used for the content. static TITLE java.lang.String The identifier for the title of an item. static TRACK_NUMBER java.lang.String Original track number on a CD or other medium. B org.ocap.hn.content CableLabs® 115
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Member Summary Methods java.util.Enumeration getIdentifierNames() Returns an Enumeration of all identifier names. java.util.Enumeration getMetadata() Returns an Enumeration of all Metadata objects. java.lang.Object getMetadata(java.lang.String which) Returns the metadata for an Identifier e.g., the Title, Genre, Artist. int getNumberOfIdentifiers() Returns the number of Identifiers MetadataNode getParentNode() Returns the parent MetadataNode Fields ACTOR public static final java.lang.String ACTOR Name of an actor appearing in a video item. The value of this field is “upnp:actor”. getMetadata() will return an array of Strings. See Also: getMetadata(String) ACTOR_AT_ROLE public static final java.lang.String ACTOR_AT_ROLE Role of an actor in the work. The value of this field is “upnp:actor@role” getMetadata returns a String. See Also: getMetadata(String) ALBUM public static final java.lang.String ALBUM This identifies a ALBUM this piece of content belongs to. For example, in MP3 files this maps to the ’Album’ ID3 tag, In case of a recording/live broadcast this could be the series to which it belongs (e.g. Buffy). The value of this field is “upnp:album” Queries for ALBUM should always return a String. getMetadata() will return an array of Strings. See Also: getMetadata(String) 116 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 ALBUM_ART public static final java.lang.String ALBUM_ART Reference to album art. Can be more than one. The value of this field is “upnp:albumArtURI”. Values must be properly escaped URIs as described in [RFC 2396 (http://www.ietf.org/rfc/ rfc2396.txt)]. getMetadata() will return an array of Strings. See Also: getMetadata(String) ARTIST public static final java.lang.String ARTIST Name of an artist. The value of this field is “upnp:artist”. getMetadata(ARTIST) will return an array of Strings. See Also: getMetadata(String) ARTIST_AT_ROLE public static final java.lang.String ARTIST_AT_ROLE Role of an artist in the work. The value of this field is “upnp:artist@role” getMetadata returns a String. See Also: getMetadata(String) ARTIST_DISCOGRAPHY public static final java.lang.String ARTIST_DISCOGRAPHY Reference to artist discography. The value of this field is “upnp:artistDiscographyURI. Values must be properly escaped URIs as described in [RFC 2396 (http://www.ietf.org/rfc/ rfc2396.txt)]. getMetadata() will return a String. See Also: getMetadata(String) AUTHOR public static final java.lang.String AUTHOR Name of an author. The value of this field is “upnp:author”. getMetadata() will return an array of Strings. B org.ocap.hn.content CableLabs® 117
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification See Also: getMetadata(String) AUTHOR_AT_ROLE public static final java.lang.String AUTHOR_AT_ROLE Role of an author in the work (e&#x2E;g&#x2E; lyrics, music). The value of this field is “upnp:author@role” getMetadata returns a String. See Also: getMetadata(String) CHANNEL_NAME public static final java.lang.String CHANNEL_NAME Used for identification of channels themselves, or information associated with a piece of recorded content. The value of this field is “upnp:channelName” See Also: getMetadata(String) CHANNEL_NUMBER public static final java.lang.String CHANNEL_NUMBER Used for identification of tuner channels themselves or information associated with a piece of recorded content. The value of this field is “upnp:channelNr” getMetadata() returns an Integer. See Also: getMetadata(String) COMMENTS public static final java.lang.String COMMENTS General-purpose tag where a user can annotate an object with some user-specific information. The value of this field is “upnp:userAnnotation” getMetadata() will return an array of Strings. See Also: getMetadata(String) CONTRIBUTOR public static final java.lang.String CONTRIBUTOR Name of a contributor. It is recommended that CONTRIBUTOR includes the name of the primary content creator (see Dublin Core ’creator’ property) The value of this field is “dc:contributor”. getMetadata() will return an array of Strings. 118 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 See Also: getMetadata(String) CREATION_DATE public static final java.lang.String CREATION_DATE This identifies the CREATION_DATE of a piece of content. In the case of e.g MP3’s this maps to the ’Year’ ID3 tag, In case of a recording/live broadcast this is when the content was created. For Images this is the date the photo was made. Queries for CREATION_DATE should always return a java.util.Date. Only the year of the Date might actually be valid (e.g. for MP3s). The value of this field is “dc:date” See Also: getMetadata(String) CREATOR public static final java.lang.String CREATOR This identifies the CREATOR of a piece of content. In the case of e.g MP3’s this maps to the ’Artist’ ID3 tag, In case of a recording/live broadcast this is the Broadcaster e.g. BBC1. Queries for CREATOR should always return a String. The value of this key is “dc:creator”. See Also: getMetadata(String) DESCRIPTION public static final java.lang.String DESCRIPTION A brief description of the content item. The value of this field is “dc:description”. See Also: getMetadata(String) DIRECTOR public static final java.lang.String DIRECTOR Name of a director. The value of this field is “upnp:director”. getMetadata() will return an array of Strings. See Also: getMetadata(String) DVD_REGION_CODE public static final java.lang.String DVD_REGION_CODE DVD region code. The value of this field is “upnp:DVDRegionCode” getMetadata() returns an Integer. See Also: getMetadata(String) B org.ocap.hn.content CableLabs® 119
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification GENRE public static final java.lang.String GENRE Name of the genre to which an object belongs. Can be more than one. The value of this field is “upnp:genre”. getMetadata() will return an array of Strings. See Also: getMetadata(String) ICON_REF public static final java.lang.String ICON_REF Reference to an icon which can be used to represent the content. The value of this field is “upnp:icon”. Values must be properly escaped URIs as described in [RFC 2396 (http://www.ietf.org/rfc/ rfc2396.txt)]. See Also: getMetadata(String) ID public static final java.lang.String ID An identifier for the object. The value of each object id property must be unique with respect to the server hosting this content. The value is didl-lite:(object)@“id” See Also: getMetadata(String) LANGUAGE public static final java.lang.String LANGUAGE Language as defined by RFC 3066, e&#x2E;g&#x2E; “en-US”. The value of this field is “dc:language” getMetadata() will return an array of Strings. See Also: getMetadata(String) LONG_DESCRIPTION public static final java.lang.String LONG_DESCRIPTION A long description of the content item. The value of this field is “upnp:longDescription”. See Also: getMetadata(String) LYRICS_REF public static final java.lang.String LYRICS_REF 120 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Reference to lyrics of a track or album. The value of this field is “upnp:lyricsURI”. Values must be properly escaped URIs as described in [RFC 2396 (http://www.ietf.org/rfc/ rfc2396.txt)]. getMetadata() will return an array of Strings. See Also: getMetadata(String) MEDIA_ID public static final java.lang.String MEDIA_ID Unique identifier of an audio CD (e&#x2E;g&#x2E; freedb or cddb id). The value of this field is “upnp:toc” See Also: getMetadata(String) PLAYLIST public static final java.lang.String PLAYLIST Name of a playlist this object belongs to. Can be more than one. The value of this field is “upnp:playlist”. getMetadata() will return an array of Strings. See Also: getMetadata(String) PRODUCER public static final java.lang.String PRODUCER Name of a producer. The value of this field is “upnp:producer”. getMetadata() will return an array of Strings. See Also: getMetadata(String) PROPRIETARY_DATA public static final java.lang.String PROPRIETARY_DATA This identifies proprietary data. The Object returned can be of any type. The value of this field is an OCAP defined string “ocap:proprietaryData”. If the proprietary data is an array of bytes the data should be transported as a base 64 String See Also: getMetadata(String) PUBLISHER public static final java.lang.String PUBLISHER Name of a publisher. The value of this field is “dc:publisher”. B org.ocap.hn.content CableLabs® 121
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification getMetadata() will return an array of Strings. See Also: getMetadata(String) RADIO_BAND public static final java.lang.String RADIO_BAND Radio station frequency band. Recommended values are “AM”, “FM”, “Shortwave”, “Internet”, “Satellite”. The value of this field is “upnp:radioBand” See Also: getMetadata(String) RADIO_CALL_SIGN public static final java.lang.String RADIO_CALL_SIGN Radio station call sign, e&#x2E;g&#x2E; “KSJO”. The value of this field is “upnp:radioCallSign” See Also: getMetadata(String) RADIO_STATION_ID public static final java.lang.String RADIO_STATION_ID Some identification, e&#x2E;g&#x2E; “107&#x2E;7”, broadcast frequency of the radio station. The value of this field is “upnp:radioStationID” See Also: getMetadata(String) RATING public static final java.lang.String RATING Rating of the object’s resource, for ’parental control’ filtering purposes, such as “R”, “PG-13”, “X”. The value of this field is “upnp:rating” See Also: getMetadata(String) REGION public static final java.lang.String REGION Some identification of the region, associated with the ’source’ of the object, e&#x2E;g&#x2E; “US”, “Latin America”, “Seattle”. The value of this field is “upnp:region” See Also: getMetadata(String) RELATION public static final java.lang.String RELATION Reference to related resources. The value of this field is “dc:relation. 122 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Values must be properly escaped URIs as described in [RFC 2396 (http://www.ietf.org/rfc/ rfc2396.txt)]. getMetadata() will return an array of Strings. See Also: getMetadata(String) RIGHTS public static final java.lang.String RIGHTS Information about rights held in and over the resource, such as Intellectual Property Rights (IPR), Copyright, and various Property Rights. The Rights element may be used for either a textual statement or a URL pointing to a rights statement, or a combination, when a brief statement and a more lengthy one are available. Examples: Rights=“Access limited to members” Rights=“http://cs-tr.cs.cornell.edu/Dienst/Repository/2.0/Terms” The value of this field is “dc:rights” getMetadata() returns an array of Strings. See Also: getMetadata(String) SCHEDULED_END_TIME public static final java.lang.String SCHEDULED_END_TIME End time of a scheduled program. The value of this field is “upnp:scheduledEndTime” getMetadata() returns java.util.Date. See Also: getMetadata(String) SCHEDULED_START_TIME public static final java.lang.String SCHEDULED_START_TIME Start time of a scheduled program. The value of this field is “upnp:scheduledStartTime” getMetadata() returns java.util.Date. See Also: getMetadata(String) STORAGE_MEDIUM public static final java.lang.String STORAGE_MEDIUM Indicates the type of storage medium used for the content. Potentially useful for user-interface purposes. Allowed values are defined by UPnP and include: • “UNKNOWN” • “DV” • “MINI-DV” • “VHS” B org.ocap.hn.content CableLabs® 123
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification • “W-VHS” • “S-VHS” • “D-VHS” • “VHSC” • “VIDEO8” • “HI8” • “CD-ROM” • “CD-DA” • “CD-R” • “CD-RW” • “VIDEO-CD” • “SACD” • “MD-AUDIO” • “MD-PICTURE” • “DVD-ROM” • “DVD-VIDEO” • “DVD-R” • “DVD+RW” • “DVD-RW” • “DVD-RAM” • “DVD-AUDIO” • “DAT” • “LD” • “HDD” • “SD” • “PC-CARD” • “MMC” • “CF” • “BD” • “MS” The value of this field is “upnp:storageMedium”. TITLE public static final java.lang.String TITLE The identifier for the title of an item. This could be the title of a song, a recording, a photo etc. This identifier is valid for all kinds of content. 124 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Queries for TITLE should always return a String. The value of this key is “dc:title”. See Also: getMetadata(String) TRACK_NUMBER public static final java.lang.String TRACK_NUMBER Original track number on a CD or other medium. The value of this field is “upnp:originalTrackNumber” getMetadata() returns an Integer. See Also: getMetadata(String) Methods getIdentifierNames() public java.util.Enumeration getIdentifierNames() Returns an Enumeration of all identifier names. Returns: Enumeration of all identifier names getMetadata() public java.util.Enumeration getMetadata() Returns an Enumeration of all Metadata objects. Returns: Enumeration of all metadata objects getMetadata(String) public java.lang.Object getMetadata(java.lang.String which) Returns the metadata for an Identifier e.g., the Title, Genre, Artist. The returned value is used by SearchableList to perform sorting, searching etc. Unless otherwise stated by the key definition the return object is a String. Parameters: which - The name of the identifier Returns: The identifier itself See Also: TITLE, ALBUM, CREATION_DATE, CREATOR getNumberOfIdentifiers() public int getNumberOfIdentifiers() Returns the number of Identifiers Returns: the number of identifiers B org.ocap.hn.content CableLabs® 125
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification getParentNode() public org.ocap.hn.content.MetadataNode getParentNode() Returns the parent MetadataNode Returns: the parent MetadataNode 126 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn.content MetadataNode Declaration public abstract class MetadataNode implements Metadata java.lang.Object | +--org.ocap.hn.content.MetadataNode All Implemented Interfaces: Metadata Description Base class for all Metadata. Metadata can be a normal java.lang.String, a java.awt.Image, another MetadataNode for tree like meta data structures or other tbd Objects. One example is given below: RootNode | --- TITLE - String(“Best Movie Ever”) | --- CREW - MetadataNode | --- MAIN_ACTOR - String(“Joe Sixpack”) | --- MAIN_ACTOR2 - String(“Doris Dosenkohl”) | --- SYNOPSIS - String(“Don't know - I fell asleep after 5 seconds”) | ---IMAGE - Image(“/home/user/images/BestMovieEver.jpg”) It is possible to get Metadata from other MetadataNodes directly by concatenating the different identifiers using # to separate them. e.g. getMetadata(“CREW#MAIN_ACTOR”) would return “Joe Sixpack” Member Summary Constructors MetadataNode() Methods void addMetadata(java.lang.String key, java.lang.Object value) Adds a new metadata entry. aquireMetadata(java.lang.String ids, org.ocap.hn.NetActionR org.ocap.hn.NetActionHandler handler) equest The Metadata might be stored on a different device on the network. java.util.Enumeration getIdentifierNames() java.util.Enumeration getMetadata() Returns an Enumeration of all Metadata objects in this node. java.lang.Object getMetadata(java.lang.String key) Returns the Metadata for the specified key. int getNumberOfIdentifiers() MetadataNode getParentNode() B org.ocap.hn.content CableLabs® 127
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Member Summary java.lang.String getText() Returns a human readable textual representation of the Metadata Constructors MetadataNode() public MetadataNode() Methods addMetadata(String, Object) public void addMetadata(java.lang.String key, java.lang.Object value) Adds a new metadata entry. Parameters: key - The key e.g. ’TITLE’ value - The value e.g., ’When Harry Meets Sally’ or a more complex Object like another MetadataNode. aquireMetadata(String[], NetActionHandler) public org.ocap.hn.NetActionRequest aquireMetadata(java.lang.String[] ids, org.ocap.hn.NetActionHandler handler) The Metadata might be stored on a different device on the network. This method request that the Metadata specified by the identifiers in the String array are transferred to the local machine. If the array is null all Metadata for this MetadataNode and its sub nodes is transferred. This is an asynchronous method. Parameters: ids - the keys which values should be acquired handler - the NetActionHandler which will be called once the operation is completed. getIdentifierNames() public java.util.Enumeration getIdentifierNames() Description copied from interface: org.ocap.hn.content.Metadata Returns an Enumeration of all identifier names. Specified By: getIdentifierNames in interface Metadata getMetadata() public java.util.Enumeration getMetadata() Returns an Enumeration of all Metadata objects in this node. Specified By: getMetadata in interface Metadata 128 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Returns: Enumeration of all Me getMetadata(String) public java.lang.Object getMetadata(java.lang.String key) Returns the Metadata for the specified key. The returned object can be a normal String (e.g. for title etc.), a java.awt.Image, a Vector containing a list of elements, another MetadataNode for tree like metadata structures or other tbd. Objects In order to query a Metadata in a hierarchy query strings like IDENT1#IDENT2#IDENT3 are possible where IDENT1 is a MetadataNode in this node, IDENT2 a MetadataNode in IDENT2 and IDENT3 an object in IDENT2. This method might get its data via the network and could take some time. Specified By: getMetadata in interface Metadata Parameters: Returns: the value associated with the key. The keys defined in Metadata define which kind of Object is returned. In most cases this will be Strings, there are however exceptions. getNumberOfIdentifiers() public int getNumberOfIdentifiers() Description copied from interface: org.ocap.hn.content.Metadata Returns the number of Identifiers Specified By: getNumberOfIdentifiers in interface Metadata getParentNode() public org.ocap.hn.content.MetadataNode getParentNode() Description copied from interface: org.ocap.hn.content.Metadata Returns the parent MetadataNode Specified By: getParentNode in interface Metadata getText() public java.lang.String getText() Returns a human readable textual representation of the Metadata Returns: textual representation of the meta data. B org.ocap.hn.content CableLabs® 129
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content RecordingContentItem Declaration public abstract class RecordingContentItem extends ContentItem java.lang.Object | +--org.ocap.hn.content.ContentItem | +--org.ocap.hn.content.RecordingContentItem All Implemented Interfaces: java.lang.Comparable, ContentEntry, Metadata, org.ocap.hn.util.SearchableItem Description This class represents a content entry that is also a RecordingListEntry. Member Summary Constructors RecordingContentItem() Methods void addAppData(int dataID, byte[] data) int compareTo(java.lang.Object o) void copyTo(ContentDirectory container) boolean delete() byte[] getAppData(int dataID) int[] getAppDataIDs() getAppID() org.dvb.application.Ap pID long getContentSize() java.util.Date getCreationDate() getExtendedFileAccessPermissions() ExtendedFileAccessPerm issions java.util.Enumeration getIdentifierNames() java.util.Enumeration getMetadata() java.lang.Object getMetadata(java.lang.String which) java.lang.String getName() int getNumberOfIdentifiers() ContentContainer getParent() boolean isLocal() void moveTo(ContentDirectory container) void removeAppData(int dataID) 130 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Constructors RecordingContentItem() public RecordingContentItem() Methods addAppData(int, byte[]) public void addAppData(int dataID, byte[] data) throws NoMoreDataEntriesException Throws: .NoMoreDataEntriesException compareTo(Object) public int compareTo(java.lang.Object o) Description copied from interface: org.ocap.hn.util.SearchableItem throws ClassCastException copyTo(ContentDirectory) public void copyTo(org.ocap.hn.content.ContentDirectory container) throws IOException, SecurityException Throws: java.lang.SecurityException, java.io.IOException delete() public boolean delete() throws IOException, SecurityException Description copied from class: org.ocap.hn.content.ContentItem Deletes this ContentItem including all its ContentResource s. Note: this overrides the definition of ContentEntry The ContentEntry is not valid anymore after this call. Implementations of this interface might override the behavior of this method. Note that this is a synchronous method. If an asynchronous method is required org.ocap.hn.ContentManagementModule.delete(Locator, NetActionHandler) should be used. Overrides: delete in class ContentItem Throws: java.lang.SecurityException, java.io.IOException B org.ocap.hn.content CableLabs® 131
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification getAppData(int) public byte[] getAppData(int dataID) getAppDataIDs() public int[] getAppDataIDs() getAppID() public org.dvb.application.AppID getAppID() getContentSize() public long getContentSize() Description copied from class: org.ocap.hn.content.ContentItem Returns the size of the content in bytes or -1 if not known. The size returned is the sum of all its ContentResource s Overrides: getContentSize in class ContentItem getCreationDate() public java.util.Date getCreationDate() Description copied from interface: org.ocap.hn.content.ContentEntry Returns the creation date of the content or NULL if not known. getExtendedFileAccessPermissions() public ExtendedFileAccessPermissions getExtendedFileAccessPermissions() Description copied from interface: org.ocap.hn.content.ContentEntry Returns the file permissions of a ContentEntry. getIdentifierNames() public java.util.Enumeration getIdentifierNames() Description copied from interface: org.ocap.hn.util.SearchableItem Returns an Enumeration of all identifier names. getMetadata() public java.util.Enumeration getMetadata() Description copied from interface: org.ocap.hn.util.SearchableItem Returns an Enumeration of all Metadata objects. getMetadata(String) public java.lang.Object getMetadata(java.lang.String which) 132 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Description copied from interface: org.ocap.hn.util.SearchableItem Returns the metadata for an Identifier such as the Title, Genre, Artist. getName() public java.lang.String getName() Description copied from class: org.ocap.hn.content.ContentItem Returns the name of this ContentItem. Note: this overides the definition of ContentEntry Overrides: getName in class ContentItem getNumberOfIdentifiers() public int getNumberOfIdentifiers() Description copied from interface: org.ocap.hn.util.SearchableItem Returns the number of Identifiers getParent() public org.ocap.hn.content.ContentContainer getParent() Description copied from interface: org.ocap.hn.content.ContentEntry Returns the ContentContainer this ContentEntry belongs to. isLocal() public boolean isLocal() Description copied from interface: org.ocap.hn.content.ContentEntry Returns true when the content is on the local device, false if it is hosted by another device on the network moveTo(ContentDirectory) public void moveTo(org.ocap.hn.content.ContentDirectory container) throws IOException, SecurityException Throws: java.lang.SecurityException, java.io.IOException removeAppData(int) public void removeAppData(int dataID) B org.ocap.hn.content CableLabs® 133
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content VideoResource Declaration public interface VideoResource Description Interface implemented by subclasses of ContentResource to identify that a content contains video/still image material. Member Summary Methods int getColorDepth() Returns the color depth (in bits) of the video/still image. java.awt.Dimension getResolution() Returns the resolution of the video/still image. Methods getColorDepth() public int getColorDepth() Returns the color depth (in bits) of the video/still image. Returns: the color depth (in bits) of the video/still image. getResolution() public java.awt.Dimension getResolution() Returns the resolution of the video/still image. Returns: the resolution of the video/still image 134 CableLabs® B org.ocap.hn.content
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Annex C org.ocap.hn.content.navigation This annex presents the org.ocap.hn.content.navigation APIs. Package org.ocap.hn.content.navigation Class Summary Classes ContentDatabaseFilter This class represent a filtering criteria to be applied while creating a ContentList. ContentList This interface represents a list of filtered ContentEntries. DatabaseQuery DatabaseQuery class. DeviceFilter This class represents a filtering criteria based on a particular device. C org.ocap.hn.content.navigation CableLabs® 135
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content.navigation ContentDatabaseFilter Declaration public abstract class ContentDatabaseFilter java.lang.Object | +--org.ocap.hn.content.navigation.ContentDatabaseFilter Direct Known Subclasses: DatabaseQuery, DeviceFilter Description This class represent a filtering criteria to be applied while creating a ContentList. Member Summary Constructors protected ContentDatabaseFilter() Methods abstract boolean accept(org.ocap.hn.content.ContentItem entry) This method is called for every ContentItem in the database/list this filter is applied to. Constructors ContentDatabaseFilter() protected ContentDatabaseFilter() Methods accept(ContentItem) public abstract boolean accept(org.ocap.hn.content.ContentItem entry) This method is called for every ContentItem in the database/list this filter is applied to. Implementations should return true if the specified ContentItem should be in the filtered list. If the ContentItem should not be listed in the new list false should be returned. Parameters: entry - the ContentItem to filter Returns: true if the ContentItem should be in the filtered ContentList, false otherwise. 136 CableLabs® C org.ocap.hn.content.navigation
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn.content.navigation ContentList Declaration public class ContentList extends org.ocap.hn.util.SearchableList java.lang.Object | +--org.ocap.hn.util.TreeListAbstraction | +--org.ocap.hn.util.SearchableList | +--org.ocap.hn.content.navigation.ContentList All Implemented Interfaces: org.ocap.hn.util.Searchable Description This interface represents a list of filtered ContentEntries. Member Summary Constructors ContentList() Methods void addContentListListener(org.ocap.hn.content.ContentListListene r listener) Adds a ContentListListener to this ContentList. ContentList filterContentList(ContentDatabaseFilter filter) Filters the ContentList. void removeContentListListener(org.ocap.hn.content.ContentListList ener listener) Removes the specified ContentListListener. Constructors ContentList() public ContentList() Methods addContentListListener(ContentListListener) public void addContentListListener(org.ocap.hn.content.ContentListListener listener) Adds a ContentListListener to this ContentList. C org.ocap.hn.content.navigation CableLabs® 137
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Parameters: listener - the Listener that will receive ContentListEvents. filterContentList(ContentDatabaseFilter) public org.ocap.hn.content.navigation.ContentList filterContentList(org.ocap.hn.content.navigation.ContentDatabaseFilter filter) throws DatabaseException Filters the ContentList. The returned ContentList is a new ContentList only containing ContentItems on which ContentDatabaseFilter.accept returned true. Parameters: filter - the ContentDatabaseFilter Returns: newly created ContentList containing only the filtered ContentItems. Throws: org.ocap.hn.content.DatabaseException removeContentListListener(ContentListListener) public void removeContentListListener(org.ocap.hn.content.ContentListListener listener) Removes the specified ContentListListener. Parameters: listener - the Listener to remove 138 CableLabs® C org.ocap.hn.content.navigation
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn.content.navigation DatabaseQuery Declaration public abstract class DatabaseQuery extends ContentDatabaseFilter java.lang.Object | +--org.ocap.hn.content.navigation.ContentDatabaseFilter | +--org.ocap.hn.content.navigation.DatabaseQuery Description DatabaseQuery class. This class represents a query of the metadata database. Methods are provided so that complex AND, OR, NOT expressions can be created. Note that this object is immutable; the and(), or() and negate() methods do not affect this object but return references to a new query. For example: DatabaseQuery qa = DatabaseQuery.newInstance (“Genre”, DatabaseQuery.EQUALS, “3.4.11”); DatabaseQuery qb = DatabaseQuery.newInstance (“SpokenLanguage”, DatabaseQuery.EQUALS, “fr-CA”); DatabaseQuery qc = qb.and(qa.negate()); So the final statement has no effect on the state of qa or qb objects, which still represent non-negated, root predicates. Member Summary Fields static int CONTAINS Operator to check for a String being contained within the field The comparison is case insensitive, non whole word. static int EQUALS Used to specify a test for equality. static int EXISTS Operator to check to see if a field exists static int GREATER_THAN Operator to specify greater than. static int GREATER_THAN_OR_EQUALS Operator to specify greater than or equals See rules for GREATER_THAN and EQUALS for how non-numeric fields are compared. static int LESS_THAN Operator to specify less than. static int LESS_THAN_OR_EQUALS Operator to specify less than or equals See rules for LESS_THAN and EQUALS for how non-numeric fields are compared. static int NOT_EQUALS Operator to check for in-equality. Constructors DatabaseQuery() C org.ocap.hn.content.navigation CableLabs® 139
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Member Summary Methods abstract DatabaseQuery and(DatabaseQuery query) Create a new DatabaseQuery based upon the logical AND of the predicates represented by this query and the argument query. abstract DatabaseQuery and(DatabaseQuery query, java.lang.String contextNode) Create a new DatabaseQuery object based upon the logical AND of the predicates represented by this query and the argument query. abstract DatabaseQuery negate() Create a new DatabaseQuery, which is the logical NOT of this query. static DatabaseQuery newInstance(java.lang.String fieldName, int comparison, java.lang.String value) Make a new DatabaseQuery for a specific value in a specific field. abstract DatabaseQuery or(DatabaseQuery query) Create a new DatabaseQuery based upon the logical OR of the predicates represented by this query and the argument query. Fields CONTAINS public static final int CONTAINS Operator to check for a String being contained within the field The comparison is case insensitive, non whole word. EQUALS public static final int EQUALS Used to specify a test for equality. For numbers and dates, an exact match is made. For strings, a case- insensitive comparison is made EXISTS public static final int EXISTS Operator to check to see if a field exists GREATER_THAN public static final int GREATER_THAN Operator to specify greater than. For numbers the test is “a>b”. For Date fields, the test is “a is after b”. For strings, the comparison is based on case-insensitive dictionary ordering (i.e. which value occurs first when sorted in alphabetical order). E.g. “dog” > “cat” == true, “Chimp” > “dog” == false GREATER_THAN_OR_EQUALS public static final int GREATER_THAN_OR_EQUALS Operator to specify greater than or equals See rules for GREATER_THAN and EQUALS for how non- numeric fields are compared. 140 CableLabs® C org.ocap.hn.content.navigation
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 LESS_THAN public static final int LESS_THAN Operator to specify less than. For numbers the test is “a<b”. For Date fields, the test is “a is before b”. For strings, the comparison is based on case-insensitive dictionary ordering (i.e. which one occurs first when sorted in alphabetical order). LESS_THAN_OR_EQUALS public static final int LESS_THAN_OR_EQUALS Operator to specify less than or equals See rules for LESS_THAN and EQUALS for how non-numeric fields are compared. NOT_EQUALS public static final int NOT_EQUALS Operator to check for in-equality. NOT_EQUALS follows the same equality checking rules as EQUALS Constructors DatabaseQuery() public DatabaseQuery() Methods and(DatabaseQuery) public abstract org.ocap.hn.content.navigation.DatabaseQuery and(org.ocap.hn.content.navigation.DatabaseQuery query) throws DatabaseException Create a new DatabaseQuery based upon the logical AND of the predicates represented by this query and the argument query. Parameters: query - The second predicate for the AND Throws: DatabaseException - if the AND of these two queries is known to be invalid org.ocap.hn.content.DatabaseException and(DatabaseQuery, String) public abstract org.ocap.hn.content.navigation.DatabaseQuery and(org.ocap.hn.content.navigation.DatabaseQuery query, java.lang.String contextNode) throws DatabaseException Create a new DatabaseQuery object based upon the logical AND of the predicates represented by this query and the argument query. The resulting predicate will only match within the scope of the specified node. For example: C org.ocap.hn.content.navigation CableLabs® 141
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification DatabaseQuery a(“Title”,DatabaseQuery.CONTAINS,“grave”); DatabaseQuery b(“TitleLanguage”,DatabaseQuery.EQUALS,“en”); DatabaseQuery query = a.and(b,“Title); will cause a search for a title that contains the name “grave” and has an English language title, within the same title node. Without the context node, a valid match would be found for: Dilemma Grave Serious Dilemma because there is a title with lang=“en” and a title which contains “grave”. Parameters: query - The second predicate for the AND contextNode - The node within which all of the AND must be satisfied. This node must be the name of known field ID, (i.e. FieldID.getInstance().hasKey(fieldName) must return true) and must be a node that is at least the highest level element represented by the two predicates (i.e. the context node is not a child node of either predicate). Throws: DatabaseException - if the AND of these two queries is known to be invalid, or the contextNode is invalid org.ocap.hn.content.DatabaseException negate() public abstract org.ocap.hn.content.navigation.DatabaseQuery negate() Create a new DatabaseQuery, which is the logical NOT of this query. Returns: a new DatabaseQuery object that is the logical negative of this object. newInstance(String, int, String) public static org.ocap.hn.content.navigation.DatabaseQuery newInstance(java.lang.String fieldName, int comparison, java.lang.String value) throws DatabaseException Make a new DatabaseQuery for a specific value in a specific field. This is how the root predicates of a query is formed. For example: DatabaseQuery q1 = DatabaseQuery.newInstance(“Title”, DatabaseQuery.CONTAINS, “Foxes”); DatabaseQuery q2 = DatabaseQuery.newInstance(“Genre”, DatabaseQuery.CONTAINS, “3.4.11”); DatabaseQuery the_query = q1.and(q2); Parameters: fieldName - The name of the field to compare. This field must be the name of known field ID, i.e. FieldID.getInstance().hasKey(fieldName) must return true. comparison - The type of comparison to make (CONTAINS, EXISTS, LESS_THAN, etc.) value - The value to check. For numeric fields, the value must be a string that contains a number. For date fields, the value must be a date in an ISO 8601 compliant format (e.g. of the form “2001- 01-05T14:30:00Z” or “2001-01-05T15:30:00+01:00”). For fields that contain an item from a classification scheme (e.g. the “Genre” field), the ID of the controlled term must be used (e.g. “3.4.11”). For comparison==DatabaseQuery.EXISTS, this parameter is not used (it is safe to pass null in this case). 142 CableLabs® C org.ocap.hn.content.navigation
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Throws: DatabaseException - is the specified fieldName is unknown, if the comparison is unknown or value is invalid. org.ocap.hn.content.DatabaseException or(DatabaseQuery) public abstract org.ocap.hn.content.navigation.DatabaseQuery or(org.ocap.hn.content.navigation.DatabaseQuery query) throws DatabaseException Create a new DatabaseQuery based upon the logical OR of the predicates represented by this query and the argument query. Parameters: query - The second predicate for the OR Throws: DatabaseException - if the AND of these two queries is known to be invalid org.ocap.hn.content.DatabaseException C org.ocap.hn.content.navigation CableLabs® 143
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.content.navigation DeviceFilter Declaration public class DeviceFilter extends ContentDatabaseFilter java.lang.Object | +--org.ocap.hn.content.navigation.ContentDatabaseFilter | +--org.ocap.hn.content.navigation.DeviceFilter Description This class represents a filtering criteria based on a particular device. Applications may use this filter to create a ContentList with content entries from a particular device. Member Summary Constructors DeviceFilter(org.ocap.hn.Device device) Creates a new DeviceFilter. Methods boolean accept(org.ocap.hn.content.ContentItem entry) Constructors DeviceFilter(Device) public DeviceFilter(org.ocap.hn.Device device) Creates a new DeviceFilter. Only ContentItems which are hosted by the specified Device will pass this filter. Parameters: device - the device to filter on Methods accept(ContentItem) public boolean accept(org.ocap.hn.content.ContentItem entry) Description copied from class: org.ocap.hn.content.navigation.ContentDatabaseFilter This method is called for every ContentItem in the database/list this filter is applied to. Implementations should return true if the specified ContentItem should be in the filtered list. If the ContentItem should not be listed in the new list false should be returned. Overrides: accept in class ContentDatabaseFilter 144 CableLabs® C org.ocap.hn.content.navigation
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. 145 CableLabs®
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification 146 CableLabs® C org.ocap.hn.content.navigation
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Annex D org.ocap.hn.util This annex presents the org.ocap.hn.util APIs. Package org.ocap.hn.util Description Provides classes and interfaces for sortable and searchable lists. The package provides classes and interfaces for sortable and searchable lists. SearchableList is the main class of this package. UPnP mapping There is no mapping to UPnP given as it is assumed that sorting and searching is done in a local database. Class Summary Interfaces Searchable This interface should be implemented by the database and by SearchableList SearchableItem Interface which should be implemented by all items added to a SearchableList. Classes MultiLevelComparator Class which allows a multi level comparison. SearchableList A SearchableList is a TreeList Abstraction which offers advanced search and sort options. TreeListAbstraction This class is used in lieu of J2ME CDC. D org.ocap.hn.util CableLabs® 147
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.util MultiLevelComparator Declaration public class MultiLevelComparator java.lang.Object | +--org.ocap.hn.util.MultiLevelComparator Description Class which allows a multi level comparison. This can be used together with a java.util.TreeSet to achieve a multi level sorting. Member Summary Constructors MultiLevelComparator(java.lang.String keys) Methods int compare(java.lang.Object o1, java.lang.Object o2) Performs a multi level comparison. boolean equals(java.lang.Object obj) Indicates whether some other object is “equal to” this MultiLevelComparator. java.lang.String[] getSortOrder() Returns an array with all keys used to sort a list in the order they are used in the sorting. void setSortOrder(java.lang.String keys) Sets the sort order of the items. Constructors MultiLevelComparator(String[]) public MultiLevelComparator(java.lang.String[] keys) Methods compare(Object, Object) public int compare(java.lang.Object o1, java.lang.Object o2) Performs a multi level comparison. 148 CableLabs® D org.ocap.hn.util
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 SearchableItem item1 = (SearchableItem)o1; SearchableItem item2 = (SearchableItem)o2; String[] sort = getSortOrder(); int ret = 0; for(int i = 0; i equals(Object) public boolean equals(java.lang.Object obj) Indicates whether some other object is “equal to” this MultiLevelComparator. This method must obey the general contract of Object.equals(Object). Additionally, this method can return true only if the specified Object is also a comparator and it imposes the same ordering as this comparator. Thus, comp1.equals(comp2) implies that sgn(comp1.compare(o1, o2))==sgn(comp2.compare(o1, o2)) for every object reference o1 and o2. Note that it is always safe not to override Object.equals(Object). However, overriding this method may, in some cases, improve performance by allowing programs to determine that two distinct Comparators impose the same order. Overrides: equals in class Object Parameters: obj - The reference object with which to compare. Returns: true only if the specified object is also a multi-level comparator and it imposes the same ordering as this one. getSortOrder() public java.lang.String[] getSortOrder() Returns an array with all keys used to sort a list in the order they are used in the sorting. Returns: array of keys used for sorting setSortOrder(String[]) public void setSortOrder(java.lang.String[] keys) Sets the sort order of the items. For example, a song could have the metadata identifiers: ’Title’, ’Artist’,’CD’, year (expressed as an Integer). To sort the songs in the order Artist, CD, title you would create an array String[] sort = {“Artist”,“CD”,“Title”}; setSortOrder(sort); If the array is null the natural (tbd for each type) sort order of that item is used. When the function is called SearchableList.setSortOrder(String[]) is called on all elements in the list. Parameters: keys - array containing the sort order. See Also: SearchableList.setSortOrder(String[]) D org.ocap.hn.util CableLabs® 149
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.util Searchable Declaration public interface Searchable All Known Implementing Classes: SearchableList Description This interface should be implemented by the database and by SearchableList Member Summary Methods java.lang.Object find(java.lang.String keys, java.lang.Object values) Finds the first SearchableItems which matches the search. java.lang.Object find(java.lang.String key, java.lang.Object obj) Finds the first SearchableItem which Identifier for the key ’key’ equals the given object obj SearchableList findAll(java.lang.String identifier, java.lang.Object compValues) Finds all SearchableItems which matches the search. Methods find(String[], Object[]) public java.lang.Object find(java.lang.String[] keys, java.lang.Object[] values) Finds the first SearchableItems which matches the search. Let value[i] be the ’metadata’ specified by identifier[i] with value[i] = get_data(identifier[i]) were get_data() is a not specified function to retrieve the data associated to the identifier[i]. An item matches the search when getMetadata(identifier[i]).equals(value[i]) && getMetadata(identifier[i+1]).equals(value[i+1) && ... for all i = 0 to i< identifier.length Parameters: keys - array of search keys values - array of object to compare with Returns: the first found item or null See Also: SearchableItem.getMetadata(String) find(String, Object) public java.lang.Object find(java.lang.String key, java.lang.Object obj) 150 CableLabs® D org.ocap.hn.util
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Finds the first SearchableItem which Identifier for the key ’key’ equals the given object obj Parameters: obj - The object to compare to key - the Identifier key Returns: the first found item or null See Also: SearchableItem.getMetadata(String) findAll(String[], Object[]) public org.ocap.hn.util.SearchableList findAll(java.lang.String[] identifier, java.lang.Object[] compValues) Finds all SearchableItems which matches the search. Let value[i] be the ’metadata’ specified by identifier[i] with value[i] = get_data(identifier[i]) were get_data() is a not specified function to retrieve the data associated to the identifier[i]. An item matches the search when getMetadata(identifier[i]).equals(value[i]) && getMetadata(identifier[i+1]).equals(value[i+1) && ... for all i = 0 to i< identifier.length D org.ocap.hn.util CableLabs® 151
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.util SearchableItem Declaration public interface SearchableItem extends java.lang.Comparable, org.ocap.hn.content.Metadata All Superinterfaces: java.lang.Comparable, org.ocap.hn.content.Metadata Description Interface which should be implemented by all items added to a SearchableList. SearchableItem and SearchableList add advanced search and sort options to the Java collection API. Member Summary Methods int compareTo(java.lang.Object o) throws ClassCastException java.util.Enumeration getIdentifierNames() Returns an Enumeration of all identifier names. java.util.Enumeration getMetadata() Returns an Enumeration of all Metadata objects. java.lang.Object getMetadata(java.lang.String which) Returns the metadata for an Identifier such as the Title, Genre, Artist. int getNumberOfIdentifiers() Returns the number of Identifiers Methods compareTo(Object) public int compareTo(java.lang.Object o) throws ClassCastException Overrides: compareTo in interface Comparable getIdentifierNames() public java.util.Enumeration getIdentifierNames() Returns an Enumeration of all identifier names. Overrides: getIdentifierNames in interface Metadata Returns: Enumeration of all identifier names getMetadata() public java.util.Enumeration getMetadata() 152 CableLabs® D org.ocap.hn.util
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Returns an Enumeration of all Metadata objects. Overrides: getMetadata in interface Metadata Returns: Enumeration of all metadata objects getMetadata(String) public java.lang.Object getMetadata(java.lang.String which) Returns the metadata for an Identifier such as the Title, Genre, Artist. Overrides: getMetadata in interface Metadata Parameters: which - The name of the identifier Returns: The identifier itself getNumberOfIdentifiers() public int getNumberOfIdentifiers() Returns the number of Identifiers Overrides: getNumberOfIdentifiers in interface Metadata Returns: the number of identifiers D org.ocap.hn.util CableLabs® 153
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.util SearchableList Declaration public class SearchableList extends TreeListAbstraction implements Searchable java.lang.Object | +--org.ocap.hn.util.TreeListAbstraction | +--org.ocap.hn.util.SearchableList All Implemented Interfaces: Searchable Description A SearchableList is a TreeList Abstraction which offers advanced search and sort options. All items added to a SearchableList must implement the SearchableItem interface. Member Summary Constructors SearchableList() Methods boolean contains(java.lang.Object o) java.util.Enumeration enumeration() Returns an enumeration over the elements in this set. java.lang.Object find(java.lang.String keys, java.lang.Object values) Finds the first SearchableItems which matches the search. java.lang.Object find(java.lang.String key, java.lang.Object obj) Finds the first SearchableItem which Identifier for the key ’key’ equals the given object obj SearchableList findAll(java.lang.String identifier, java.lang.Object compValues) Finds all SearchableItems which matches the search. java.lang.String[] getSortOrder() void setSortOrder(java.lang.String keys) Sets the sort order of the items in this list. Constructors SearchableList() public SearchableList() 154 CableLabs® D org.ocap.hn.util
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Methods contains(Object) public boolean contains(java.lang.Object o) Description copied from class: org.ocap.hn.util.TreeListAbstraction See TreeSet Overrides: contains in class TreeListAbstraction Parameters: Returns: true if the object exists in this list enumeration() public java.util.Enumeration enumeration() Returns an enumeration over the elements in this set. The elements are returned in ascending order. Returns: An enumeration over the elements in this set. find(String[], Object[]) public java.lang.Object find(java.lang.String[] keys, java.lang.Object[] values) Finds the first SearchableItems which matches the search. Let value[i] be the ’metadata’ specified by identifier[i] with value[i] = get_data(identifier[i]) were get_data() is a not specified function to retrieve the data associated to the identifier[i]. An item matches the search when getMetadata(identifier[i]).equals(value[i]) && getMetadata(identifier[i+1]).equals(value[i+1) && ... for all i = 0 to i< identifier.length Specified By: find in interface Searchable Parameters: keys - array of search keys values - array of object to compare with Returns: the first found item or null See Also: SearchableItem.getMetadata(String) find(String, Object) public java.lang.Object find(java.lang.String key, java.lang.Object obj) Finds the first SearchableItem which Identifier for the key ’key’ equals the given object obj Specified By: find in interface Searchable Parameters: obj - The object to compare to key - the Identifier key Returns: the first found item or null D org.ocap.hn.util CableLabs® 155
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification See Also: SearchableItem.getMetadata(String) findAll(String[], Object[]) public org.ocap.hn.util.SearchableList findAll(java.lang.String[] identifier, java.lang.Object[] compValues) Finds all SearchableItems which matches the search. Let value[i] be the ’metadata’ specified by identifier[i] with value[i] = get_data(identifier[i]) were get_data() is a not specified function to retrieve the data associated to the identifier[i]. An item matches the search when getMetadata(identifier[i]).equals(value[i]) && getMetadata(identifier[i+1]).equals(value[i+1) && ... for all i = 0 to i< identifier.length Specified By: findAll in interface Searchable getSortOrder() public java.lang.String[] getSortOrder() setSortOrder(String[]) public void setSortOrder(java.lang.String[] keys) Sets the sort order of the items in this list. A song could have the metadata identifiers: ’Title’, ’Artist’, ’CD’, year (expressed as an Integer). To sort the songs in the order Artist, CD, title you would create an array String[] sort = {“Artist”,“CD”,“Title”}; setSortOrder(sort); If the array is null the natural (tbd for each type) sort order of that item is used Parameters: keys - array containing the sort order. 156 CableLabs® D org.ocap.hn.util
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 org.ocap.hn.util TreeListAbstraction Declaration public class TreeListAbstraction java.lang.Object | +--org.ocap.hn.util.TreeListAbstraction Direct Known Subclasses: SearchableList Description This class is used in lieu of J2ME CDC. This interface should be implemented by classes which offer a sorted map similar to the java.util.TreeSet class. Member Summary Constructors TreeListAbstraction() Methods boolean add(java.lang.Object o) See TreeSet void clear() See TreeSet boolean contains(java.lang.Object o) See TreeSet java.util.Enumeration elements() TreeSet would return an Iterator but as Iterator is only part of Java 2 we return an Enumeration here. boolean isEmpty() See TreeSet boolean remove(java.lang.Object o) See TreeSet int size() See TreeSet java.lang.Object[] toArray() See TreeSet Constructors TreeListAbstraction() public TreeListAbstraction() D org.ocap.hn.util CableLabs® 157
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification Methods add(Object) public boolean add(java.lang.Object o) See TreeSet Parameters: Returns: see TreeSet clear() public void clear() See TreeSet contains(Object) public boolean contains(java.lang.Object o) See TreeSet Parameters: Returns: true if the object exists in this list elements() public java.util.Enumeration elements() TreeSet would return an Iterator but as Iterator is only part of Java 2 we return an Enumeration here. Returns: Enumeration of all elements isEmpty() public boolean isEmpty() See TreeSet Returns: true if empty remove(Object) public boolean remove(java.lang.Object o) See TreeSet Parameters: Returns: true if object has been removed size() public int size() See TreeSet Returns: the size 158 CableLabs® D org.ocap.hn.util
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 toArray() public java.lang.Object[] toArray() See TreeSet Returns: see TreeSet D org.ocap.hn.util CableLabs® 159
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification This page intentionally left blank. 160 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Annex E org.ocap.hn.service This annex presents the org.ocap.hn.service APIs. Package org.ocap.hn.service Class Summary Interfaces RemoteService A RemoteService is a service which is hosted or provided by another device on the home network E org.ocap.hn.service CableLabs® 161
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification org.ocap.hn.service RemoteService Declaration public interface RemoteService extends javax.tv.service.Service All Superinterfaces: javax.tv.service.Service Description A RemoteService is a service which is hosted or provided by another device on the home network Member Summary Methods getContentItem() org.ocap.hn.content.Co Returns the ContentItem associated with this remote service ntentItem Methods getContentItem() public org.ocap.hn.content.ContentItem getContentItem() Returns the ContentItem associated with this remote service Returns: The org.ocap.hn.content.ContentItem associated with this service. 162 CableLabs® E org.ocap.hn.service
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 Annex F UPnP Mappings (Normative) This annex contains the mappings from the OCAP Home Networking API method, for calls to UPnP actions. When UPnP is used as the home networking protocol mechanism, devices which are OCAP Home Networking Extensions specification compliant, SHALL contain the following UPnP services: • Audio/Video Transport • Content Directory • Connection Management When UPnP is used as the home networking protocol mechanism, the OCAP Home Networking Extension specification compliant devices SHALL map OCAP Home Networking API methods to UPnP actions, per the sections in this annex. Note: The word service is used in both an OCAP and UPnP context below and has a different meaning for each. F.1 Package org.ocap.hn F.1.1 ContentManagementModule interface F.1.1.1 copy method There are two cases that affect UPnP action mapping to this method: a) When the destination is not the device, this method, called from the UPnP AVTransport service Record action, SHALL be used. This technique can be used when the control point is neither the source, nor the destination, and when the control point is the source. b) When the destination is the device, this method, called from the UPnP ContentDirectory service ImportResource action, SHALL be used. F.1.1.2 move method This is the same as the copy method, except the content MUST be deleted from the source once the copy has completed successfully. See the following delete method. F.1.1.3 delete method First, the UPnP ContentDirectory service DestroyObject SHALL be used. If the locator for the content is an entire OCAP service, the service is deleted, using the UPnP ContentDirectory service DestroyResource. In this case, all of the content and metadata associated with the OCAP service are deleted. F.1.1.4 rename method The UPnP ContentDirectory service UpdateObject SHALL be used. This will only change the metadata for the content (e.g., song name), and does not alter file, directory, or OCAP service names. CableLabs® 163
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification F.1.2 RemoteMediaRendererModule interface F.1.2.1 createRemotePlayer method Content rendering using the UPnP AV architecture allows a UPnP Control Point to control the streaming playback of content from a Server to a content Renderer. the createRemotePlayer method establishes a means of accessing a UPnP Control Point (associated with the local device), which in turn establishes communications with a local or networked server (as determined by the locator passed to the method) and a local or networked Renderer (implicitly associated with the object associated with the method). Prior to returning a JMF player, the UPnP Control Point must perform the necessary UPnP Connection Manager functions: a) Server - Renderer Negotiations (ConnectionManager::GetProtocolInfo()) Get capabilities Negotiation of delivery protocol Negotiation of content format / options b) Prepare for Connection (ConnectionManager::Prepare for Connection()) Instantiate resources Register QoS (if available) Verify access permissions Get A/V Transport handle from server (push) or renderer (pull) Once the connection has been established, the JMF player will provide an interface to connection manager functions (for connection status), A/V Transport playback control (e.g., fast foward, rewind) and rendering control (e.g., mute, volume). When the player is released, the control point implementation is responsible for closing the connection (ConnectionManager::ConnectionComplete()). Supported JMF player controls will vary widely from renderer to renderer. A simple audio device, for example, may only support the GainControl object and associated methods. More sophisticated A/V renderers may support trick-play (setRate()). A complete list of supported JMF controls supported by a given module are provided player’s getControls() method. F.1.2.2 getSupportedMimeTypes method This method provides an interface for determining what mime types the renderer supports. The mime types supported will be determined using the UPnP Media Renderer’s ConnectionManager::GetProtocolInfo() action. F.1.2.3 isSupportedMimeType method The isSupportedMimeTypes method provides an interface for determining if the associated renderer supports a given mime type. The mime type passed will be compared against supported format types obtained using the UPnP Media Renderer’s ConnectionManager::GetProtocolInfo() action. F.2 Package org.ocap.hn.content F.2.1 AudioResource Interface F.2.1.1 getSampleFrequency method This method maps to the DIDL-Lite, Information Technology - Mutimedia Framework - Part 2: Digital Item Declaration [7], property res@sampleFrequency, which is referenced in the UPnP Content Directory Service [8]. This is the sample frequency in Hertz (Hz). 164 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 F.2.1.2 getNumberOfChannels method This method maps to the DIDL-Lite [7] property res@nrAudioChannels, which is referenced in the UPnP Content Directory Service [8]. This integer refers to the number of audio channels within the resource, such as 1 for monaural, 2 for stereo, or 6 for Dolby surround sound. F.2.1.3 getBitsPerSample method This method maps to the DIDL-Lite [7] property res@bitsPerSample, which is referenced in the UPnP Content Directory Service [8]. This integer refers to the number of bits per sample within the resource. F.2.2 ContentEntry Interface F.2.2.1 getName method UPnP Content Directory Service [8] does not export the file name of a resource. The UPnP ID SHALL be returned by this method. This is the name of the content entry, and is not the title of a piece of content, but rather an identifier of a physical piece of content. F.2.2.2 getContentSize method This method maps to the DIDL-Lite (Information Technology - Mutimedia Framework - Part 2: Digital Item Declaration [7]) property res@size which is referenced in the UPnP ContentDirectory:1 specification [8]. This unsigned long value is the size in bytes of the resource. F.2.2.3 getExtendedFileAccessPermissions method File permissions are defined in the UPnP Content Directory Service [8] using the DIDL-Lite, Information Technology - Mutimedia Framework - Part 2: Digital Item Declaration [7], property object@restricted and the upnp:writeStatus property. F.2.2.4 getLocation method UPnP Content Directory Service [8] does not offer file location, so this string can be created using the identifiers of the content and its parent. F.2.3 Metadata Interface F.2.3.1 actor method This method maps to the UPnP property upnp:actor, which is defined in the UPnP Content Directory Service [8]. This string value is the name of an actor appearing in a video item. F.2.3.2 actor_at_role method This method maps to the UPnP property actor@role, which is defined in the UPnP Content Directory Service [8]. This string value is the role of the actor in the video item. F.2.3.3 album method This method maps to the UPnP property upnp:album, which is defined in the UPnP Content Directory Service [8]. This string value is the title of the album to which the item belongs. F.2.3.4 album_art method This method maps to the UPnP property upnp:albumArtURI, which is defined in the UPnP Content Directory Service [8]. This URI value is a reference to album art. Values must be properly escaped URIs, as described in IETF RFC 2396. CableLabs® 165
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification F.2.3.5 artist method This method maps to the UPnP property upnp:artist, which is defined in the UPnP Content Directory Service [8]. This string value is the name of the artist. F.2.3.6 artist_at_role method This method maps to the UPnP property upnp:artist@role, which is defined in the UPnP Content Directory Service [8]. This string value is the role of an artist in a work. F.2.3.7 artist_discography method This method maps to the UPnP property upnp:artistDiscographyURI, which is defined in the UPnP Content Directory Service [8]. This URI value is a reference to the artist’s discography. Values must be properly escaped URIs, as described in IETF RFC 2396. F.2.3.8 author method This method maps to the UPnP property upnp:author, which is defined in the UPnP Content Directory Service [8]. This string value is the name of an author of a text item. F.2.3.9 author_at_role method This method maps to the UPnP property upnp:author@role, which is defined in the UPnP Content Directory Service [8]. This string value is the role of an author in the work, such as lyrics. F.2.3.10 channel_name method This method maps to the UPnP property upnp:channelName, which is defined in the UPnP Content Directory Service [8]. This string value is used for identification of channels themselves, or information associated with a piece of recorded content. F.2.3.11 channel_number method This method maps to the UPnP property upnp:channelNr, which is defined in the UPnP Content Directory Service [8]. This integer value is used for identification of tuner channels themselves, or information associated with a piece of recorded content. F.2.3.12 comments method This method maps to the UPnP property upnp:userAnnotation, which is defined in the UPnP Content Directory Service [8]. This string value is a general-purpose tag where a user can annotate an object with some user- specific information. F.2.3.13 contributor method This method maps to the Dublin Core property dc:contributor, which is referenced in the UPnP Content Directory Service [8]. It is recommended in the UPnP Content Directory Service specification, that the contributor property include the name of the primary content creator or owner (DublinCore ‘creator’ property). Reference: http://dublincore.org/documents/dces. F.2.3.14 creation_date method This method maps to the Dublin Core property dc:date, which is referenced in the UPnP Content Directory Service [8]. This string identifies the creation date of a piece of content. F.2.3.15 creator method This method maps to the Dublin Core property dc:creator, which is referenced in the UPnP Content Directory Service [8]. The value of this string is the primary content creator or owner of the object. 166 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 F.2.3.16 description method This method maps to the Dublin Core property dc:description, which is referenced in the UPnP Content Directory Service [8]. This string contains a brief description of the content item. Reference: http:// dublincore.org/documents/dces. F.2.3.17 director method This method maps to the UPnP property upnp:director, which is defined in the UPnP Content Directory Service [8]. This string identifies the name of the director of the video content item. F.2.3.18 dvd_region_code method This method maps to the UPnP property upnp:DVDRegionCode, which is defined in the UPnP Content Directory Service [8]. The value of this integer is the region code of the DVD. F.2.3.19 genre method This method maps to the UPnP property upnp:genre, which is defined in the UPnP Content Directory Service [8]. This string identifies the name of the genre to which an object belongs. F.2.3.20 id method This method maps to the DIDL-Lite, Information Technology - Mutimedia Framework - Part 2: Digital Item Declaration [7] property didl-lite:(object)@id, which is referenced in the UPnP Content Directory Service [8]. This string contains an identifier for the object. The value of each object id property must be unique, with respect to the UPnP Content Directory, and the server hosting this content. F.2.3.21 language method This method maps to the Dublin Core property dc:language, which is referenced in the UPnP Content Directory Service [8]. This string identifies the language as defined by IETF RFC 3066. F.2.3.22 long_description method This method maps to the UPnP property upnp:longDescription, which is defined in the UPnP Content Directory Service [8]. This string contains a few lines of description of the content item, and is longer than the Dublin Core description method. F.2.3.23 lyrics_ref method This method maps to the UPnP property upnp:lyricsURI, which is defined in the UPnP Content Directory Service [8]. This URI refers to the lyrics of the song, or the whole album. Values must be properly escaped URIs, as described in IETF RFC 2396. F.2.3.24 media_id method This method maps to the UPnP property upnp:toc, which is defined in the UPnP Content Directory Service [8]. The value of this string is the identifier of an audio CD. F.2.3.25 playlist method This method maps to the UPnP property upnp:playlist, which is defined in the UPnP Content Directory Service [8]. The value of this string is the name of the playlist to which the item belongs. F.2.3.26 producer method This method maps to the UPnP property upnp:producer, which is defined in the UPnP Content Directory Service [8]. The value of this string is the name of the producer, such as the producer of a video or of a CD. CableLabs® 167
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification F.2.3.27 publisher method This method maps to the Dublin Core property dc:publisher, which is referenced in the UPnP Content Directory Service [8]. This string identifies the publisher of the content. Reference: http://dublincore.org/documents/dces. F.2.3.28 radio_band method This method maps to the UPnP property upnp:radioBand, which is defined in the UPnP Content Directory Service [8]. The value of this string is the radio station frequency band. Recommended values are “AM”, “FM”, “Shortwave”, “Internet”, or “Satellite”. F.2.3.29 radio_call_sign method This method maps to the UPnP property upnp:radioCallSign, which is defined in the UPnP Content Directory Service [8]. The value of this string is a radio station call sign, such as “KIFM”. F.2.3.30 radio_station_id method This method maps to the UPnP property upnp:radioStationID, which is defined in the UPnP Content Directory Service [8]. The value of this string is some identification of the broadcast frequency of the radio station, such as “107.7”. F.2.3.31 rating method This method maps to the UPnP property upnp:rating, which is defined in the UPnP Content Directory Service [8]. The value of this string is the rating of the object’s resource, for “parental control” filtering purposes, such as “R”, “PG-13”, and “X”. F.2.3.32 region method This method maps to the UPnP property upnp:region, which is defined in the UPnP Content Directory Service [8]. The value of this string is some identification of the region associated with the source of the object, such as “U.S.”, “Latin America”, or “Seattle”. F.2.3.33 relation method This method maps to the Dublin Core property dc:relation, which is referenced in the UPnP Content Directory Service [8]. This URI property is a reference to related resources. Reference: http://dublincore.org/documents/ dces. Values must be properly escaped URIs as described in IETF RFC 2396. F.2.3.34 rights method This method maps to the Dublin Core property dc:rights, which is referenced in the UPnP Content Directory Service [8]. The value of this string is information about rights held in and over the resource. Reference: http:// dublincore.org/documents/dces. F.2.3.35 scheduled_end_time method This method maps to the UPnP property upnp:scheduledEndTime, which is defined in the UPnP Content Directory Service [8]. The value of this string is date and time, in the “yyyy-mm-ddThh:mm:ss” format defined by ISO 8601, used to indicate the end time of a scheduled program, indented for use by timers. F.2.3.36 scheduled_start_time method This method maps to the UPnP property upnp:scheduledStartTime, which is defined in the UPnP Content Directory Service [8]. The value of this string is date and time, in the “yyyy-mm-ddThh:mm:ss” format defined by ISO 8601, used to indicate the start time of a scheduled program, indented for use by timers. 168 CableLabs®
  • OCAP Home Networking OC-SP-OCAP-HNEXT1.0-I01-050519 F.2.3.37 storage_medium method This method maps to the UPnP property upnp:storageMedium, which is defined in the UPnP Content Directory Service [8]. The value of this string indicates the type of storage medium used for the content. F.2.3.38 title method This method maps to the Dublin Core property dc:title, which is referenced in the UPnP Content Directory Service [8]. The value of this string is the name of the object, such as the title of a song, recording, photograph, or book. F.2.3.39 track method This method maps to the UPnP property upnp:originalTrackNumber, which is defined in the UPnP Content Directory Service [8]. This integer value indicates the original track number on an audio CD or other medium. F.2.4 VideoResource Interface F.2.4.1 getColorDepth method This method maps to the DIDL-Lite, Information Technology - Mutimedia Framework - Part 2: Digital Item Declaration [7], property res@colorDepth, which is referenced in the UPnP Content Directory Service [8]. This unsigned integer value is the encoding characteristic of the resource. F.2.4.2 getResolution method This method maps to the DIDL-Lite, Information Technology - Mutimedia Framework - Part 2: Digital Item Declaration [7], property res@resolution, which is referenced in the UPnP Content Directory Service [8]. This pattern string identifies the XxY resolution of the resource in pixels (typically an image item or video item). String pattern is of the form: [0-9] + x[0-9] + (one or more digits, ‘x’, followed by one or more digits). CableLabs® 169
  • OC-SP-OCAP-HNEXT1.0-I01-050519 OpenCable™ Application Platform Specification 170 CableLabs®