toolkit/components/taskscheduler/nsIWinTaskSchedulerService.idl

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsISupports.idl"
   7
   8 /**
   9  * An interface for Windows Task Scheduler 2.0.
  10  * Documentation for the underlying APIs can be found at
  11  * https://docs.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page
  12  */
  13 [scriptable, main_process_scriptable_only, uuid(a8d36901-0b6a-46c3-a214-a9e1d5d6047a)]
  14 interface nsIWinTaskSchedulerService : nsISupports
  15 {
  16   /**
  17    * Register (create) a task from an XML definition.
  18    * The task will be created so that it only runs as the current user
  19    * (TASK_LOGON_INTERACTIVE_TOKEN).
  20    *
  21    * @throws NS_ERROR_FILE_NOT_FOUND if the folder does not exist.
  22    * @throws NS_ERROR_FILE_ALREADY_EXISTS if the task already existed and aUpdateExisting is false.
  23    *
  24    * @param aFolderName     Full name of the folder in which to create the task, starting with "\".
  25    *
  26    * @param aTaskName       Name of the task.
  27    *
  28    * @param aDefinitionXML  XML definition of the task. This is passed directly to Task Scheduler,
  29    *                        see the schema at
  30    *                        https://docs.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-schema
  31    *
  32    * @param aUpdateExisting Whether to update an existing task with the same name, default false.
  33    */
  34   void registerTask(in wstring aFolderName,
  35                     in wstring aTaskName,
  36                     in wstring aDefinitionXML,
  37                     [optional] in boolean aUpdateExisting);
  38
  39   /**
  40    * Validate the XML task definition with Task Scheduler without creating a task, for testing.
  41    * Doesn't throw if only the final ITaskFolder::RegisterTask() fails.
  42    *
  43    * @param aDefinitionXML      Definition to validate.
  44    * @return                    HRESULT from ITaskFolder::RegisterTask()
  45    *                            Success should be S_OK (0). XML validation failure could be one of
  46    *                            SCHED_E_UNEXPECTED_NODE, SCHED_E_NAMESPACE, SCHED_E_INVALIDVALUE,
  47    *                            SCHED_E_MISSINGNODE, SCHED_E_MALFORMEDXML, but there may be others.
  48    */
  49   long validateTaskDefinition(in wstring aDefinitionXML);
  50
  51   /**
  52    * Get the registration information for a task.
  53    *
  54    * @throws NS_ERROR_FILE_NOT_FOUND if the folder or task do not exist.
  55    *
  56    * @param aFolderName     Full name of the folder containing the task, starting with "\".
  57    * @param aTaskName       Name of the task to read.
  58    * @return                Registration information for the task, as XML text.
  59    */
  60   AString getTaskXML(in wstring aFolderName, in wstring aTaskName);
  61
  62   /**
  63    * Gets the sid of the current user.
  64    *
  65    * @throws NS_ERROR_NOT_IMPLEMENTED If called on a non-Windows OS.
  66    * @throws NS_ERROR_FAILURE         If the user token cannot be found.
  67    * @throws NS_ERROR_ABORT           If converting the sid to a string fails.
  68    *
  69    * @returns                         The sid of the current user.
  70    */
  71   AString getCurrentUserSid();
  72
  73   /**
  74    * Delete a task.
  75    *
  76    * @throws NS_ERROR_FILE_NOT_FOUND if the folder or task do not exist.
  77    *
  78    * @param aFolderName     Full name of the folder containing the task, starting with "\".
  79    * @param aTaskName       Name of the task to delete.
  80    */
  81   void deleteTask(in wstring aFolderName, in wstring aTaskName);
  82
  83   /**
  84    * List the names of all tasks in a task folder.
  85    *
  86    * @throws NS_ERROR_FILE_NOT_FOUND if the folder doesn't exist.
  87    *
  88    * @param aFolderName     The full name of the task folder to enumerate, starting with "\".
  89    *
  90    * @return                An array with the names of the tasks found.
  91    */
  92   Array<AString> getFolderTasks(in wstring aFolderName);
  93
  94   /**
  95    * Create a new task subfolder under a given parent folder.
  96    *
  97    * @throws NS_ERROR_FILE_NOT_FOUND if the parent folder does not exist.
  98    * @throws NS_ERROR_FILE_ALREADY_EXISTS if the subfolder already exists.
  99    *
 100    * @param aParentFolderName       Immediate parent for the new folder, starting with "\".
 101    * @param aSubFolderName          Name of the new folder to create.
 102    */
 103   void createFolder(in wstring aParentFolderName, in wstring aSubFolderName);
 104
 105   /**
 106    * Delete a folder.
 107    *
 108    * @throws NS_ERROR_FILE_NOT_FOUND if the parent folder does not exist.
 109    * @throws NS_ERROR_FILE_DIR_NOT_EMPTY if the folder was not empty.
 110    *
 111    * @param aParentFolderName       Immediate parent of the folder to delete, starting with "\".
 112    * @param aSubFolderName          Name of the folder to delete.
 113    */
 114   void deleteFolder(in wstring aParentFolderName, in wstring aSubFolderName);
 115 };