InvokeRecurrenceRule

Since: BlackBerry 10.3.0

#include <bb/system/InvokeRecurrenceRule>

To link against this class, add the following line to your .pro file: LIBS += -lbbsystem

Encapsulates a recurrence rule, which defines a schedule for triggering a headless application.

The recurrence is invoked by a timer registration. The headless target is invoked on the specified time slot with the action 'bb.action.system.TIMER_FIRED'. At a minimum, a recurrence rule is described by the following 3 parameters:

  • Frequency, which specifies the frequency of repeating events. It has one of values enumerated in InvokeRecurrenceRuleFrequency with default value of InvokeRecurrenceRuleFrequency::None.

  • Interval, which specifies the interval of repetition for the rule (with default value of 1)

  • Start Date/Time, which specifies the date at which the recurrence starts. It defaults to the present date/time (now).

The interval is a positive integer identifying the interval of repetition for the rule. For example, interval equal to 1 means every hour for an InvokeRecurrenceRuleFrequency::Hourly rule. For a InvokeRecurrenceRuleFrequency::Daily rule an interval of 2 means every other day. Additionally, the rule can be further modified by specifying recurrences such as minutes of the hour, hours of the day, days of the month and months of the year. If minutes of the hour, hours of the day, days of the month and months of the year are missing, the missing values are derived from the corresponding values in the start date.

The frequency used to define a recurrence rules may generate recurrence instances with an invalid date (for example, February 30) or nonexistent local time (for example, 1:30 AM on a day where the local time is moved forward by an hour at 1:00 AM). These invalid recurrence instances will be skipped.

Optionally, it can have a date limit or a count limit. A date limit specifies the date at which the recurrence ends. The count limit specifies the number of times the recurrence rule will trigger the headless application.

The following sample code demonstrates how to register a daily recurrent timer that fires at 10AM and 5PM, beginning January 1st, 2014 in local time zone. Note that error handling is omitted for clarity.

    QDate sDate(2014, 1, 1);  // January 1, 2014
    QTime sTime(0, 0);  // Midnight
    InvokeDateTime startTime(sDate,sTime);
    InvokeRecurrenceRule recurrenceRule(bb::system::InvokeRecurrenceRuleFrequency::Daily, startTime);
    QSet<int> setHours;
    setHours << 10 << 17 ;
    recurrenceRule.setHoursOfDay(setHours);

    InvokeTimerRequest timerRequest;
    QString timerId = "1234-unique-id";
    if (recurrenceRule.isValid()) {
      timerRequest.set(timerId,  recurrenceRule, "com.example.RecRuleTestService");
       bb::system::InvokeReply * _reply = _invokeManager->registerTimer(timerRequest);
       if (_reply != NULL) {
           connect(_reply, SIGNAL(finished()), this, SLOT(finishedFired()));
       }
    }

If a recurrence rule defines a schedule that leads to generating time slots that are less than six minutes apart, this rule will be rejected and registration will fail.

It is important to mention that recurrence rules have to be explicitly deregistered. Otherwise, the recurrence rule timer would stay active forever. It means that timerId used for timer registration must be saved by the developer to be used later for deregistering that recurrence rule. It is developer's responsibility to make sure that their application logic executes at some point the following piece of code:
    bb::system::InvokeReply * _reply = _invokeManager->deregisterTimer(timerId);
Note that the deregisterTimer() call is asynchronous. To be notified when it completes, add:
    if (_reply != NULL) {
       connect(_reply, SIGNAL(finished()), this, SLOT(finishedFired()));
     }


Overview

Public Functions Index

