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