1 /********************************************************************\ 2 * This program is free software; you can redistribute it and/or * 3 * modify it under the terms of the GNU General Public License as * 4 * published by the Free Software Foundation; either version 2 of * 5 * the License, or (at your option) any later version. * 6 * * 7 * This program is distributed in the hope that it will be useful, * 8 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 10 * GNU General Public License for more details. * 11 * * 12 * You should have received a copy of the GNU General Public License* 13 * along with this program; if not, contact: * 14 * * 15 * Free Software Foundation Voice: +1-617-542-5942 * 16 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 17 * Boston, MA 02110-1301, USA gnu@gnu.org * 18 * * 19 \********************************************************************/ 20 /** 21 * @addtogroup Engine 22 * @{ */ 23 /** 24 @addtogroup SchedXaction Scheduled/Periodic/Recurring Transactions 25 26 Scheduled Transactions provide a framework for remembering 27 information about a transactions that are set to occur in the 28 future, either once or periodically. 29 @{ */ 30 /** 31 * @file SchedXaction.h 32 * @brief Scheduled Transactions public handling routines. 33 * @author Copyright (C) 2001 Joshua Sled <jsled@asynchronous.org> 34 */ 35 36 #ifndef XACC_SCHEDXACTION_H 37 #define XACC_SCHEDXACTION_H 38 39 typedef struct _SchedXactionClass SchedXactionClass; 40 41 #include <time.h> 42 #include <glib.h> 43 #include "qof.h" 44 #include "Recurrence.h" 45 #include "gnc-engine.h" 46 47 /* --- type macros --- */ 48 #define GNC_TYPE_SCHEDXACTION (gnc_schedxaction_get_type ()) 49 #define GNC_SCHEDXACTION(o) \ 50 (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_SCHEDXACTION, SchedXaction)) 51 #define GNC_SCHEDXACTION_CLASS(k) \ 52 (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_SCHEDXACTION, SchedXactionClass)) 53 #define GNC_IS_SCHEDXACTION(o) \ 54 (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_SCHEDXACTION)) 55 #define GNC_IS_SCHEDXACTION_CLASS(k) \ 56 (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_SCHEDXACTION)) 57 #define GNC_SCHEDXACTION_GET_CLASS(o) \ 58 (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_SCHEDXACTION, SchedXactionClass)) 59 GType gnc_schedxaction_get_type(void); 60 61 #define GNC_IS_SX(obj) GNC_IS_SCHEDXACTION(obj) 62 #define GNC_SX(obj) GNC_SCHEDXACTION(obj) 63 64 typedef struct _SchedXaction SchedXaction; 65 66 /** 67 * A single scheduled transaction. 68 * 69 * Scheduled transactions have a list of transactions, and a frequency 70 * [and associated date anchors] with which they are scheduled. 71 * 72 * Things that make sense to have in a template transaction: 73 * [not] Date [though eventually some/multiple template transactions 74 * might have relative dates]. 75 * Memo 76 * Account 77 * Funds In/Out... or an expr involving 'amt' [A, x, y, a?] for 78 * variable expenses. 79 * 80 * Template transactions are instantiated by: 81 * . copying the fields of the template 82 * . setting the date to the calculated "due" date. 83 * 84 * We should be able to use the GeneralJournal [or, yet-another-subtype 85 * of the internal ledger] for this editing. 86 **/ 87 struct _SchedXaction 88 { 89 QofInstance inst; 90 gchar *name; 91 92 GList *schedule; 93 94 GDate last_date; 95 96 GDate start_date; 97 /* if end_date is invalid, then no end. */ 98 GDate end_date; 99 100 /* if num_occurances_total == 0, then no limit */ 101 gint num_occurances_total; 102 /* remaining occurrences are as-of the 'last_date'. */ 103 gint num_occurances_remain; 104 105 /* the current instance-count of the SX. */ 106 gint instance_num; 107 108 gboolean enabled; 109 gboolean autoCreateOption; 110 gboolean autoCreateNotify; 111 gint advanceCreateDays; 112 gint advanceRemindDays; 113 114 Account *template_acct; 115 116 /** The list of deferred SX instances. This list is of SXTmpStateData 117 * instances. */ 118 GList /* <SXTmpStateData*> */ *deferredList; 119 }; 120 121 struct _SchedXactionClass 122 { 123 QofInstanceClass parent_class; 124 }; 125 126 /** Just the variable temporal bits from the SX structure. */ 127 typedef struct _SXTmpStateData 128 { 129 GDate last_date; 130 gint num_occur_rem; 131 gint num_inst; 132 } SXTmpStateData; 133 134 #define xaccSchedXactionSetGUID(X,G) qof_instance_set_guid(QOF_INSTANCE(X),(G)) 135 136 /** 137 * Creates and initializes a scheduled transaction. 138 */ 139 SchedXaction *xaccSchedXactionMalloc(QofBook *book); 140 141 void sx_set_template_account (SchedXaction *sx, Account *account); 142 143 /** 144 * Cleans up and frees a SchedXaction and its associated data. 145 */ 146 void xaccSchedXactionDestroy( SchedXaction *sx ); 147 148 void gnc_sx_begin_edit (SchedXaction *sx); 149 void gnc_sx_commit_edit (SchedXaction *sx); 150 151 /** @return GList<Recurrence*> **/ 152 /*@ dependent @*/ 153 GList* gnc_sx_get_schedule(const SchedXaction *sx); 154 /** @param[in] schedule A GList<Recurrence*> **/ 155 void gnc_sx_set_schedule(SchedXaction *sx, /*@ null @*//*@ only @*/ GList *schedule); 156 157 gchar *xaccSchedXactionGetName( const SchedXaction *sx ); 158 /** 159 * A copy of the name is made. 160 */ 161 void xaccSchedXactionSetName( SchedXaction *sx, const gchar *newName ); 162 163 const GDate* xaccSchedXactionGetStartDate(const SchedXaction *sx ); 164 time64 xaccSchedXactionGetStartDateTT(const SchedXaction *sx ); 165 void xaccSchedXactionSetStartDate( SchedXaction *sx, const GDate* newStart ); 166 void xaccSchedXactionSetStartDateTT( SchedXaction *sx, const time64 newStart ); 167 168 int xaccSchedXactionHasEndDate( const SchedXaction *sx ); 169 /** 170 * Returns invalid date when there is no end-date specified. 171 */ 172 const GDate* xaccSchedXactionGetEndDate(const SchedXaction *sx ); 173 /** 174 * Set to an invalid GDate to turn off 'end-date' definition. 175 */ 176 void xaccSchedXactionSetEndDate( SchedXaction *sx, const GDate* newEnd ); 177 178 const GDate* xaccSchedXactionGetLastOccurDate(const SchedXaction *sx ); 179 time64 xaccSchedXactionGetLastOccurDateTT(const SchedXaction *sx ); 180 void xaccSchedXactionSetLastOccurDate( SchedXaction *sx, const GDate* newLastOccur ); 181 void xaccSchedXactionSetLastOccurDateTT( SchedXaction *sx, const time64 newLastOccur ); 182 183 /** 184 * Returns true if the scheduled transaction has a defined number of 185 * occurrences, false if not. 186 */ 187 gboolean xaccSchedXactionHasOccurDef( const SchedXaction *sx ); 188 gint xaccSchedXactionGetNumOccur( const SchedXaction *sx ); 189 /** 190 * Set to '0' to turn off number-of-occurrences definition. 191 */ 192 void xaccSchedXactionSetNumOccur( SchedXaction *sx, gint numNum ); 193 gint xaccSchedXactionGetRemOccur( const SchedXaction *sx ); 194 void xaccSchedXactionSetRemOccur( SchedXaction *sx, gint numRemain ); 195 196 /** Calculates and returns the number of occurrences of the given SX 197 * in the given date range (inclusive). */ 198 gint gnc_sx_get_num_occur_daterange(const SchedXaction *sx, const GDate* start_date, const GDate* end_date); 199 200 /** \brief Get the instance count. 201 * 202 * This is incremented by one for every created 203 * instance of the SX. Returns the instance num of the SX unless stateData 204 * is non-null, in which case it returns the instance num from the state 205 * data. 206 * @param sx The instance whose state should be retrieved. 207 * @param stateData may be NULL. 208 */ 209 gint gnc_sx_get_instance_count( const SchedXaction *sx, /*@ null @*/ SXTmpStateData *stateData ); 210 /** 211 * Sets the instance count to something other than the default. As the 212 * default is the incorrect value '0', callers should DTRT here. 213 */ 214 void gnc_sx_set_instance_count( SchedXaction *sx, gint instanceNum ); 215 216 GList *xaccSchedXactionGetSplits( const SchedXaction *sx ); 217 void xaccSchedXactionSetSplits( SchedXaction *sx, GList *newSplits ); 218 219 gboolean xaccSchedXactionGetEnabled( const SchedXaction *sx ); 220 void xaccSchedXactionSetEnabled( SchedXaction *sx, gboolean newEnabled ); 221 222 void xaccSchedXactionGetAutoCreate( const SchedXaction *sx, 223 /*@ out @*/ gboolean *outAutoCreate, 224 /*@ out @*/ gboolean *outNotify ); 225 void xaccSchedXactionSetAutoCreate( SchedXaction *sx, 226 gboolean newAutoCreate, 227 gboolean newNotify ); 228 229 gint xaccSchedXactionGetAdvanceCreation( const SchedXaction *sx ); 230 void xaccSchedXactionSetAdvanceCreation( SchedXaction *sx, gint createDays ); 231 232 gint xaccSchedXactionGetAdvanceReminder( const SchedXaction *sx ); 233 void xaccSchedXactionSetAdvanceReminder( SchedXaction *sx, gint reminderDays ); 234 235 /** \name Temporal state data. 236 * 237 * These functions allow us to opaquely save the entire temporal state of 238 * ScheduledTransactions. This is used by the "since-last-run" dialog to 239 * store the initial state of SXes before modification ... if it later 240 * becomes necessary to revert an entire set of changes, we can 'revert' the 241 * SX without having to rollback all the individual state changes. 242 @{ 243 */ 244 /** Allocates a new SXTmpStateData object and fills it with the 245 * current state of the given sx. 246 */ 247 SXTmpStateData *gnc_sx_create_temporal_state(const SchedXaction *sx ); 248 249 /** Calculates the next occurrence of the given SX and stores that 250 * occurrence in the remporalStateDate. The SX is unchanged. */ 251 void gnc_sx_incr_temporal_state(const SchedXaction *sx, SXTmpStateData *stateData ); 252 253 /** Frees the given stateDate object. */ 254 void gnc_sx_destroy_temporal_state( SXTmpStateData *stateData ); 255 256 /** \brief Allocates and returns a one-by-one copy of the given 257 * temporal state. 258 * 259 * The caller must destroy the returned object with 260 * gnc_sx_destroy_temporal_state() after usage. 261 */ 262 SXTmpStateData *gnc_sx_clone_temporal_state( SXTmpStateData *stateData ); 263 /** @} */ 264 265 /** \brief Returns the next occurrence of a scheduled transaction. 266 * 267 * If the transaction hasn't occurred, then it's based off the start date. 268 * Otherwise, it's based off the last-occurrence date. 269 * 270 * If state data is NULL, the current value of the SX is used for 271 * computation. Otherwise, the values in the state data are used. This 272 * allows the caller to correctly create a set of instances into the future 273 * for possible action without modifying the SX state until action is 274 * actually taken. 275 */ 276 GDate xaccSchedXactionGetNextInstance(const SchedXaction *sx, 277 SXTmpStateData *stateData); 278 279 /** \brief Set the schedxaction's template transaction. 280 281 t_t_list is a glist of TTInfo's as defined in SX-ttinfo.h. 282 The edit dialog doesn't use this mechanism; maybe it should. 283 */ 284 void xaccSchedXactionSetTemplateTrans( SchedXaction *sx, 285 GList *t_t_list, 286 QofBook *book ); 287 288 /** \brief Adds an instance to the deferred list of the SX. 289 290 Added instances are added in date-sorted order. 291 */ 292 void gnc_sx_add_defer_instance( SchedXaction *sx, void *deferStateData ); 293 294 /** \brief Removes an instance from the deferred list. 295 296 If the instance is no longer useful; gnc_sx_destroy_temporal_state() it. 297 */ 298 void gnc_sx_remove_defer_instance( SchedXaction *sx, void *deferStateData ); 299 300 /** \brief Returns the defer list from the SX. 301 302 This is a date-sorted state-data instance list. 303 The list should not be modified by the caller; use the 304 gnc_sx_{add,remove}_defer_instance() functions to modify the list. 305 */ 306 GList *gnc_sx_get_defer_instances( SchedXaction *sx ); 307 308 /* #defines for Properties and GncModule */ 309 #define GNC_SX_SHARES "shares" 310 #define GNC_SX_FREQ_SPEC "scheduled-frequency" 311 #define GNC_SX_NAME "sched-xname" 312 #define GNC_SX_START_DATE "sched-start-date" 313 #define GNC_SX_LAST_DATE "sched-last-date" 314 #define GNC_SX_NUM_OCCUR "sx-total-number" 315 #define GNC_SX_REM_OCCUR "sx-remaining-num" 316 317 /** \brief QOF registration. */ 318 gboolean SXRegister (void); 319 320 /** \deprecated */ 321 #define xaccSchedXactionIsDirty(X) qof_instance_is_dirty (QOF_INSTANCE(X)) 322 /** \deprecated */ 323 #define xaccSchedXactionGetGUID(X) qof_entity_get_guid(QOF_INSTANCE(X)) 324 325 #endif /* XACC_SCHEDXACTION_H */ 326 327 /** @} */ 328 /** @} */ 329