BackgroundTaskAdd (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

This content has been translated automatically. Click here to view the French version.

Help / WLanguage / WLanguage functions / Mobile specific functions / Background task functions

Operating mode
Handling background tasks
Android specific features
Specific features for iOS

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

BackgroundTaskAdd (Function)

In french: TâcheEnArrièrePlanAjoute

Adds a new background task. This task will be performed periodically when the application is stopped or when it is running in the background.

Example

// Demande le traitement des emails reçus une fois par jour
BackgroundTaskAdd(ProcTraitementEmailEnArrièrePlan, 24*60)

PROCEDURE ProcTraitementEmailEnArrièrePlan()
// Traitement des emails en attente
n is int = TraiteEmailRecus()
IF n > 0 THEN
	// Notifie l'utilisateur 
	notif is Notification
	notif.Title = "Traitement des emails terminés"
	notif.Message = StringBuild("%1 emails ont été traités", n)
	NotifAdd(notif)
END

Syntax

<Result> = BackgroundTaskAdd(<WLanguage procedure> [, <Time interval> [, <Option>]])

<Result>: Integer

ID of the added task,
0 if an error occurs. To get more details on the error, use ErrorInfo.

<WLanguage procedure>: Procedure name

WLanguage procedure ("callback" procedure) called when running the task.
This procedure must be a global procedure of project and it must expect no parameter. Otherwise, a fatal error will occur during the call to BackgroundTaskAdd.

<Time interval>: Optional integer

Minimum time interval (expressed in minutes) between two task executions. Used to guarantee that the task will not be run during this time interval. However, the system can increase the time interval according to several factors (important workload, low battery, etc.). Therefore, the real time interval can change and it can be quite long (several hours).
By default:
the time interval between two task executions is set to 1 hour.
the minimum time interval allowed is set to 15 minutes.
This parameter can correspond to:
an integer corresponding to the number of minutes,
a Duration variable,
the duration in a readable format (e.g., '20min').

<Option>: Optional Integer constant

Type of task to be executed:
processingBackgroundTask The task corresponds to background processing.
Please note: The following conditions must be met for background processing to be carried out:
processing the job may take a few minutes,
the device does not have a low battery,
the energy-saving mode is not active on the device,
in the device settings, the "Refresh in background" option is set to "Yes" and the option is active for the application.* the application has been launched in the previous week (or 2 weeks),
the application is in the list of recent applications (app switcher),
the user is not actively using the device (e.g., loading at night).
refreshBackgroundTask The task is a background refresh task.
Please note: For a refresh task to be executed, the following conditions must be met:
processing the job may take a few seconds,
the device does not have a low battery,
the energy-saving mode is not active on the device,
in the device settings, the "Refresh in background" option is set to "Yes" and the option is active for the application.
the application has been launched and used recently,
the application is in the list of recent applications (app switcher),
CPU and network data budget not exceeded,
the execution number is not exceeded.

Remarks

Operating mode

Once added, the background task is automatically run by the system at regular time interval.

The task is persistent, it will continue to be run periodically when the application is stopped, even when the device is restarted.

If the task is triggered while the application is not started, the application will be run in background (without opening the first project window), the initialization process of project and the declaration process of classes and sets of procedures will be run before calling the procedure associated with the task.

The task will be run when the application is not started or when the application is in background. If the application is displayed in the foreground, its execution will be postponed.

As the task can be run in a secondary thread of the application, the code of the WLanguage procedure must not contain an access to the application's UI or open dialog boxes (via Info, Error, etc.). If the task must interact with the users, you can use notifications (Notifxxx functions).

Handling background tasks

To delete a task added by BackgroundTaskAdd, use BackgroundTaskDelete.
To list the added background tasks, use BackgroundTaskList.
InBackgroundMode is used to find out whether a procedure is run in "background" mode or not.

From the editor, you can specify that a procedure must be run in background task by enabling the corresponding option from the setting window of procedure automation. The task will be automatically added the next time the application is launched: in this case, you don't need to call the function BackgroundTaskAdd.

Android specific features

If the task is to run while the device is in standby mode, it is recommended to ask the user to disable battery optimization for this application with SysBatteryOptimBackground.
Debugging:
For debugging purposes, you can force the execution of a background task via ADB by using the following command line:
adb shell cmd jobscheduler run -f <application> <id>

where:
- <application> corresponds to the application package name as defined in the generation wizard (e.g. com.masociete.monapplication).
- <id> is the identifier of task to run (returned by BackgroundTaskAdd).
Required version:
Background tasks can only be added on devices running Android 5.0 or later (API level 21).
A fatal error occurs if the function is used with an earlier system version.
To determine the version of Android the application is running on, use SysAndroidVersion.
Permissions required:
This function changes the permissions required by the application.
Required permissions:
RECEIVE_BOOT_COMPLETED: enables an application to receive the ACTION_BOOT_COMPLETED which is broadcast when the system has completed booting.
Once run, the task in background continues to operate as long as the application is installed.
The tasks in background are not called in the simulator.

Specific features for iOS

Running time:
The background tasks have a total of 30 seconds to be run. If this timeout is exceeded, the application is directly stopped (this timeout can be reduced according to the system availability). Therefore, the task execution must be as fast as possible.
Practically, the system uses the execution time of task to define the real frequency at which it must be called.
Debugging:
You have the ability to debug the background tasks via Xcode, by triggering them manually via "Debug .. Simulate Background Fetch".
In order for the system to consider that the application can run background tasks, the application must perform network requests (calls to web services, HTTP requests, access to an HFSQL database, GPS, Email, ...). Indeed, iOS checks whether the application exploits data coming from the network.
The application must be able to run background tasks. On the device, in the "Device parameters .. Application name", the option "Refresh in background" must be checked.
When the application is specifically closed by a double press on the Home button and a swipe, the background procedure has less chances to be run.
The procedure will not be called anymore if the devices switches to "energy saving" mode.
The timeout between two procedure executions will be reduced if the device is plugged and connected to a WiFi network.
The frequency at which the application is enabled by the user will impact the call frequency of procedure.
The faster the request execution is, the shorter the time between two executions. In most cases, a long execution time of procedure means that the calls will be spaced out in time. The system gives priority to the procedures that consume less CPU.

Business / UI classification: Business Logic

Component: wd300android.jar