RSDTaskController

public protocol RSDTaskController : AnyObject, NSObjectProtocol

RSDTaskController handles a base-level implementation for running a task. This object is expected to be an appropriate instance of a view controller, depending upon the operating system.

To start a task, create an instance of a view controller that conforms to this protocol and set the task, taskInfo, or taskViewModel.

  • A path object used to track the current state of a running task.

    Declaration

    Swift

    var taskViewModel: RSDTaskViewModel! { get set }

  • Returns a step controller appropriate to the given step. If this method returns nil then the step should be ignored.

    Declaration

    Swift

    func stepController(for step: RSDStep, with parent: RSDPathComponent?) -> RSDStepController?

  • Returns a list of the async action controllers that are currently active. This includes controllers that are requesting permissions, starting, running, and stopping.

    Declaration

    Swift

    var currentAsyncControllers: [RSDAsyncAction] { get }

  • Navigate to the next step from the previous step in the given direction.

    Declaration

    Swift

    func show(_ stepController: RSDStepController, from previousStep: RSDStep?, direction: RSDStepDirection, completion: ((Bool) -> Void)?)

    Parameters

    stepController

    The step controller to show.
    previousStep

    The previous step. This is either the step currently being displayed or else the RSDSectionStep or RSDTaskStep if the previous step was the last step in a paged section or fetched subtask.
    direction

    The direction in which to show the animation change.
    completion

    The completion to call once the navigation animation has completed.

  • Show a loading state while fetching the given task from the task info.

    Declaration

    Swift

    func showLoading(for taskInfo: RSDTaskInfo)

    Parameters

    taskInfo

    The task info for the task being fetched.

  • Fired when the task controller is ready to go forward. This method must invoke the goForward() method either to go forward automatically or else go forward after a user action.

    Declaration

    Swift

    func handleFinishedLoading()

  • Hide the loading state if currently showing it.

    Declaration

    Swift

    func hideLoadingIfNeeded()

  • Failed to fetch the task from the current task path. Handle the error. A retry can be fired by calling goForward().

    Declaration

    Swift

    func handleTaskFailure(with error: Error)

    Parameters

    error

    The error returned by the failed task fetch.

  • The task has completed.

    Declaration

    Swift

    func handleTaskDidFinish(with reason: RSDTaskFinishReason, error: Error?)

    Parameters

    reason

    The reason the task is finished.
    error

    The error, if any, that resulted in stopping the task early.

  • This method is called when a task result is ready for upload, save, archive, etc. This method will be called when either (a) the task is ready to dismiss or (b) when the task is displaying the last completion step.

    Declaration

    Swift

    func handleTaskResultReady(with taskViewModel: RSDTaskViewModel)

    Parameters

    taskViewModel

    The root task view model for this task.

  • Add async action controllers to the shared queue for the given configuations. It is up to the task controller to decide how to create the controllers and how to manage adding them to the currentAsyncControllers array.

    Handling async actions is left to the view controller on Apple devices because this is commonly tied to UI/UX and thread management that the view controller is best suited to determining as appropriate for the given platform.

    The async actions should not be started. Instead they should be returned with idle status.

    The task controller needs to handle blocking any navigation changes until the async actions are ready to proceed; meaning that navigation should be blocked until after required authorizations are checked. Otherwise, the modal popup alert can be swallowed by the step change.

    Note

    If creating the recorder might take time, the task controller should move creation to a background thread so that the main thread is not blocked.

    Declaration

    Swift

    func addAsyncActions(with configurations: [RSDAsyncActionConfiguration], path: RSDPathComponent, completion: @escaping (([RSDAsyncAction]) -> Void))

    Parameters

    configurations

    The configurations to start.
    path

    The path component that is currently being navigated.
    completion

    The completion to call with the instantiated controllers.

  • Request permissions for controllers but do not start the controllers.

    Declaration

    Swift

    func requestPermission(for controllers: [RSDAsyncAction], completion: @escaping (() -> Void))

    Parameters

    controllers

    The controllers for which to request permissions.
    completion

    The completion to call with the instantiated controllers.

  • Start all async actions that are waiting to be started.

    Declaration

    Swift

    func startAsyncActionsIfNeeded()

  • Start the async actions. The protocol extension calls this method when an async action should be started directly after the step is presented.

    Declaration

    Swift

    func startAsyncActions(for controllers: [RSDAsyncAction], showLoading: Bool, completion: @escaping (() -> Void))

  • Stop the async actions. The protocol extension does not directly implement stopping the async actions to allow customization of how the results are added to the task and whether or not forward navigation should be blocked until the completion handler is called. When the stop action is called, the view controller needs to handle stopping the controllers, adding the results, and showing a loading state until ready to move forward in the task navigation.

    Declaration

    Swift

    func stopAsyncActions(for controllers: [RSDAsyncAction], showLoading: Bool, completion: @escaping (() -> Void))
  • taskInfo Extension method

    Convenience method for getting/setting the main entry point for the task controller via the task info.

    Declaration

    Swift

    public var taskInfo: RSDTaskInfo! { get set }
  • task Extension method

    Convenience property for getting/setting the main entry point for the task controller via the task.

    Declaration

    Swift

    public var task: RSDTask! { get set }