Nextcloud PHP API (master)

IManager
in

API surface for apps interacting with and making use of LanguageModel providers without known which providers are installed

Tags
since
30.0.0
Attributes
#[Consumable]
$since: '30.0.0'

Table of Contents

Methods

cancelTask()  : void
claimNextScheduledTask()  : Task|null
Atomically claim the oldest scheduled task of the given task types and mark it RUNNING.
countTasks()  : int
Get the count of tasks filtered by status and optionally by task type(s)
deleteTask()  : void
Delete a task that has been scheduled before
extractFileIdsFromTask()  : array<int, int>
Extract all input and output file IDs from a task
getAvailableTaskTypeIds()  : array<int, string>
getAvailableTaskTypes()  : array<string, ShapeEnumValue[][]}>
getNextScheduledTask()  : Task
getNextScheduledTasks()  : array<int, Task>
getPreferredProvider()  : IProvider
getProviders()  : array<string|int, IProvider>
getTask()  : Task
getTasks()  : array<int, Task>
getUserTask()  : Task
getUserTasks()  : array<int, Task>
getUserTasksByApp()  : array<int, Task>
hasProviders()  : bool
lockTask()  : bool
Changes the task status to STATUS_RUNNING and, if successful, returns True.
prepareInputData()  : array<string|int, array<int, (numeric)|string|File>|(numeric)|string|File>
Prepare the task's input data, so it can be processed by the provider ie. this replaces file ids with File objects
processTask()  : bool
Process task with a synchronous provider
runTask()  : Task
Run the task and return the finished task
scheduleTask()  : void
setTaskIntermediateOutput()  : bool
Set the task intermediate output.
setTaskProgress()  : bool
setTaskResult()  : void
setTaskStatus()  : void

Methods

cancelTask()

public cancelTask(int $id) : void
Parameters
$id : int

The id of the task

Tags
throws
Exception

If the query failed

NotFoundException

If the task could not be found

since
30.0.0

claimNextScheduledTask()

Atomically claim the oldest scheduled task of the given task types and mark it RUNNING.

public claimNextScheduledTask([array<int, string> $taskTypeIds = [] ]) : Task|null

Unlike getNextScheduledTask (which only fetches) this both selects and locks the task in one step, so concurrent workers never claim the same task. On databases supporting it this uses SELECT ... FOR UPDATE SKIP LOCKED; on SQLite it falls back to a bounded lock-and-retry. The task is only ever transitioned SCHEDULED -> RUNNING; it is never marked FAILED by claiming.

Parameters
$taskTypeIds : array<int, string> = []

When non-empty, only tasks of these task type IDs are considered.

Tags
throws
Exception

If the query failed

since
35.0.0
Return values
Task|null —

The claimed task (status RUNNING), or null if nothing could be claimed.

countTasks()

Get the count of tasks filtered by status and optionally by task type(s)

public countTasks(int $status[, array<int, string> $taskTypeIds = [] ]) : int
Parameters
$status : int

The task status to filter by

$taskTypeIds : array<int, string> = []

Optional list of task type IDs to filter by

Tags
throws
Exception

If the query failed

since
34.0.0
Return values
int —

The count of matching tasks

deleteTask()

Delete a task that has been scheduled before

public deleteTask(Task $task) : void
Parameters
$task : Task

The task to delete

Tags
throws
Exception

if deleting the task in the database failed

since
30.0.0

extractFileIdsFromTask()

Extract all input and output file IDs from a task

public extractFileIdsFromTask(Task $task) : array<int, int>
Parameters
$task : Task
Tags
throws
NotFoundException
since
32.0.0
Return values
array<int, int>

getAvailableTaskTypeIds()

public getAvailableTaskTypeIds([bool $showDisabled = false ][, string|null $userId = null ]) : array<int, string>
Parameters
$showDisabled : bool = false

if false, disabled task types will be filtered out

$userId : string|null = null

to check if the user is a guest. Will be obtained from session if left to default

Tags
since
32.0.0
Return values
array<int, string>

getAvailableTaskTypes()

public getAvailableTaskTypes([bool $showDisabled = false ][, string|null $userId = null ]) : array<string, ShapeEnumValue[][]}>
Parameters
$showDisabled : bool = false

if false, disabled task types will be filtered out

$userId : string|null = null

to check if the user is a guest. Will be obtained from session if left to default

Tags
since
30.0.0
31.0.0

Added the showDisabled argument.

31.0.7

Added the userId argument

33.0.0

Added isInternal to return value

Return values
array<string, ShapeEnumValue[][]}>

getNextScheduledTask()

public getNextScheduledTask([array<int, string> $taskTypeIds = [] ][, array<int, int> $taskIdsToIgnore = [] ]) : Task
Parameters
$taskTypeIds : array<int, string> = []
$taskIdsToIgnore : array<int, int> = []
Tags
throws
Exception

If the query failed

NotFoundException

If no task could not be found

since
30.0.0
Return values
Task

getNextScheduledTasks()

public getNextScheduledTasks([array<int, string> $taskTypeIds = [] ][, array<int, int> $taskIdsToIgnore = [] ][, int $numberOfTasks = 1 ]) : array<int, Task>
Parameters
$taskTypeIds : array<int, string> = []
$taskIdsToIgnore : array<int, int> = []
$numberOfTasks : int = 1
Tags
throws
Exception

If the query failed

since
33.0.0
Return values
array<int, Task>

getTasks()

