/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

/**
 * An interface for Windows Task Scheduler 2.0.
 * Documentation for the underlying APIs can be found at
 * https://docs.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page
 */
[scriptable, main_process_scriptable_only, uuid(a8d36901-0b6a-46c3-a214-a9e1d5d6047a)]
interface nsIWinTaskSchedulerService : nsISupports
{
  /**
   * Register (create) a task from an XML definition.
   * The task will be created so that it only runs as the current user
   * (TASK_LOGON_INTERACTIVE_TOKEN).
   *
   * @throws NS_ERROR_FILE_NOT_FOUND if the folder does not exist.
   * @throws NS_ERROR_FILE_ALREADY_EXISTS if the task already existed and aUpdateExisting is false.
   *
   * @param aFolderName     Full name of the folder in which to create the task, starting with "\".
   *
   * @param aTaskName       Name of the task.
   *
   * @param aDefinitionXML  XML definition of the task. This is passed directly to Task Scheduler,
   *                        see the schema at
   *                        https://docs.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-schema
   *
   * @param aUpdateExisting Whether to update an existing task with the same name, default false.
   */
  void registerTask(in wstring aFolderName,
                    in wstring aTaskName,
                    in wstring aDefinitionXML,
                    [optional] in boolean aUpdateExisting);

  /**
   * Validate the XML task definition with Task Scheduler without creating a task, for testing.
   * Doesn't throw if only the final ITaskFolder::RegisterTask() fails.
   *
   * @param aDefinitionXML      Definition to validate.
   * @return                    HRESULT from ITaskFolder::RegisterTask()
   *                            Success should be S_OK (0). XML validation failure could be one of
   *                            SCHED_E_UNEXPECTED_NODE, SCHED_E_NAMESPACE, SCHED_E_INVALIDVALUE,
   *                            SCHED_E_MISSINGNODE, SCHED_E_MALFORMEDXML, but there may be others.
   */
  long validateTaskDefinition(in wstring aDefinitionXML);

  /**
   * Get the registration information for a task.
   *
   * @throws NS_ERROR_FILE_NOT_FOUND if the folder or task do not exist.
   *
   * @param aFolderName     Full name of the folder containing the task, starting with "\".
   * @param aTaskName       Name of the task to read.
   * @return                Registration information for the task, as XML text.
   */
  AString getTaskXML(in wstring aFolderName, in wstring aTaskName);

  /**
   * Delete a task.
   *
   * @throws NS_ERROR_FILE_NOT_FOUND if the folder or task do not exist.
   *
   * @param aFolderName     Full name of the folder containing the task, starting with "\".
   * @param aTaskName       Name of the task to delete.
   */
  void deleteTask(in wstring aFolderName, in wstring aTaskName);

  /**
   * List the names of all tasks in a task folder.
   *
   * @throws NS_ERROR_FILE_NOT_FOUND if the folder doesn't exist.
   *
   * @param aFolderName     The full name of the task folder to enumerate, starting with "\".
   *
   * @return                An array with the names of the tasks found.
   */
  Array<AString> getFolderTasks(in wstring aFolderName);

  /**
   * Create a new task subfolder under a given parent folder.
   *
   * @throws NS_ERROR_FILE_NOT_FOUND if the parent folder does not exist.
   * @throws NS_ERROR_FILE_ALREADY_EXISTS if the subfolder already exists.
   *
   * @param aParentFolderName       Immediate parent for the new folder, starting with "\".
   * @param aSubFolderName          Name of the new folder to create.
   */
  void createFolder(in wstring aParentFolderName, in wstring aSubFolderName);

  /**
   * Delete a folder.
   *
   * @throws NS_ERROR_FILE_NOT_FOUND if the parent folder does not exist.
   * @throws NS_ERROR_FILE_DIR_NOT_EMPTY if the folder was not empty.
   *
   * @param aParentFolderName       Immediate parent of the folder to delete, starting with "\".
   * @param aSubFolderName          Name of the folder to delete.
   */
  void deleteFolder(in wstring aParentFolderName, in wstring aSubFolderName);
};