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.
bb::system::InvokeReply * _reply = _invokeManager->deregisterTimer(timerId);
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 () | |
void | clearLimit () |
int | countLimit () const |
bb::system::InvokeDateTime | dateLimit () const |
QSet< int > | daysOfMonth () const |
QSet< int > | daysOfWeek () const |
bb::system::InvokeRecurrenceRuleFrequency::Type | frequency () const |
QSet< int > | hoursOfDay () const |
int | interval () const |
bool | isValid () const |
bb::system::InvokeRecurrenceRuleLimit::Type | limitType () const |
QSet< int > | minutesOfHour () const |
QSet< int > | monthsOfYear () const |
InvokeRecurrenceRule & | operator= (const InvokeRecurrenceRule &other) |
void | setDaysOfMonth (const QSet< int > &daysOfMonth) |
void | setDaysOfWeek (const QSet< int > &daysOfWeek) |
void | setFrequency (bb::system::InvokeRecurrenceRuleFrequency::Type frequency) |
void | setHoursOfDay (const QSet< int > &hours) |
void | setInterval (int interval) |
void | setLimit (const InvokeDateTime &date) |
void | setLimit (int count) |
void | setMinutesOfHour (const QSet< int > &minutes) |
void | setMonthsOfYear (const QSet< int > &monthsOfYear) |
void | setStartTime (const InvokeDateTime &startTime) |
bb::system::InvokeDateTime | startTime () const |
Public Functions
Creates a new InvokeRecurrenceRule object.
BlackBerry 10.3.0
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 |
BlackBerry 10.3.0
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. |
BlackBerry 10.3.0
Creates a copy of an existing InvokeRecurrenceRule object.
Parameters | |
---|---|
other |
The source InvokeRecurrenceRule object to copy. |
BlackBerry 10.3.0
Destructor.
BlackBerry 10.3.0
void
Clears the limit.
Calling this method resets both count and date limit. As result, the rule repeats indefinitely until it gets unregistered.
BlackBerry 10.3.0
int
Returns the count limit.
The method returns the count limit that was previously set.
count limit that was previously set
BlackBerry 10.3.0
bb::system::InvokeDateTime
Returns the date limit.
The method returns the date limit that was previously set.
date limit that was previously set
BlackBerry 10.3.0
QSet< int >
Returns the daysOfMonth.
The method returns the daysOfMonth that was previously set.
daysOfMonth that was previously set
BlackBerry 10.3.0
QSet< int >
Returns the daysOfWeek.
The method returns the daysOfWeek that was previously set.
daysOfWeek that was previously set
BlackBerry 10.3.0
bb::system::InvokeRecurrenceRuleFrequency::Type
Returns the frequency.
The method returns the frequency that was previously set.
frequency that was previously set
BlackBerry 10.3.0
QSet< int >
Returns the hoursOfDay.
The method returns the hoursOfDay that was previously set.
hoursOfDay that was previously set
BlackBerry 10.3.0
int
Returns the interval.
The method returns the interval that was previously set.
interval that was previously set
BlackBerry 10.3.0
bool
Returns true if this InvokeRecurrenceRule object is valid.
frequency is InvokeRecurrenceRuleFrequency::None
start date/time is not valid (method startTime().isValid() returns false
interval is not a positive number
true if valid, false otherwise
BlackBerry 10.3.0
bb::system::InvokeRecurrenceRuleLimit::Type
Returns the limit type.
The method returns the limit type that was previously set.
limit type that was previously set
BlackBerry 10.3.0
QSet< int >
Returns the minutesOfHour.
The method returns the minutesOfHour that was previously set.
minutesOfHour that was previously set
BlackBerry 10.3.0
QSet< int >
Returns the monthsOfYear.
The method returns the monthsOfYear that was previously set.
monthsOfYear that was previously set
BlackBerry 10.3.0
InvokeRecurrenceRule &
Copies the data of an existing InvokeRecurrenceRule object to this object.
Parameters | |
---|---|
other |
The source InvokeRecurrenceRule object to copy. |
The InvokeRecurrenceRule instance.
BlackBerry 10.3.0
void
Sets the days of the month.
Parameters | |
---|---|
daysOfMonth |
A list of days within an month when the rule is applied. |
BlackBerry 10.3.0
void
Sets the days of the week.
Parameters | |
---|---|
daysOfWeek |
A list of days within an week when the rule is applied. |
BlackBerry 10.3.0
void
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 |
BlackBerry 10.3.0
void
Sets the hours of the day.
Parameters | |
---|---|
hours |
A list of hours within an day when the rule is applied. |
BlackBerry 10.3.0
void
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. |
BlackBerry 10.3.0
void
Sets the date limit of a recurrence rule.
Parameters | |
---|---|
date |
The date limit as InvokeDateTime. Setting invalid date makes the recurrence rule invalid. |
BlackBerry 10.3.0
void
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" |
BlackBerry 10.3.0
void
Sets the minutes of the hour.
Parameters | |
---|---|
minutes |
A list of minutes within an hour when the rule is applied |
BlackBerry 10.3.0
void
Sets the months of the year.
Parameters | |
---|---|
monthsOfYear |
A list of months within an year when the rule is applied. |
BlackBerry 10.3.0
void
Sets the start time of the rule.
Parameters | |
---|---|
startTime |
The InvokeDateTime representing the start time for the rule. |
BlackBerry 10.3.0
bb::system::InvokeDateTime
Returns the assigned start time.
start time that was previously set
BlackBerry 10.3.0