InvokeRecurrenceRule ()
InvokeRecurrenceRule (bb::system::InvokeRecurrenceRuleFrequency::Type frequency)
InvokeRecurrenceRule (bb::system::InvokeRecurrenceRuleFrequency::Type frequency, const InvokeDateTime &startTime)
InvokeRecurrenceRule (const InvokeRecurrenceRule &other)
~InvokeRecurrenceRule ()
voidclearLimit ()
intcountLimit () const
bb::system::InvokeDateTimedateLimit () const
QSet< int >daysOfMonth () const
QSet< int >daysOfWeek () const
bb::system::InvokeRecurrenceRuleFrequency::Typefrequency () const
QSet< int >hoursOfDay () const
intinterval () const
boolisValid () const
bb::system::InvokeRecurrenceRuleLimit::TypelimitType () const
QSet< int >minutesOfHour () const
QSet< int >monthsOfYear () const
InvokeRecurrenceRule &operator= (const InvokeRecurrenceRule &other)
voidsetDaysOfMonth (const QSet< int > &daysOfMonth)
voidsetDaysOfWeek (const QSet< int > &daysOfWeek)
voidsetFrequency (bb::system::InvokeRecurrenceRuleFrequency::Type frequency)
voidsetHoursOfDay (const QSet< int > &hours)
voidsetInterval (int interval)
voidsetLimit (const InvokeDateTime &date)
voidsetLimit (int count)
voidsetMinutesOfHour (const QSet< int > &minutes)
voidsetMonthsOfYear (const QSet< int > &monthsOfYear)
voidsetStartTime (const InvokeDateTime &startTime)
bb::system::InvokeDateTimestartTime () const

Public Functions

InvokeRecurrenceRule ()

Creates a new InvokeRecurrenceRule object.

Since:

BlackBerry 10.3.0