public getTasks(string|null $userId[, string|null $taskTypeId = null ][, string|null $appId = null ][, string|null $customId = null ][, int|null $status = null ][, int|null $scheduleAfter = null ][, int|null $endedBefore = null ]) : array<int, Task>
Parameters
$userId : string|null

The user id that scheduled the task

$taskTypeId : string|null = null

The task type id to filter by

$appId : string|null = null

The app ID of the app that submitted the task

$customId : string|null = null

The custom task ID

$status : int|null = null

The task status

$scheduleAfter : int|null = null

Minimum schedule time filter

$endedBefore : int|null = null

Maximum ending time filter

Tags
throws
Exception

If the query failed

NotFoundException

If the task could not be found

since
30.0.0
Return values
array<int, Task>

getUserTask()

public getUserTask(int $id, string|null $userId) : Task
Parameters
$id : int

The id of the task

$userId : string|null

The user id that scheduled the task

Tags
throws
Exception

If the query failed

NotFoundException

If the task could not be found

since
30.0.0
Return values
Task

getUserTasks()

public getUserTasks(string|null $userId[, string|null $taskTypeId = null ][, string|null $customId = null ]) : array<int, Task>
Parameters
$userId : string|null

The user id that scheduled the task

$taskTypeId : string|null = null

The task type id to filter by

$customId : string|null = null
Tags
throws
Exception

If the query failed

NotFoundException

If the task could not be found

since
30.0.0
Return values
array<int, Task>

getUserTasksByApp()

public getUserTasksByApp(string|null $userId, string $appId[, string|null $customId = null ]) : array<int, Task>
Parameters
$userId : string|null
$appId : string
$customId : string|null = null
Tags
throws
Exception

If the query failed

JsonException

If parsing the task input and output failed

since
30.0.0
Return values
array<int, Task>

hasProviders()

public hasProviders() : bool
Tags
since
30.0.0
Return values
bool

lockTask()

Changes the task status to STATUS_RUNNING and, if successful, returns True.

public lockTask(Task $task) : bool
Parameters
$task : Task
Tags
since
30.0.0
Return values
bool

prepareInputData()

Prepare the task's input data, so it can be processed by the provider ie. this replaces file ids with File objects

public prepareInputData(Task $task) : array<string|int, array<int, (numeric)|string|File>|(numeric)|string|File>
Parameters
$task : Task
Tags
throws
NotPermittedException
GenericFileException
LockedException
ValidationException
UnauthorizedException
since
30.0.0
Return values
array<string|int, array<int, (numeric)|string|File>|(numeric)|string|File>

processTask()

Process task with a synchronous provider

public processTask(Task $task, ISynchronousProvider $provider) : bool

Prepare task input data and run the process method of the provider This should only be used by OC\TaskProcessing\SynchronousBackgroundJob::run() and OCP\TaskProcessing\IManager::runTask()

Parameters
$task : Task
$provider : ISynchronousProvider
Tags
throws
Exception
since
30.0.0
Return values
bool —

True if the task has run successfully

runTask()

Run the task and return the finished task

public runTask(Task $task) : Task
Parameters
$task : Task

The task to run

Tags
throws
PreConditionNotMetException

If no or not the requested provider was registered but this method was still called

ValidationException

the given task input didn't pass validation against the task type's input shape and/or the providers optional input shape specs

Exception

storing the task in the database failed

UnauthorizedException

the user scheduling the task does not have access to the files used in the input

since
30.0.0
Return values
Task —

The result task

scheduleTask()

public scheduleTask(Task $task) : void
Parameters
$task : Task

The task to run

Tags
throws
PreConditionNotMetException

If no or not the requested provider was registered but this method was still called

ValidationException

the given task input didn't pass validation against the task type's input shape and/or the providers optional input shape specs

Exception

storing the task in the database failed

UnauthorizedException

the user scheduling the task does not have access to the files used in the input

since
30.0.0

setTaskIntermediateOutput()

Set the task intermediate output.

public setTaskIntermediateOutput(int $id, array<string|int, mixed> $output) : bool

If notify_push is available, the output will be pushed to the user and the task will be updated in the DB every 2 seconds at most.

Parameters
$id : int

The id of the task

$output : array<string|int, mixed>

The intermediate output

Tags
throws
Exception

If the query failed

NotFoundException

If the task could not be found

since
35.0.0
Return values
bool —

true if the task should still be running; false if the task has been cancelled in the meantime

setTaskProgress()

public setTaskProgress(int $id, float $progress) : bool
Parameters
$id : int
$progress : float
Tags
throws
ValidationException
Exception
NotFoundException
since
30.0.0
Return values
bool —

true if the task should still be running; false if the task has been cancelled in the meantime

setTaskResult()

public setTaskResult(int $id, string|null $error, array<string|int, mixed>|null $result[, bool $isUsingFileIds = false ][, string|null $userFacingError = null ]) : void
Parameters
$id : int

The id of the task

$error : string|null
$result : array<string|int, mixed>|null
$isUsingFileIds : bool = false
$userFacingError : string|null = null
Tags
throws
Exception

If the query failed

NotFoundException

If the task could not be found

since
30.0.0
33.0.0

Added userFacingError parameter

setTaskStatus()

public setTaskStatus(Task $task, int $status) : void
Parameters
$task : Task
$status : int
Tags
psalm-param

Task::STATUS_* $status

throws
JsonException
Exception
since
30.0.0
On this page

Search results