using System.Collections.Generic;

namespace Toolbox.Docking.Api.Control
{
    /// <summary>
    /// ITbWorkTask provides workflow control as well as 
    /// access to Toolbox services. 
    /// </summary>
    public interface ITbWorkTask : ITbInitTask
    {
        #region options 
        /// <summary>
        /// Specifies whether the work task operates with or without accounting of StereoMode.
        /// </summary>
        bool StereoMode { get; }

        /// <summary>
        /// Specifies whether the task would use external calculator cache.
        /// </summary>
        bool UseCalculatorExternalCache { get; }

        #endregion

        #region resources
        /// <summary>
        /// Provides access to the Toolbox calculation service.
        /// </summary>
        ITbCalcService CalcService { get; }

        #region Define structure

        /// <summary>
        /// Creates a canonized Toolbox structure from a SMILES of a possibly unknown origin or SMILES dialect. 
        /// </summary>
        /// <param name="nonCanonicSmiles">
        /// External SMILES. 
        /// </param>
        /// <param name="problem">Empty string in case of successfully recognized SMILES, otherwise contains the identified problem</param>
        /// <returns>
        /// Constructed <see cref="Chemical"/> object that can be used within the Toolbox workflow.
        /// </returns>
        Chemical.Chemical CreateChemical(string nonCanonicSmiles, out string problem);


        /// <summary>
        /// Creates a canonized Toolbox structure from a SMILES of a possibly unknown origin or SMILES dialect. 
        /// </summary>
        /// <param name="cas">The CAS number for the <see cref="Chemical"/>.</param>
        /// <param name="nonCanonicSmiles">External SMILES.</param>
        /// <param name="names">The names for the <see cref="Chemical"/>.</param>
        /// <param name="problem">Empty string in case of successfully recognized SMILES, otherwise contains the identified problem</param>
        /// <returns>
        /// Constructed <see cref="Chemical"/> object that can be used within the Toolbox workflow. 
        /// </returns>
        Chemical.Chemical CreateChemical(int cas, string nonCanonicSmiles, IEnumerable<string> names, out string problem);
        #endregion


        /// <summary>
        /// The chemical set as target for Toolbox workflow.
        /// </summary>
        Chemical.Chemical TargetChemical{ get; }

        #endregion

        #region Control

        /// <summary>
        /// When IsTimeOut is true the Token.IsCancellationRequested is also true.
        /// Use this only when need to distinguish cancellation and cancellation due to time out. 
        /// </summary>
        bool IsTimeOut { get; }


        /// <summary>
        /// Creates a sub-task. Tasks should be broken down in smaller tasks in order to better 
        /// inform the user how a task progresses.
        /// </summary>
        /// <param name="subTaskCaption">The caption for the sub-task.</param>
        /// <param name="subTaskMaxProgress">The number of items for the task.</param>
        /// <param name="meaningfulProgress">Specify whether this will be a meaningful progress or an infinite progress.</param>
        /// <returns>
        /// The resulting work sub-task.
        /// </returns>
        ITbWorkTask CreateSubWorkTask(string subTaskCaption, int subTaskMaxProgress, bool meaningfulProgress);

        #endregion
    }
}