InvokeRecurrenceRule (

Creates a new InvokeRecurrenceRule object with the provided frequency.

Start time is set to "Now" of local time zone. Interval is set to 1.

Parameters
frequency

Specifies one of the frequencies from bb::system::InvokeRecurrenceRuleFrequency::Type

Since:

BlackBerry 10.3.0

InvokeRecurrenceRule (

Creates a new InvokeRecurrenceRule object with the provided frequency and start time.

Interval is set to 1.

Parameters
frequency

Specifies one of the frequencies from bb::system::InvokeRecurrenceRuleFrequency::Type

startTime

The InvokeDateTime representing the start time for the rule.

Since:

BlackBerry 10.3.0

InvokeRecurrenceRule (

Creates a copy of an existing InvokeRecurrenceRule object.

Parameters
other

The source InvokeRecurrenceRule object to copy.

Since:

BlackBerry 10.3.0

~InvokeRecurrenceRule ()

Destructor.

Since:

BlackBerry 10.3.0

void clearLimit ()

Clears the limit.

Calling this method resets both count and date limit. As result, the rule repeats indefinitely until it gets unregistered.

Since:

BlackBerry 10.3.0

int countLimit ()

Returns the count limit.

The method returns the count limit that was previously set.

Return:

count limit that was previously set

Since:

BlackBerry 10.3.0

bb::system::InvokeDateTime dateLimit ()

Returns the date limit.

The method returns the date limit that was previously set.

Return:

date limit that was previously set

Since:

BlackBerry 10.3.0

QSet< int > daysOfMonth ()

Returns the daysOfMonth.

The method returns the daysOfMonth that was previously set.

Return:

daysOfMonth that was previously set

Since:

BlackBerry 10.3.0

QSet< int > daysOfWeek ()

Returns the daysOfWeek.

The method returns the daysOfWeek that was previously set.

Return:

daysOfWeek that was previously set

Since:

BlackBerry 10.3.0

bb::system::InvokeRecurrenceRuleFrequency::Type frequency ()

Returns the frequency.

The method returns the frequency that was previously set.

Return:

frequency that was previously set

Since:

BlackBerry 10.3.0

QSet< int > hoursOfDay ()

Returns the hoursOfDay.

The method returns the hoursOfDay that was previously set.

Return:

hoursOfDay that was previously set

Since:

BlackBerry 10.3.0

int interval ()

Returns the interval.

The method returns the interval that was previously set.

Return:

interval that was previously set

Since:

BlackBerry 10.3.0

bool isValid ()

Returns true if this InvokeRecurrenceRule object is valid.

The rule is considered invalid in one of the following is true:
  • frequency is InvokeRecurrenceRuleFrequency::None

  • start date/time is not valid (method startTime().isValid() returns false

  • interval is not a positive number

Return:

true if valid, false otherwise

Since:

BlackBerry 10.3.0

bb::system::InvokeRecurrenceRuleLimit::Type limitType ()

Returns the limit type.

The method returns the limit type that was previously set.

Return:

limit type that was previously set

Since:

BlackBerry 10.3.0

QSet< int > minutesOfHour ()

Returns the minutesOfHour.

The method returns the minutesOfHour that was previously set.

Return:

minutesOfHour that was previously set

Since:

BlackBerry 10.3.0

QSet< int > monthsOfYear ()

Returns the monthsOfYear.

The method returns the monthsOfYear that was previously set.

Return:

monthsOfYear that was previously set

Since:

BlackBerry 10.3.0

InvokeRecurrenceRule & operator= (

Copies the data of an existing InvokeRecurrenceRule object to this object.

Parameters
other

The source InvokeRecurrenceRule object to copy.

Return:

The InvokeRecurrenceRule instance.

Since:

BlackBerry 10.3.0

void setDaysOfMonth (
  • const QSet< int > &daysOfMonth)

Sets the days of the month.

Parameters
daysOfMonth

A list of days within an month when the rule is applied.

Since:

BlackBerry 10.3.0

void setDaysOfWeek (
  • const QSet< int > &daysOfWeek)

Sets the days of the week.

Parameters
daysOfWeek

A list of days within an week when the rule is applied.

Since:

BlackBerry 10.3.0

void setFrequency (

Sets the frequency.

Specifies the frequency of repeating events. The frequency of the event is defined by frequency type and the interval

Parameters
frequency

The frequency from InvokeRecurrenceRuleFrequency

Since:

BlackBerry 10.3.0

void setHoursOfDay (
  • const QSet< int > &hours)

Sets the hours of the day.

Parameters
hours

A list of hours within an day when the rule is applied.

Since:

BlackBerry 10.3.0

void setInterval (
  • intinterval)

Sets the interval.

The interval is a positive integer identifying the interval of repetition for the rule. The default interval is related to the interval type specified by one of the values of as InvokeRecurrenceRuleFrequency.

Parameters
interval

The interval. A negative or 0 value will make the rule invalid, If this method is never called the default interval of "1" will be used for a specific rule.

Since:

BlackBerry 10.3.0

void setLimit (

Sets the date limit of a recurrence rule.

Parameters
date

The date limit as InvokeDateTime. Setting invalid date makes the recurrence rule invalid.

Since:

BlackBerry 10.3.0

void setLimit (
  • intcount)

Sets the count limit of a recurrence rule.

Parameters
count

The count limit to set. A value of zero will reset the limit. A negative value will make the rule invalid, that is, the method InvokeRecurrenceRule.isValid() will return "false"

Since:

BlackBerry 10.3.0

void setMinutesOfHour (
  • const QSet< int > &minutes)

Sets the minutes of the hour.

Parameters
minutes

A list of minutes within an hour when the rule is applied

Since:

BlackBerry 10.3.0

void setMonthsOfYear (
  • const QSet< int > &monthsOfYear)

Sets the months of the year.

Parameters
monthsOfYear

A list of months within an year when the rule is applied.

Since:

BlackBerry 10.3.0

void setStartTime (

Sets the start time of the rule.

Parameters
startTime

The InvokeDateTime representing the start time for the rule.

Since:

BlackBerry 10.3.0

bb::system::InvokeDateTime startTime ()

Returns the assigned start time.

Return:

start time that was previously set

Since:

BlackBerry 10.3.0

Last modified: 2015-01-22



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus