/// <summary>
/// Optimized version of for adding multiple
/// child items and containers at once.
/// <para>
/// This method is somewhat different than <see cref="DvMediaContainer.AddObjects"/>()
/// in that the added branches are assigned a new unique ids from
/// <see cref="MediaBuilder.GetUniqueId"/>(). Such a methodology absolves the
/// application-logic from requiring <see cref="MediaBuilder.PrimeNextId"/>()
/// to prevent object ID collisions. Programmers should be careful when mixing
/// use of <see cref="DvMediaContainer.AddObjects"/>() and
/// AddBranches(), as improper use can still cause ID collisions. As a general rule,
/// application logic that uses <see cref="DvMediaContainer.AddObjects"/>()
/// should always use <see cref="MediaBuilder.PrimeNextId"/>() to prime the
/// media object counter and application logic that always uses AddBranches()
/// need not do this.
/// </para>
/// </summary>
/// <param name="branches">ICollection of items that implement
/// <see cref="IDvMedia"/>
/// </param>
/// <exception cref="Error_PendingDeleteException">
/// Thrown if the item being added is a reference
/// to another item that has been marked for removal.
/// </exception>
/// <exception cref="Error_ObjectIsContainerAndItem">
/// Thrown if an IDvMedia object indicates it is an item
/// as well as a container.
/// </exception>
/// <exception cref="InvalidCastException">
/// Thrown if the branch is not a <see cref="IDvContainer"/> or a <see cref="IDvItem"/>.
/// </exception>
public virtual void AddBranches(ICollection branches)
{
foreach (IUPnPMedia branch in branches)
{
branch.ID = MediaBuilder.GetUniqueId();
}
this.AddObjects(branches, false);
}
/// <summary>
/// Makes it so that a DvMediaItem instantiated from an XmlElement
/// instantiates its child resources as <see cref="DvMediaResource"/> objects.
///
/// <para>
/// Derived classes that expect different types for their resources and child
/// media objects need to override this method.
/// </para>
/// </summary>
/// <param name="xmlElement"></param>
protected override void FinishInitFromXml(XmlElement xmlElement)
{
ArrayList children;
base.UpdateEverything(true, true, typeof(DvMediaResource), typeof(DvMediaItem), typeof(DvMediaContainer), xmlElement, out children);
if (this.m_ID.StartsWith(MediaBuilder.Seed) == false)
{
this.m_ID = MediaBuilder.GetUniqueId();
}
}
/// <summary>
/// Adds an item, container, or a complete content subtree to this container.
/// If the branch is a multiple-item subtree, then the programmer should
/// take care to ensure that the proposed sub-tree is stable by itself.
/// <para>
/// This method is somewhat different than <see cref="DvMediaContainer.AddObject"/>()
/// in that the added branch is assigned a new unique id from
/// <see cref="MediaBuilder.GetUniqueId"/>(). Such a methodology absolves the
/// application-logic from requiring <see cref="MediaBuilder.PrimeNextId"/>()
/// to prevent object ID collisions. Programmers should be careful when mixing
/// use of <see cref="DvMediaContainer.AddObject"/>() and
/// AddBranch(), as improper use can still cause ID collisions. As a general rule,
/// application logic that uses <see cref="DvMediaContainer.AddObject"/>()
/// should always use <see cref="MediaBuilder.PrimeNextId"/>() to prime the
/// media object counter and application logic that always uses AddBranch()
/// need not do this.
/// </para>
/// </summary>
/// <param name="branch">An item, container, or multiple-item subtree.</param>
/// <exception cref="InvalidCastException">
/// Thrown if the branch is not a <see cref="IDvItem"/> or a <see cref="IDvContainer"/>.
/// </exception>
public virtual void AddBranch(IDvMedia branch)
{
branch.ID = MediaBuilder.GetUniqueId();
this.AddObject(branch, false);
}
public DvMediaReference(DvMediaItem underlyingItem)
{
m_uniqueId = MediaBuilder.GetUniqueId();
this.m_Underlying = underlyingItem;
}
/// <summary>
/// This creates a new DvMediaItem instance that refers
/// to this instance. Public programmers should take
/// caution when using this method. It's possible
/// to create an item that exists in a content
/// hierarchy that points to another item that
/// is not in the content hierarchy.
/// </summary>
/// <returns>a new DvMediaItem instance</returns>
public IDvItem CreateReference()
{
string id = MediaBuilder.GetUniqueId();
return(CreateReference(id));
}
