using DbAPI.Connections;
using DTS.Common.Interface.Database;
using DTS.Common.Interface.Tags;

namespace DbAPI.Tags
{
    /// <summary>
    /// defines functions to create, retrieve, update, delete tags
    /// </summary>
    public interface ITags
    {
        /// <summary>
        /// inserts a tag assignment record into the database
        /// </summary>
        /// <param name="user">user making request</param>
        /// <param name="connection">connection request is being made on</param>
        /// <param name="tagAssignment">assignment to be committed</param>
        /// <returns>0 (ERROR_SUCCESS) on success, all other values are error codes</returns>
        ulong TagAssignmentsInsert(IUserDbRecord user,
            IConnectionDetails connection,
            ITagAssignment tagAssignment);
        /// <summary>
        /// deletes all matching tags.
        /// </summary>
        /// <param name="user">user making request</param>
        /// <param name="connection">connection request is being made on</param>
        /// <param name="objectId">object tags assigned to</param>
        /// <param name="tagType">the object type</param>
        /// <returns>0 (ERROR_SUCCESS) on success, all other values are error codes</returns>
        ulong TagAssignmentsDelete(IUserDbRecord user,
            IConnectionDetails connection,
            int objectId,
            TagTypes tagType);
        /// <summary>
        /// retrieves all tags that have been assigned to an object type
        /// </summary>
        /// <param name="user">user making request</param>
        /// <param name="connection">connection request is being made on</param>
        /// <param name="tagType">object type tags are assigned to (use null for all)</param>
        /// <param name="tagAssignments">all matching assignments</param>
        /// <returns>0 (ERROR_SUCCESS) on success, all other values are error codes</returns>
        ulong TagAssignmentsGet(IUserDbRecord user,
            IConnectionDetails connection,
            TagTypes? tagType,
            out ITagAssignment[] tagAssignments
            );
        /// <summary>
        /// inserts a new tag, modifies tag with new id after insert
        /// </summary>
        /// <param name="user">user requesting insert</param>
        /// <param name="connection">connection tag is being inserted on</param>
        /// <param name="tag">tag to insert</param>
        /// <returns>0 (ERROR_SUCCESS) on success, all other values are error codes</returns>
        ulong TagsInsert(IUserDbRecord user,
            IConnectionDetails connection,
            ref ITag tag);
        /// <summary>
        /// returns id for a given tag text
        /// </summary>
        /// <param name="user">user making request</param>
        /// <param name="connection">connection request is being made on</param>
        /// <param name="tagText">text associated with tag</param>
        /// <param name="id">id of tag (or null if not found)</param>
        /// <returns>0 on success, all other values are error codes</returns>
        ulong TagsGetId(IUserDbRecord user,
            IConnectionDetails connection,
            string tagText,
            out int? id);
        /// <summary>
        /// deletes all matching tags
        /// </summary>
        /// <param name="tagId">id of tag to be deleted</param>
        /// <param name="connection">connection tag should be deleted on</param>
        /// <param name="user">user requesting delete</param>
        /// <returns>0 (ERROR_SUCCESS) on success, all other values are error codes</returns>
        ulong TagsDelete(IUserDbRecord user,
            IConnectionDetails connection,
            int tagId);

        /// <summary>
        /// retrieves all tags matching search criteria
        /// </summary>
        /// <param name="user">user making request</param>
        /// <param name="connection">connection request is made on</param>
        /// <param name="tagId">id of tag to search for (use null to get all tags)</param>
        /// <param name="records">all matching records</param>
        /// <returns>0 (ERROR_SUCCESS) on success, all other values are error codes</returns>
        ulong TagsGet(IUserDbRecord user,
            IConnectionDetails connection,
            int? tagId,
            out ITag[] records);
    }
}