root/lang/csharp/iTunesCOMWrap/trunk/iTunesCOMWrap/Interfaces/ISources.cs @ 11175

namespace Clovery.iTunesHelper.COMWrap.Interfaces
{
    /// <summary>
    /// Represents an entry in the Source list (music library, CD, device, etc.).
    /// </summary>
    public interface ISource : IITObject
    {
        /// <summary>
        /// Returns the kind of the source.
        /// </summary>
        SourceKind Kind { get; }

        /// <summary>
        /// Returns the total size of the source, if it has a fixed size.
        /// </summary>
        double Capacity { get; }

        /// <summary>
        /// Returns the free space on the source, if it has a fixed size.
        /// </summary>
        double FreeSpace { get; }

        /// <summary>
        /// Returns a collection containing the playlists in this source. 
        /// </summary>
        /// <remarks>
        /// The source's primary playlist is always the first playlist in the collection.
        /// </remarks>
        IPlaylistCollection Playlists { get; }

        /// <summary>
        /// Returns a collection containing some children of this source.
        /// </summary>
        IChildPlaylistCollection Children { get; }

        /// <summary>
        /// Create a folder in an existing source.
        /// </summary>
        /// <param name="folderName">The name of the new folder (may be NULL or empty).</param>
        /// <returns>Returns a created folder</returns>
        IPlaylist CreateFolder(string folderName);

        /// <summary>
        /// Create a playlist in an existing source.
        /// </summary>
        /// <param name="playlistName">The name of the new playlist (may be NULL or empty).</param>
        /// <returns>Returns a created playlist</returns>
        IPlaylist CreatePlaylist(string playlistName);

        /// <summary>
        /// Return a playlist if the playlist existing with specified name,
        /// otherwise create playlist with specified name.
        /// </summary>
        /// <param name="playlistName">The name of the new playlist (may be NULL or empty).</param>
        /// <returns>Returns a created playlist</returns>
        IPlaylist GetOrCreatePlaylist(string playlistName);

        /// <summary>
        /// Return a folder if the folder existing with specified name,
        /// otherwise create folder with specified name.
        /// </summary>
        /// <param name="folderName">The name of the new folder (may be NULL or empty).</param>
        /// <returns>Returns a created folder</returns>
        IPlaylist GetOrCreateFolder(string folderName);
    }

    public interface IIPodSource : ISource
    {
        void EjectIPod();
        string SoftwareVersion { get; }
        void UpdateIPod();
    }

    public interface ISourceCollection : INamedCollection<ISource> { }
}