Merge pull request #15347 from nextcloud/feat/taskprocessing-fileshaped

docs(taskprocessing): Document FileShaped usage

Author: marcelklehr

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<dependency-injection>`.
 
+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``,