/* * nsVanadielAlarm.idl * * Copyright (c) 2005 by Daniel Potter. All rights reserved. * * This file is part of the Vana'diel Clock. * * The Vana'diel Clock is free software; you can redistribute * it and/or modify it under the terms of the GNU General Public License * as published by the Free Software Foundation; either version 2 of the * License, or (at your option) any later version. * * The Vana'diel Clock is distributed in the hope that it will * be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with the Vana'diel Clock; if not, write to the * Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307 USA * * Describes the XPCOM interfaces for using alarms. */ #include "nsISupports.idl" #include "nsIRDFDataSource.idl" #include "nsIRDFResource.idl" [scriptable, uuid(e8513bde-bad9-4172-a67f-8de617a55a57)] interface nsIVanadielAlarm : nsISupports { /** * The next time the alarm should be activated. This is most useful * if preAlertTime is set to something above 0. */ readonly attribute PRUint64 nextAlarm; /** * The unique ID of the alarm, generated when it was created * based on the creation time and an internal counter. */ readonly attribute string id; /** * True if this alarm still can sound, false if it has no pattern * and it's already sounded. */ readonly attribute boolean active; /** * The pattern for the alarm. The pattern works very similar to the * way a crontab works (funny that). It's a field of numbers in the * following format: * * [moonphase] [rseweek] * * The number is specified as a comma separated list of numbers * or as a range, like 1-4. If every instance should be used, * then "*" is used. * * [moonphase] and [rseweek] are optional and may be left out. * * If the pattern is set to an empty string, then the alarm only * sounds once. * * Setting the pattern will not update the alarm. You need to use * updateAlarm to do that. */ attribute string pattern; /** * A user-set name. */ attribute string name; /** * A user-set description. */ attribute string description; /** * The time the alarm should go off at, in Vana'diel seconds. */ attribute PRUint64 time; /** * The time before the alarm actually goes off to sound a pre-alert. * This is in Vana'diel seconds! */ attribute PRUint64 preAlertTime; /** * The URL to the icon for this alarm, should be a 32x32 image. */ attribute string icon; /** * The URL to the small icon for this alarm, should be a 16x16 image. */ attribute string smallIcon; /** * The actual URL to the icon for this alarm, if icon is set * to "time:moon" or "time:day". */ readonly attribute string nextIcon; /** * The actual URL to the small icon for this alarm, if smallIcon is set * to "time:moon" or "time:day". */ readonly attribute string nextSmallIcon; /** * The URL to a sound to play when the alarm goes off, or "beep" if * it should use window.beep() */ attribute string sound; /** * The type of alarm, used only for editting it. */ attribute string type; /** * Gets the latest debug message generated, if debug messages are * enabled. */ readonly attribute string debugMessage; /** * Notifies the alarm that it has been activated, and that the current * time is now the given time. This may move the activated alarm * forward far enough that the alarm is no longer active. */ void activate( in PRUint64 time ); /** * Sets the alarm, using a pattern. This is most useful if you want * to set a one-off alarm that should go off at a given time based on * the pattern you set. */ void setAlarm( in PRUint64 time, in string pattern ); /** * Updates the alarm to the given time. If a pattern is set, the * alarm will go off at the next time after the pattern. */ void updateAlarm( in PRUint64 time ); /** * Binds this alarm to the given RDF resource, loading any existing * information from the RDF and updating it when information changes. * * This may alter the existing ID. * * If no information exists in the RDF, then it will be added. * * If this alarm was already bound to an RDF node, it will become * "unbound" from that node. */ void bindToRDF( in nsIRDFDataSource rdfSource, in nsIRDFResource rdfResource ); /** * Unbinds from the RDF as specified in bindToRDF, or does nothing * if already removed from any RDF source. */ void unbindFromRDF( ); }; [scriptable, uuid(e8513bde-bad9-4172-a67f-8de617a55a58)] interface nsIVanadielAlarmManagerListener : nsISupports { /** * Indicates that a new alarm has been added to the available alarms. */ void alarmAdded( in nsIVanadielAlarm alarm ); /** * Indicates that an existing alarm has been removed from the available alarms. */ void alarmRemoved( in nsIVanadielAlarm alarm ); /** * Indicates that an existing alarm has sounded. */ void alarmFired( in nsIVanadielAlarm alarm ); /** * Indicates that one for more alarms have fired and have been updated. */ void alarmsAltered( ); }; [scriptable, uuid(e8513bde-bad9-4172-a67f-8de617a55a56)] interface nsIVanadielAlarmManager : nsISupports { /** * Count of the number of alarms currently being managed. */ readonly attribute PRUint32 count; /** * URI to the RDF datasource used to store alarms. */ readonly attribute string rdfURI; /** * Gets the alarm at a given index, or null if there is no alarm * at that index. */ nsIVanadielAlarm getAlarmAt( in PRUint32 index ); /** * Gets a given alarm that contains the id, or null if there is * no alarm with that ID. */ nsIVanadielAlarm getAlarmById( in string id ); /** * Adds an alarm, notifying any listeners. */ void addAlarm( in nsIVanadielAlarm alarm ); /** * Removes an alarm if it exists, notifying listeners only if the * alarm was already in this manager. */ void removeAlarm( in nsIVanadielAlarm alarm ); /** * Loads the alarms from the default datasource, if necessary. * If the alarms have already been loaded, then nothing happens. */ void loadAlarms( ); /** * Flushs the alarm data to disk. */ void flushAlarms( ); /** * Activate all alarms which should have been activated at this time. * This will be called automatically by nsIVanadielTimer once it * has been started. * @param time the time in Vana'diel seconds * @param late true if the timer had missed this alarm because the * browser was offline */ void activateAlarms( in PRUint64 time, in boolean late ); /** * Displays an alarm, as if it had gone off now. Useful for testing * the alarm dialog. */ void showAlarmDialog( in nsIVanadielAlarm alarm ); /** * Alerts all listeners that some alarm, somewhere, has been altered. */ void fireAlarmAltered( ); /** * Adds a listener to listen to new alarms being added and existing * alarms being removed. */ void addVanadielAlarmManagerListener( in nsIVanadielAlarmManagerListener listener ); /** * Removes a listener to listen to new alarms being added and existing * alarms being removed. */ void removeVanadielAlarmManagerListener( in nsIVanadielAlarmManagerListener listener ); };