Merge pull request #176 from joeperpetua/Implement-Task-Scheduler-API

Implement Task Scheduler / Event Scheduler API

README.md

@@ -195,6 +195,9 @@ This wrapper cover the following APIs for now:
 | SYNO.Core.SecurityScan.Status         |
 | SYNO.Core.SecurityScan.Status         |
 | SYNO.Core.User                        |
+| SYNO.Core.User.PasswordExpiry         | 
+| SYNO.Core.User.PasswordPolicy         |
+| SYNO.Core.User.PasswordConfirm        |
 | SYNO.Core.QuickConnect                |
 | SYNO.Core.QuickConnect.Permission     |
 | SYNO.Core.Network.Router.Topology     |
@@ -268,6 +271,13 @@ This wrapper cover the following APIs for now:
 |----------------|
 | SYNO.CloudSync |
 
+| Task Scheduler / Event Scheduler |
+|----------------------------------|
+| SYNO.Core.TaskScheduler          |
+| SYNO.Core.TaskScheduler.Root     |
+| SYNO.Core.EventScheduler         |
+| SYNO.Core.EventScheduler.Root    |
+
 #
 ### Not all Surveillance Station functions works.
 
@@ -525,6 +535,7 @@ DS info with below functions:
 | `users_info()`                    |
 | `password_policy()`               |
 | `password_expiry()`               |
+| `password_confirm()`              |
 | `personal_photo_enable()`         |
 | `ftp_chroot_user()`               |
 | `server_pair()`                   |
@@ -726,6 +737,35 @@ DS info with below functions:
 | `connection_remove()`          | Remove a specific connection.                                  |
 | `task_remove()`                | Remove a specific task.                                        |
 
+### task_scheduler
+| Functions                       | Description                                                    |
+|---------------------------------|----------------------------------------------------------------|
+| `get_output_config()`           | Retrieve the task output configuration.                        |
+| `get_task_list()`               | Retrieve list of Scheduled and Event tasks.                    |
+| `get_task_config()`             | Get Scheduled task settings.                                   |
+| `get_task_results()`            | Get results of a Scheduled task.                               |
+| `set_output_config()`           | Set the task output configuration.                             |
+| `task_set_enable()`             | Enable or disable a Scheduled task.                            |
+| `task_run()`                    | Run a Scheduled task.                                          |
+| `task_delete()`                 | Delete a Scheduled task.                                       |
+| `create_script_task()`          | Create a "User defined script scheduled task".                 |
+| `modify_script_task()`          | Modify a "User defined script scheduled task".                 |
+| `create_beep_control_task()`    | Create a "Beep control scheduled task".                        |
+| `modify_beep_control_task()`    | Modify a "Beep control scheduled task".                        |
+| `create_service_control_task()` | Create a "Service scheduled task".                             |
+| `modify_service_control_task()` | Modify a "Service scheduled task".                             |
+| `create_recycle_bin_task()`     | Create a "Recycle Bin scheduled task".                         |
+| `modify_recycle_bin_task()`     | Modify a "Recycle Bin scheduled task".                         |
+
+### event_scheduler
+| Functions                      | Description                                                    |
+|--------------------------------|----------------------------------------------------------------|
+| `get_task_results()`           | Get results of a Event Triggered task.                         |
+| `get_result_output()`          | Get the output for a given result.                             |
+| `task_set_enable()`            | Enable or disable a Event Triggered task.                      |
+| `task_run()`                   | Run a Event Triggered task.                                    |
+| `task_delete()`                | Delete a Event Triggered task.                                 |
+| `task_create_or_set()`         | Create or modify a Event Triggered task.                       |
 
 #### What's still missing
 

synology_api/auth.py

@@ -9,7 +9,7 @@
 from .exceptions import SynoConnectionError, HTTPError, JSONDecodeError, LoginError, LogoutError, DownloadStationError
 from .exceptions import FileStationError, AudioStationError, ActiveBackupError, VirtualizationError, BackupError
 from .exceptions import CertificateError, CloudSyncError, DHCPServerError, DirectoryServerError, DockerError, DriveAdminError
-from .exceptions import LogCenterError, NoteStationError, OAUTHError, PhotosError, SecurityAdvisorError
+from .exceptions import LogCenterError, NoteStationError, OAUTHError, PhotosError, SecurityAdvisorError, TaskSchedulerError, EventSchedulerError
 from .exceptions import UniversalSearchError, USBCopyError, VPNError, CoreSysInfoError, UndefinedError
 
 USE_EXCEPTIONS: bool = True
@@ -32,6 +32,7 @@ def __init__(self,
         self._port: str = port
         self._username: str = username
         self._password: str = password
+        self._secure: bool = secure
         self._sid: Optional[str] = None
         self._syno_token: Optional[str] = None
         self._session_expire: bool = True
@@ -350,6 +351,12 @@ def request_data(self,
                 # Security advisor error:
                 elif api_name.find('SecurityAdvisor') > -1:
                     raise SecurityAdvisorError(error_code=error_code)
+                # Task Scheduler error:
+                elif api_name.find('SYNO.Core.TaskScheduler') > -1:
+                    raise TaskSchedulerError(error_code=error_code)
+                # Event Scheduler error:
+                elif api_name.find('SYNO.Core.EventScheduler') > -1:
+                    raise EventSchedulerError(error_code=error_code)
                 # Universal search error:
                 elif api_name.find('SYNO.Finder') > -1:
                     raise UniversalSearchError(error_code=error_code)

synology_api/core_sys_info.py

@@ -794,6 +794,38 @@ def password_expiry(self) -> dict[str, object] | str:
         req_param = {'version': info['maxVersion'], 'method': 'get'}
 
         return self.request_data(api_name, api_path, req_param)
+
+    def password_confirm(self, password: str) -> dict[str, object] | str:
+        """Issues a passowrd/session comparison to ensure the given password matches the auth of the current session.
+
+        This is needed by some APIs as a confirmation method, for example, when creating/modifying a scheduled task with root permissions. 
+        Please note that the password will be sent in plain text, just like in the base auth method.
+
+        Args:
+            password (str):
+                The password with which the session was initiated.
+
+        Returns:
+            dict|str:
+                A dictionary containing a `SynoConfirmPWToken`, or an error message.
+
+            Example return:
+            {
+                "data": {
+                    "SynoConfirmPWToken": "xxxxx"
+                },
+                "success": true
+            }
+        """
+        # There is a way to send the password encrypted, but could not figure out how the NAS wants the data to be encrypted.
+        # It wants an AES and RSA key sent to it under the field "__cIpHeRtExT", tried some ways of implementing it, 
+        # but kept getting decryption errors in /var/log/synoscgi.log, so just went through with the plain text password. 
+        api_name = 'SYNO.Core.User.PasswordConfirm'
+        info = self.core_list[api_name]
+        api_path = info['path']
+        req_param = {'version': 2, 'method': 'auth', 'password': password}
+
+        return self.request_data(api_name, api_path, req_param)
 
     def personal_photo_enable(self) -> dict[str, object] | str:
         api_name = 'SYNO.Core.User.Home'