From e5aea1b0162f6928b4fe631a2ac052b5be9ce42b Mon Sep 17 00:00:00 2001 From: Rintaro Kuroiwa Date: Thu, 6 Feb 2014 13:20:36 -0800 Subject: [PATCH] Doxygen doc for MPD generation classes. Change-Id: I8d28d05395732684f8c8fc73a8a40656ffa26a74 --- mpd/base/content_protection_element.h | 2 + mpd/base/mpd_builder.cc | 9 --- mpd/base/mpd_builder.h | 74 ++++++++++++++++-------- mpd/base/mpd_notifier.h | 42 +++++++++----- mpd/base/xml/scoped_xml_ptr.h | 3 + mpd/base/xml/xml_node.h | 81 +++++++++++++++++++-------- 6 files changed, 142 insertions(+), 69 deletions(-) diff --git a/mpd/base/content_protection_element.h b/mpd/base/content_protection_element.h index 121d240902..444e8b7540 100644 --- a/mpd/base/content_protection_element.h +++ b/mpd/base/content_protection_element.h @@ -17,6 +17,8 @@ namespace dash_packager { +/// Structure to represent element in DASH MPD spec (ISO +/// 23009-1:2012 MPD and Segment Formats). struct ContentProtectionElement { ContentProtectionElement(); ~ContentProtectionElement(); diff --git a/mpd/base/mpd_builder.cc b/mpd/base/mpd_builder.cc index 80b1e9078a..f5377b74ed 100644 --- a/mpd/base/mpd_builder.cc +++ b/mpd/base/mpd_builder.cc @@ -105,15 +105,6 @@ AdaptationSet* MpdBuilder::AddAdaptationSet() { return adaptation_set.release(); } -bool MpdBuilder::WriteMpd() { - base::AutoLock scoped_lock(lock_); - std::string mpd; - bool result = ToStringImpl(&mpd); - - // NOTE: Write to file, after interface change. - return result; -} - bool MpdBuilder::ToString(std::string* output) { base::AutoLock scoped_lock(lock_); return ToStringImpl(output); diff --git a/mpd/base/mpd_builder.h b/mpd/base/mpd_builder.h index 0e97fa50dd..8a3389b70a 100644 --- a/mpd/base/mpd_builder.h +++ b/mpd/base/mpd_builder.h @@ -7,7 +7,6 @@ // This file contains the MpdBuilder, AdaptationSet, and Representation class // declarations. // http://goo.gl/UrsSlF - #ifndef MPD_BASE_MPD_BUILDER_H_ #define MPD_BASE_MPD_BUILDER_H_ @@ -34,6 +33,7 @@ class XmlNode; } // namespace xml +/// This class generates DASH MPDs (Media Presentation Descriptions). class MpdBuilder { public: enum MpdType { @@ -41,16 +41,23 @@ class MpdBuilder { kDynamic }; + /// Constructs MpdBuilder. + /// @param type indicates whether the MPD should be for VOD or live content + /// (kStatic for VOD profile, or kDynamic for live profile). explicit MpdBuilder(MpdType type); ~MpdBuilder(); + /// Add entry to the MPD. + /// @param base_url URL for entry. void AddBaseUrl(const std::string& base_url); - // The returned pointer is owned by this object. + /// Adds to the MPD. + /// @return The new adaptation set, which is owned by this instance. AdaptationSet* AddAdaptationSet(); - // This will write to stdout until File interface is defined. - bool WriteMpd(); + /// Writes the MPD to the given string. + /// @param[out] output is an output string where the MPD gets written. + /// @return true on success, false otherwise. bool ToString(std::string* output); private: @@ -79,23 +86,35 @@ class MpdBuilder { DISALLOW_COPY_AND_ASSIGN(MpdBuilder); }; +/// AdaptationSet class provides methods to add Representations and +/// elements to the AdaptationSet element. class AdaptationSet { public: + /// @param adaptation_set_id is an ID number for this AdaptationSet. + /// @param representation_counter is a Counter for assigning ID numbers to + /// Representation. It can not be NULL. AdaptationSet(uint32 adaptation_set_id, base::AtomicSequenceNumber* representation_counter); ~AdaptationSet(); - // The returned pointer is owned by this object. + /// Create a Representation instance using @a media_info. + /// @param media_info is a MediaInfo object used to initialize the returned + /// Representation instance. + /// @return On success, returns a pointer to Representation. Otherwise returns + /// NULL. The returned pointer is owned by the AdaptationSet instance. Representation* AddRepresentation(const MediaInfo& media_info); - // If |element| has {value, schemeIdUri} set and has - // {“value”, “schemeIdUri”} as key for additional_attributes, - // then the former is used. + /// Add a ContenProtection element to the adaptation set. + /// @param element contains the ContentProtection element contents. + /// If @a element has {value, schemeIdUri} set and has + /// {“value”, “schemeIdUri”} as key for @a additional_attributes, + /// then the former is used. void AddContentProtectionElement(const ContentProtectionElement& element); - // Makes a copy of AdaptationSet xml element with its child elements, which - // are Representation elements. On success this returns non-NULL ScopedXmlPtr, - // otherwise returns NULL ScopedXmlPtr. + /// Makes a copy of AdaptationSet xml element with its child Representation + /// and ContentProtection elements. + /// @return On success returns a non-NULL ScopedXmlPtr. Otherwise returns a + /// NULL ScopedXmlPtr. xml::ScopedXmlPtr::type GetXml(); // Must be unique in the Period. @@ -117,35 +136,46 @@ class AdaptationSet { DISALLOW_COPY_AND_ASSIGN(AdaptationSet); }; -// In |media_info|, ContentProtectionXml::{schemeIdUri,value} takes precedence -// over schemeIdUri and value specified in ContentProtectionXml::attributes. +/// Representation class contains references to a single media stream, as +/// well as optional ContentProtection elements for that stream. class Representation { public: + /// @param media_info is a MediaInfo containing information on the media. + /// @param representation_id is the numeric ID for the . Representation(const MediaInfo& media_info, uint32 representation_id); ~Representation(); + /// Tries to initialize the instance. If this does not succeed, the instance + /// should not be used. + /// @return true on success, false otherwise. bool Init(); - // If |element| has {value, schemeIdUri} set and has - // {“value”, “schemeIdUri”} as key for additional_attributes, - // then the former is used. + /// Add a ContenProtection element to the representation. + /// @param element contains the ContentProtection element contents. + /// If @a element has {value, schemeIdUri} set and has + /// {“value”, “schemeIdUri”} as key for @a additional_attributes, + /// then the former is used. void AddContentProtectionElement(const ContentProtectionElement& element); + /// Add a media segment to the representation. + /// @param start_time is the start time for the segment, in units of the + /// stream's time scale. + /// @param duration is the duration of the segment, in units of the stream's + /// time scale. + /// @return true on success, false otherwise. bool AddNewSegment(uint64 start_time, uint64 duration); - // Makes a copy of the current XML. Note that this is a copy. The caller is - // responsible for cleaning up the allocated resource. + /// @return Copy of . xml::ScopedXmlPtr::type GetXml(); - // Must be unique amongst other Representations in the MPD file. - // As the MPD spec says. + /// @return ID number for . uint32 id() const { return id_; } private: - // Returns whether |media_info_| has required fields to generate a valid - // Representation. Returns true on success, otherwise returns false. + // Returns true if |media_info_| has required fields to generate a valid + // Representation. Otherwise returns false. bool HasRequiredMediaInfoFields(); // Note: Because 'mimeType' is a required field for a valid MPD, these return diff --git a/mpd/base/mpd_notifier.h b/mpd/base/mpd_notifier.h index 35158564d2..2483433b2a 100644 --- a/mpd/base/mpd_notifier.h +++ b/mpd/base/mpd_notifier.h @@ -18,34 +18,48 @@ namespace dash_packager { class ContentProtectionElement; class MediaInfo; +/// Interface for publish/subscribe publisher class which notifies MpdBuilder +/// of media-related events. class MpdNotifier { public: MpdNotifier() {}; virtual ~MpdNotifier() {}; - // Initializes the notifier. For example, if this notifier uses a network for - // notification, then this would setup connection with the remote host. + /// Initializes the notifier. For example, if this notifier uses a network for + /// notification, then this would set up the connection with the remote host. + /// @return true on success, false otherwise. virtual bool Init() = 0; - // Notifies the MpdBuilder that there is a new container along with - // |media_info|. Live may have multiple "files" but those should be notified - // via NotifyNewSegment(). - // On success this populates |container_id| for the container and returns true, - // otherwise returns false. + /// Notifies the MpdBuilder that there is a new container along with + /// @a media_info. Live may have multiple files (segments) but those should be + /// notified via NotifyNewSegment(). + /// @param media_info is the MediaInfo that will be passed to MpdBuilder. + /// @param[out] container_id is the numeric ID of the container, possibly for + /// NotifyNewSegment() and AddContentProtectionElement(). Only + /// populated on success. + /// @return true on success, false otherwise. virtual bool NotifyNewContainer(const MediaInfo& media_info, uint32* container_id) = 0; - // Only for Live. Notifies MpdBuilder that there is a new segment ready that - // starts from |start_time| for |duration|. - // |container_id| must be an ID number populated by calling - // NotifyNewContainer(). + /// Notifies MpdBuilder that there is a new segment ready. Used only for live + /// profile. + /// @param container_id Container ID obtained from calling + /// NotifyNewContainer(). + /// @param start_time is the start time of the new segment, in units of the + /// stream's time scale. + /// @param duration is the duration of the new segment, in units of the + /// stream's time scale.. + /// @return true on success, false otherwise. virtual bool NotifyNewSegment(uint32 container_id, uint64 start_time, uint64 duration) = 0; - // Adds content protection information to the MPD. - // |container_id| must be an ID number populated by calling - // NotifyNewContainer(). + /// Adds content protection information to the MPD. + /// @param container_id is the nummeric container ID obtained from calling + /// NotifyNewContainer(). + /// @param content_protection_element New ContentProtection element + /// specification. + /// @return true on success, false otherwise. virtual bool AddContentProtectionElement( uint32 container_id, const ContentProtectionElement& content_protection_element) = 0; diff --git a/mpd/base/xml/scoped_xml_ptr.h b/mpd/base/xml/scoped_xml_ptr.h index cf10a5af23..9589580629 100644 --- a/mpd/base/xml/scoped_xml_ptr.h +++ b/mpd/base/xml/scoped_xml_ptr.h @@ -17,6 +17,8 @@ namespace dash_packager { namespace xml { +/// Deleter functor for deleting libxml2 pointers. This is used with +/// ScopedXmlPtr. struct XmlDeleter { // Called by scoped_ptr. http://goo.gl/YaLbcS inline void operator()(xmlSchemaParserCtxtPtr ptr) const { @@ -33,6 +35,7 @@ struct XmlDeleter { // C++11 allows template alias but standards before it do not. This struct is // for aliasing scoped_ptr with libxml2 object deleter. +/// scoped_ptr for libxml2 resources. template struct ScopedXmlPtr { typedef scoped_ptr type; diff --git a/mpd/base/xml/xml_node.h b/mpd/base/xml/xml_node.h index 04ab8fb765..755839588e 100644 --- a/mpd/base/xml/xml_node.h +++ b/mpd/base/xml/xml_node.h @@ -21,40 +21,59 @@ namespace dash_packager { namespace xml { -// These classes are wrapper classes for XML elements for generating MPD. -// None of the pointer parameters should be NULL. None of the methods are meant -// to be overridden. +/// These classes are wrapper classes for XML elements for generating MPD. +/// None of the pointer parameters should be NULL. None of the methods are meant +/// to be overridden. class XmlNode { public: - // Makes an XML element with |name|. |name| should not be NULL. + /// Make an XML element. + /// @param name is the name of the element, which should not be NULL. explicit XmlNode(const char* name); virtual ~XmlNode(); - // The ownership transfers to this object. On failure, this method will - // destruct |child|. + /// Add a child element to this element. + /// @param child is a xmlNode to add as a child for this element. Ownership + /// of the child node is transferred. + /// @return true on success, false otherwise. bool AddChild(ScopedXmlPtr::type child); + /// Set a string attribute. + /// @param attribute_name The name (lhs) of the attribute. + /// @param attribute The value (rhs) of the attribute. void SetStringAttribute(const char* attribute_name, const std::string& attribute); + /// Sets an interger attribute. + /// @param attribute_name The name (lhs) of the attribute. + /// @param number The value (rhs) of the attribute. void SetIntegerAttribute(const char* attribute_name, uint64 number); + + /// Set a floating point number attribute. + /// @param attribute_name is the name of the attribute to set. + /// @param number is the value (rhs) of the attribute. void SetFloatingPointAttribute(const char* attribute_name, double number); + /// Sets 'id=@a id' attribute. + /// @param id is the ID for this element. void SetId(uint32 id); - // This is like 'innerHTML' setter. - // This function does not work well with AddChild(). Use either AddChild() or - // SetContent() when setting the content of this node. + /// Set the contents of an XML element using a string. + /// Note: This function does not work well with AddChild(). Use either + /// AddChild() or SetContent() when setting the content of this node. + /// @param content is a string containing the text-encoded child elements to + /// be added to the element. void SetContent(const std::string& content); - // Ownership transfer. After calling this method, calling any methods of - // this object, except the destructor, is undefined. + /// Transfer the ownership of the xmlNodePtr. After calling this method, the + /// behavior of any methods, except the destructor, is undefined. + /// @return The resource of this object. ScopedXmlPtr::type PassScopedPtr(); - // Release the xmlNodePtr of this object. After calling this method, calling - // any methods of this object, except the destructor, is undefined. + /// Release the xmlNodePtr of this object. After calling this method, the + /// behavior of any methods, except the destructor, is undefined. xmlNodePtr Release(); + /// @return Raw pointer to the element. xmlNodePtr GetRawPtr(); private: @@ -63,17 +82,19 @@ class XmlNode { DISALLOW_COPY_AND_ASSIGN(XmlNode); }; -// This corresponds to RepresentationBaseType in MPD. RepresentationBaseType is -// not a concrete element type so this should not get instantiated on its own. -// AdaptationSet and Representation are subtypes of this. +/// This corresponds to RepresentationBaseType in MPD. RepresentationBaseType is +/// not a concrete element type so this should not get instantiated on its own. +/// AdaptationSet and Representation are subtypes of this. class RepresentationBaseXmlNode : public XmlNode { public: virtual ~RepresentationBaseXmlNode(); bool AddContentProtectionElements( const std::list& content_protection_elements); - // Return true on success. If content_protections size is 0 in |media_info|, - // this will return true. Otherwise return false. + /// Add a ContentProtection elements to this element. + /// @param media_info is a MediaInfo containing the ContentProtection + /// elements to add. + /// @return true on success, false otherwise. bool AddContentProtectionElementsFromMediaInfo(const MediaInfo& media_info); protected: @@ -86,7 +107,7 @@ class RepresentationBaseXmlNode : public XmlNode { DISALLOW_COPY_AND_ASSIGN(RepresentationBaseXmlNode); }; -// AdaptationSetType in MPD. +/// AdaptationSetType specified in MPD. class AdaptationSetXmlNode : public RepresentationBaseXmlNode { public: AdaptationSetXmlNode(); @@ -96,7 +117,7 @@ class AdaptationSetXmlNode : public RepresentationBaseXmlNode { DISALLOW_COPY_AND_ASSIGN(AdaptationSetXmlNode); }; -// RepresentationType in MPD. +/// RepresentationType in MPD. class RepresentationXmlNode : public RepresentationBaseXmlNode { public: typedef ::google::protobuf::RepeatedPtrField @@ -108,17 +129,29 @@ class RepresentationXmlNode : public RepresentationBaseXmlNode { RepresentationXmlNode(); virtual ~RepresentationXmlNode(); - // Returns true if successfully set attributes and children elements (if - // applicable). repeated info of size 0 is valid input. + /// Adds video metadata to the MPD. + /// @param repeated_video_info constains the VideoInfos for Representation. + /// Input of size 0 is valid. + /// @return true if successfully set attributes and children elements (if + /// applicable), false otherwise. bool AddVideoInfo(const RepeatedVideoInfo& repeated_video_info); + + /// Adds audio metadata to the MPD. + /// @param repeated_audio_info constains the AudioInfos for Representation. + /// Input of size 0 is valid. + /// @return true if successfully set attributes and children elements (if + /// applicable), false otherwise. bool AddAudioInfo(const RepeatedAudioInfo& repeated_audio_info); - // Check MediaInfo protobuf definition for which fields are specific to VOD. + /// Adds fields that are specific to VOD. This ignores @a media_info fields for + /// Live. + /// @param media_info is a MediaInfo with VOD information. + /// @return true on success, false otherwise. bool AddVODOnlyInfo(const MediaInfo& media_info); private: // Add AudioChannelConfiguration elements. This will add multiple - // AudioChannelConfiguration if |repeated_audio_info| contains multiple + // AudioChannelConfiguration if @a repeated_audio_info contains multiple // distinct channel configs (e.g. 2 channels and 6 channels adds 2 elements). bool AddAudioChannelInfo(const RepeatedAudioInfo& repeated_audio_info);