From 5d2554d8ef5e26e54a6950ce5aed03942d364145 Mon Sep 17 00:00:00 2001 From: Marcel Klehr Date: Tue, 21 Jul 2026 10:48:17 +0200 Subject: [PATCH] docs(taskprocessing): Document FileShaped usage Signed-off-by: Marcel Klehr --- .../digging_deeper/task_processing.rst | 35 +++++++++++++++++-- 1 file changed, 32 insertions(+), 3 deletions(-) diff --git a/developer_manual/digging_deeper/task_processing.rst b/developer_manual/digging_deeper/task_processing.rst index e95c8e84467..d265d2dc6f6 100644 --- a/developer_manual/digging_deeper/task_processing.rst +++ b/developer_manual/digging_deeper/task_processing.rst @@ -416,16 +416,45 @@ A **Task processing provider** will usually be a class that implements the inter The method ``getName`` returns a string to identify the registered provider in the user interface. The method ``process`` implements the task processing step. In case execution fails for some reason, you should throw a ``\OCP\TaskProcessing\Exception\ProcessingException`` with an explanatory error message. -Since v33.0.0 you can now also throw an ``OCP\TaskProcessing\Exception\UserFacingProcessingException`` which includes a string parameter to set for error messages that will be propagated to the end-user, make sure to always translate these into the language of the user that requested the task. The rule of thumb of when to use a user-facing error message, is as follows: When the error happened due to a mistake from the user or the user can do something to fix the error, throw a user facing error. However, do make sure to not include implementation or server details in the user facing error message, that's what the normal error message is for; it will only be visible to administrators. -Important to note here is that ``Image``, ``Audio``, ``Video`` and ``File`` slots in the input array will be filled with ``\OCP\Files\File`` objects for your convenience. When outputting one of these you should simply return a string, the API will turn the data into a proper file for convenience. The ``$reportProgress`` parameter is a callback that you may use at will to report the task progress as a single float value between 0 and 1. Its return value will indicate if the task is still running (``true``) or if it was cancelled (``false``) and processing should be terminated. +The ``$reportProgress`` parameter is a callback that you may use at will to report the task progress as a single float value between 0 and 1. Its return value will indicate if the task is still running (``true``) or if it was cancelled (``false``) and processing should be terminated. This class would typically be saved into a file in ``lib/TaskProcessing`` of your app but you are free to put it elsewhere as long as it's loadable by Nextcloud's :ref:`dependency injection container`. +User-facing errors +^^^^^^^^^^^^^^^^^^ + +.. versionadded:: 33.0.0 + +Since v33.0.0 you can now also throw an ``OCP\TaskProcessing\Exception\UserFacingProcessingException`` which includes a string parameter to set for error messages that will be propagated to the end-user, make sure to always translate these into the language of the user that requested the task. The rule of thumb of when to use a user-facing error message, is as follows: When the error happened due to a mistake from the user or the user can do something to fix the error, throw a user facing error. However, do make sure to not include implementation or server details in the user facing error message, that's what the normal error message is for; it will only be visible to administrators. + + +Dealing with file-shaped data +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +TaskProcessing providers often want to operate on files. If your provider takes ``Image``, ``Audio``, ``Video`` and ``File`` slots, these will be passed to the ``process`` method as ``\OCP\Files\File`` objects. + +If your provider provides ``Image``, ``Audio``, ``Video`` and ``File`` slots as output, you can output these as strings that contain the binary data. These will be stored in files, and consumers will receive the corresponding file IDs instead. + +.. versionadded:: 35.0.0 + +Since v35.0.0 we recommend providing file-shaped output (ie. ``Image``, ``Audio``, ``Video`` and ``File`` slots) using the the ``\OCP\TaskProcessing\FileShaped`` class, which also allows specifying a file extension. + +This eases mime-type detection for task processing consumers. + +.. code-block:: php + + public function process( + ?string $userId, array $input, callable $reportProgress + ): array { + // … + return ['output' => new FileShaped(EShapeType::Audio, $binaryOutput, extension: 'ogg')]; + } + .. _task_processing-options: Implementing an advanced TaskProcessing provider ------------------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ``\OCP\TaskProcessing\ISynchronousOptionsAwareProvider`` interface is available if you want your provider to support watermarking or streaming. If your provider implements ``\OCP\TaskProcessing\ISynchronousOptionsAwareProvider``,