1 /********************************************************************\ 2 * gncOwner.h -- Business Interface: Object OWNERs * 3 * * 4 * This program is free software; you can redistribute it and/or * 5 * modify it under the terms of the GNU General Public License as * 6 * published by the Free Software Foundation; either version 2 of * 7 * the License, or (at your option) any later version. * 8 * * 9 * This program is distributed in the hope that it will be useful, * 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 12 * GNU General Public License for more details. * 13 * * 14 * You should have received a copy of the GNU General Public License* 15 * along with this program; if not, contact: * 16 * * 17 * Free Software Foundation Voice: +1-617-542-5942 * 18 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 19 * Boston, MA 02110-1301, USA gnu@gnu.org * 20 * * 21 \********************************************************************/ 22 /** @addtogroup Business 23 @{ */ 24 /** @addtogroup Owner 25 @{ */ 26 /** @file gncOwner.h 27 @brief Business Interface: Object OWNERs 28 @author Copyright (C) 2001,2002 Derek Atkins <warlord@MIT.EDU> 29 @author Copyright (c) 2005 Neil Williams <linux@codehelp.co.uk> 30 @author Copyright (c) 2006 David Hampton <hampton@employees.org> 31 */ 32 33 #ifndef GNC_OWNER_H_ 34 #define GNC_OWNER_H_ 35 36 typedef struct _gncOwner GncOwner; 37 38 #define GNC_ID_OWNER "gncOwner" 39 40 typedef enum 41 { 42 GNC_OWNER_NONE , 43 GNC_OWNER_UNDEFINED , 44 GNC_OWNER_CUSTOMER , 45 GNC_OWNER_JOB , 46 GNC_OWNER_VENDOR , 47 GNC_OWNER_EMPLOYEE , 48 } GncOwnerType; 49 50 #include "qof.h" 51 #include "gncCustomer.h" 52 #include "gncJob.h" 53 #include "gncVendor.h" 54 #include "gncEmployee.h" 55 #include "gncInvoice.h" 56 #include "Account.h" 57 #include "gnc-lot.h" 58 59 /** \name QOF handling 60 61 Whilst GncOwner is not a formal QOF object, these functions 62 are still expected to be useful in making GncOwner transparent 63 to QOF as they can be used by objects like GncInvoice. 64 @{ 65 */ 66 /** return the type for the collection. */ 67 QofIdTypeConst qofOwnerGetType(const GncOwner *owner); 68 /** return the type for the owner as an untranslated string. */ 69 const char * gncOwnerGetTypeString (const GncOwner *owner); 70 /** return the owner itself as an entity. */ 71 QofInstance* qofOwnerGetOwner (const GncOwner *owner); 72 /** set the owner from the entity. */ 73 void qofOwnerSetEntity (GncOwner *owner, QofInstance *ent); 74 /** Check if entity is an owner kind. This function conveniently 75 * imitates the various GNC_IS_ checks on the other gnucash 76 * objects even though an owner is not really a true object. */ 77 gboolean GNC_IS_OWNER (QofInstance *ent); 78 79 /** Returns the QofIdType of the given GncOwnerType, or NULL if no 80 * suitable one exists. */ 81 QofIdTypeConst gncOwnerTypeToQofIdType(GncOwnerType t); 82 83 gboolean 84 gncOwnerRegister(void); 85 86 /** @} */ 87 88 #ifndef SWIG 89 90 /** \struct GncOwner */ 91 struct _gncOwner 92 { 93 GncOwnerType type; /**< Customer, Job, Vendor, Employee or Undefined. */ 94 union 95 { 96 gpointer undefined; 97 GncCustomer * customer; 98 GncJob * job; 99 GncVendor * vendor; 100 GncEmployee * employee; 101 } owner; /**< holds the pointer to the owner object. */ 102 gpointer qof_temp; /**< Set type independently of the owner. */ 103 }; 104 105 #endif /* SWIG */ 106 107 /** \name Setup routines 108 @{ 109 */ 110 void gncOwnerInitUndefined (GncOwner *owner, gpointer obj); 111 void gncOwnerInitCustomer (GncOwner *owner, GncCustomer *customer); 112 void gncOwnerInitJob (GncOwner *owner, GncJob *job); 113 void gncOwnerInitVendor (GncOwner *owner, GncVendor *vendor); 114 void gncOwnerInitEmployee (GncOwner *owner, GncEmployee *employee); 115 /** @} */ 116 /** \name Get routines. 117 @{ 118 */ 119 /** Returns the GncOwnerType of this owner. (Not to be confused with qofOwnerGetType().) */ 120 GncOwnerType gncOwnerGetType (const GncOwner *owner); 121 /** Returns TRUE if the given owner is one of the valid objects. 122 * Returns FALSE if the owner is (still) undefined, or if it is NULL. */ 123 gboolean gncOwnerIsValid (const GncOwner *owner); 124 125 /** If the given owner is of type GNC_OWNER_UNDEFINED, returns the undefined 126 * pointer, which is usually NULL. Otherwise returns NULL. */ 127 gpointer gncOwnerGetUndefined (const GncOwner *owner); 128 /** If the given owner is of type GNC_OWNER_CUSTOMER, returns the pointer 129 * to the customer object. Otherwise returns NULL. */ 130 GncCustomer * gncOwnerGetCustomer (const GncOwner *owner); 131 /** If the given owner is of type GNC_OWNER_JOB, returns the pointer 132 * to the job object. Otherwise returns NULL. */ 133 GncJob * gncOwnerGetJob (const GncOwner *owner); 134 /** If the given owner is of type GNC_OWNER_VENDOR, returns the pointer 135 * to the vendor object. Otherwise returns NULL. */ 136 GncVendor * gncOwnerGetVendor (const GncOwner *owner); 137 /** If the given owner is of type GNC_OWNER_EMPLOYEE, returns the pointer 138 * to the employee object. Otherwise returns NULL. */ 139 GncEmployee * gncOwnerGetEmployee (const GncOwner *owner); 140 141 const char * gncOwnerGetID (const GncOwner *owner); 142 const char * gncOwnerGetName (const GncOwner *owner); 143 GncAddress * gncOwnerGetAddr (const GncOwner *owner); 144 gboolean gncOwnerGetActive (const GncOwner *owner); 145 gnc_commodity * gncOwnerGetCurrency (const GncOwner *owner); 146 /** @} */ 147 148 /** \name Set routines. 149 @{ 150 */ 151 void gncOwnerSetActive (const GncOwner *owner, gboolean active); 152 /** @} */ 153 154 void gncOwnerCopy (const GncOwner *src, GncOwner *dest); 155 156 /** \name Comparison routines. 157 @{ 158 */ 159 /** Assess equality by checking 160 * - if both owner objects refer to the same owner type 161 * - and if the owner reference points to the same 162 * {vendor/customer/employee} in memory */ 163 gboolean gncOwnerEqual (const GncOwner *a, const GncOwner *b); 164 /** Same as gncOwnerEqual, but returns 0 if 165 equal to be used as a GList custom compare function */ 166 int gncOwnerGCompareFunc (const GncOwner *a, const GncOwner *b); 167 /** Sort on name */ 168 int gncOwnerCompare (const GncOwner *a, const GncOwner *b); 169 /** @} */ 170 171 /** Get the GncGUID of the immediate owner */ 172 const GncGUID * gncOwnerGetGUID (const GncOwner *owner); 173 GncGUID gncOwnerRetGUID (GncOwner *owner); 174 175 /** 176 * Get the "parent" Owner or GncGUID thereof. The "parent" owner 177 * is the Customer or Vendor, or the Owner of a Job 178 */ 179 const GncOwner * gncOwnerGetEndOwner (const GncOwner *owner); 180 const GncGUID * gncOwnerGetEndGUID (const GncOwner *owner); 181 182 /** Attach an owner to a lot */ 183 void gncOwnerAttachToLot (const GncOwner *owner, GNCLot *lot); 184 185 /** Helper function used to filter a list of lots by owner. 186 */ 187 gboolean gncOwnerLotMatchOwnerFunc (GNCLot *lot, gpointer user_data); 188 189 /** Helper function used to sort lots by date. If the lot is 190 * linked to an invoice, use the invoice posted date, otherwise 191 * use the lot's opened date. 192 */ 193 gint gncOwnerLotsSortFunc (GNCLot *lotA, GNCLot *lotB); 194 195 /** Get the owner from the lot. If an owner is found in the lot, 196 * fill in "owner" and return TRUE. Otherwise return FALSE. 197 */ 198 gboolean gncOwnerGetOwnerFromLot (GNCLot *lot, GncOwner *owner); 199 200 /** Convenience function to get the owner from a transaction. 201 * Transactions don't really have an owner. What this function will 202 * do it figure out whether the transaction is part of a business 203 * transaction (either a posted invoice/bill/voucher/credit note or 204 * a payment transaction) and use the business object behind it 205 * to extract owner information. 206 */ 207 gboolean gncOwnerGetOwnerFromTxn (Transaction *txn, GncOwner *owner); 208 209 gboolean gncOwnerGetOwnerFromTypeGuid (QofBook *book, GncOwner *owner, QofIdType type, GncGUID *guid); 210 211 /** 212 * Create a lot for a payment to the owner using the other 213 * parameters passed in. If a transaction is set, this transaction will be 214 * reused if possible (meaning, if the transaction currency matches 215 * the owner's currency and if the transaction has (at least?) one 216 * split in the transfer account). 217 */ 218 GNCLot * 219 gncOwnerCreatePaymentLotSecs (const GncOwner *owner, Transaction **preset_txn, 220 Account *posted_acc, Account *xfer_acc, 221 gnc_numeric amount, gnc_numeric exch, time64 date, 222 const char *memo, const char *num); 223 224 /** 225 * Given a list of lots, try to balance as many of them as possible 226 * by creating balancing transactions between them. This can be used 227 * to automatically link invoices to payments (to "mark" invoices as 228 * paid) or to credit notes or the other way around. 229 * 230 * The function starts with the first lot in the list and tries to 231 * create balancing transactions to the remainder of the lots in the 232 * list. If it reaches the end of the list, it will find the next 233 * still open lot in the list and tries to balance it with all lots 234 * that follow it (the ones that precede it are either already closed 235 * or not suitable or they would have been processed in a previous 236 * iteration). 237 * 238 * By intelligently sorting the list of lots, you can play with the 239 * order of precedence in which the lots should be processed. For 240 * example, by sorting the oldest invoice lots first, the code will 241 * attempt to balance these first. 242 * 243 * Some restrictions: 244 * - the algorithm is lazy: it will create the smallest balancing 245 * transaction(s) possible, not the largest ones. Since the process 246 * is iterative, you will have balanced the maximum amount possible 247 * in the end, but it may be done in several transactions instead of 248 * only one big one. 249 * - the balancing transactions only work within one account. If a 250 * balancing lot is from another account than the lot currently being 251 * balanced, it will be skipped during balance evaluation. However 252 * if there is a mix of lots from two different accounts, the algorithm 253 * will still attempt to match all lots per account. 254 * - the calling function is responsible for the memory management 255 * of the lots list. If it created the list, it should properly free 256 * it as well. 257 */ 258 void gncOwnerAutoApplyPaymentsWithLots (const GncOwner *owner, GList *lots); 259 260 /** 261 * A convenience function to apply a payment to the owner. 262 * It creates a lot for a payment, optionally based on an existing 263 * transaction and then tries to balance it with the list of 264 * document/payment lots passed in. If not lots were given, 265 * all open lots for the owner are considered. 266 * 267 * This code is actually a convenience wrapper around gncOwnerCreatePaymentLot 268 * and gncOwnerAutoApplyPaymentsWithLots. See their descriptions for more 269 * details on what happens exactly. 270 */ 271 void 272 gncOwnerApplyPaymentSecs (const GncOwner *owner, Transaction **preset_txn, 273 GList *lots, Account *posted_acc, Account *xfer_acc, 274 gnc_numeric amount, gnc_numeric exch, time64 date, 275 const char *memo, const char *num, gboolean auto_pay); 276 277 /** Helper function to find a split in lot that best offsets target_value 278 * Obviously it should be of opposite sign. 279 * If there are more splits of opposite sign the following 280 * criteria are used in order of preference: 281 * 1. exact match in abs value is preferred over larger abs value 282 * 2. larger abs value is preferred over smaller abs value 283 * 3. if previous and new candidate are in the same value category, 284 * prefer real payment splits over lot link splits 285 * 4. if previous and new candidate are of same split type 286 * prefer biggest abs value. 287 */ 288 Split *gncOwnerFindOffsettingSplit (GNCLot *pay_lot, gnc_numeric target_value); 289 290 /** Helper function to reduce the value of a split to target_value. To make 291 * sure the split's parent transaction remains balanced a second split 292 * will be created with the remainder. Similarly if the split was part of a 293 * (business) lot, the remainder split will be added to the same lot to 294 * keep the lot's balance unchanged. 295 */ 296 gboolean gncOwnerReduceSplitTo (Split *split, gnc_numeric target_value); 297 298 /** To help a user understand what a lot link transaction does, 299 * we set the memo to name all documents involved in the link. 300 * The function below calculates this memo and sets it for 301 * all splits in the lot link transaction. 302 */ 303 void gncOwnerSetLotLinkMemo (Transaction *ll_txn); 304 305 /** Returns a GList of account-types based on the owner type */ 306 GList * gncOwnerGetAccountTypesList (const GncOwner *owner); 307 308 /** Returns a GList of currencies associated with the owner */ 309 GList * gncOwnerGetCommoditiesList (const GncOwner *owner); 310 311 312 /** Given an owner, extract the open balance from the owner and then 313 * convert it to the desired currency. 314 */ 315 gnc_numeric 316 gncOwnerGetBalanceInCurrency (const GncOwner *owner, 317 const gnc_commodity *report_currency); 318 319 #define OWNER_TYPE "type" 320 #define OWNER_TYPE_STRING "type-string" /**< Allows the type to be handled externally. */ 321 #define OWNER_CUSTOMER "customer" 322 #define OWNER_JOB "job" 323 #define OWNER_VENDOR "vendor" 324 #define OWNER_EMPLOYEE "employee" 325 #define OWNER_PARENT "parent" 326 #define OWNER_PARENTG "parent-guid" 327 #define OWNER_NAME "name" 328 329 #define OWNER_FROM_LOT "owner-from-lot" 330 331 /** 332 * These two functions are mainly for the convenience of scheme code. 333 * Normal C code has no need to ever use these two functions, and rather 334 * can just use a GncOwner directly and just pass around a pointer to it. 335 */ 336 GncOwner * gncOwnerNew (void); 337 void gncOwnerFree (GncOwner *owner); 338 339 340 /** 341 * These are convenience wrappers around gnc{Vendor,Customer,Job,Employee}* 342 * functions. This allows you to begin edit, destroy commit edit an owner 343 * without knowing its type. 344 */ 345 void gncOwnerBeginEdit (GncOwner *owner); 346 void gncOwnerCommitEdit (GncOwner *owner); 347 void gncOwnerDestroy (GncOwner *owner); 348 349 #endif /* GNC_OWNER_H_ */ 350 /** @} */ 351 /** @} */ 352