navigator_invoke_timer_registration

Send the timer registration reg to service.

Synopsis:

#include <bps/navigator_invoke.h>

BPS_API int navigator_invoke_timer_registration_send(const navigator_invoke_timer_registration_t *reg)

Since:

BlackBerry 10.3.0

Arguments:

reg: The navigator_invoke_timer_registration_t request to send.

Library:

libbps (For the qcc command, use the -l bps option to link against this library)

Description:

This function instructs the timer invocation service to install, update, or uninstall the given timer trigger.

The navigator_invoke_timer_registration_action_t request attribute indicates whether the application intends to register or de-register the trigger. If the trigger timer for the target is already registered, then the new registration replaces the current one. Timer registration is persistent and will survive device reboots. The recurrent timer is not notified in the current time slot if it matches the recurrence rule; it will be notified starting from the next match only. The target is launched through the invoke framework with the action 'bb.action.system.TIMER_FIRED'.

The application should listen for asynchronous responses to the registration request to determine if it was successful. Refer to the navigator_event_get_err() function to retrieve error messages from bps event.

Currently, timer triggers only support headless targets. The following request attributes are required to register a timer trigger:

action (either register or unregister)
non-empty target key
non-empty timer id
type (valid timer trigger type)
valid recurrence rule(for recurrent timer registrations)
valid specific time (for specific time registrations)

Currently, you can register a maximum of 5 timers, of which only 1 can be a recurrent timer. If you attempt to register a specific timer for a time that occurs within 6 minutes of a previously registered timer, the registration will fail.

Specific timers are automatically deregistered when they expire. You can deregister them prior to expiration by calling navigator_invoke_timer_set_action with action() NAVIGATOR_INVOKE_TIMER_ACTION_UNREGISTER. You must deregister recurrence timers.

Returns: