1 /********************************************************************\ 2 * gncAddress.h -- an Address object * 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 Address 25 26 An address belongs to another object, determined by the ::GncOwner. 27 It is the owner that assigns a name and identifier to the address. 28 In effect, an address is just a building - to make it useful to 29 GnuCash, it needs to be tied to a person. After all, you cannot 30 invoice a building, you invoice a person working / living in the 31 building. 32 33 QOF needs to handle all objects generically and to tie the address 34 to an owner, QOF must be able to find each - as entities. 35 36 This allows QOF to follow the hierarchy of objects without having 37 to call any application-specific routines. 38 39 To achieve this, new GncAddress routines have been added. An address 40 is now created with a NULL parent and the parent set explicitly using 41 the QOF object declaration. Whilst this adds functionality, it is 42 important that a valid ::GncOwner entity is always set as a parent. 43 This is an API issue - QOF will always set the parent provided that 44 a suitable entity is passed to the qofAddressSetOwner routine. It is 45 up to you to pass a suitable entity. 46 47 @{ */ 48 /** @file gncAddress.h 49 @brief an Address object 50 @author Copyright (C) 2001 Derek Atkins <warlord@MIT.EDU> 51 @author Copyright (c) 2005 Neil Williams <linux@codehelp.co.uk> 52 */ 53 54 #ifndef GNC_ADDRESS_H_ 55 #define GNC_ADDRESS_H_ 56 57 #include "qof.h" 58 #include "gncBusiness.h" 59 60 #define GNC_ADDRESS_MODULE_NAME "gncAddress" 61 #define GNC_ID_ADDRESS GNC_ADDRESS_MODULE_NAME 62 /** \struct GncAddress 63 64 @param QofInstance The address instance. 65 @param QofBook* Copy of the book pointer. 66 @param QofInstance* parent entity. 67 @param gboolean dirty flag 68 @param char* name of addressee 69 @param char* first line of address 70 @param char* second line of address 71 @param char* third line of address 72 @param char* fourth line of address 73 @param char* phone number 74 @param char* fax number 75 @param char* email address 76 */ 77 typedef struct _gncAddress GncAddress; 78 typedef struct _gncAddressClass GncAddressClass; 79 80 /* --- type macros --- */ 81 #define GNC_TYPE_ADDRESS (gnc_address_get_type ()) 82 #define GNC_ADDRESS(o) \ 83 (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_ADDRESS, GncAddress)) 84 #define GNC_ADDRESS_CLASS(k) \ 85 (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_ADDRESS, GncAddressClass)) 86 #define GNC_IS_ADDRESS(o) \ 87 (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_ADDRESS)) 88 #define GNC_IS_ADDRESS_CLASS(k) \ 89 (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_ADDRESS)) 90 #define GNC_ADDRESS_GET_CLASS(o) \ 91 (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_ADDRESS, GncAddressClass)) 92 GType gnc_address_get_type(void); 93 94 /** @name Create/Destroy functions 95 @{ */ 96 GncAddress *gncAddressCreate (QofBook *book, QofInstance *parent); 97 void gncAddressDestroy (GncAddress *addr); 98 void gncAddressBeginEdit (GncAddress *addr); 99 void gncAddressCommitEdit (GncAddress *addr); 100 101 /** @} */ 102 103 /** @name Set functions 104 @{ */ 105 106 void gncAddressSetName (GncAddress *addr, const char *name); 107 void gncAddressSetAddr1 (GncAddress *addr, const char *addr1); 108 void gncAddressSetAddr2 (GncAddress *addr, const char *addr2); 109 void gncAddressSetAddr3 (GncAddress *addr, const char *addr3); 110 void gncAddressSetAddr4 (GncAddress *addr, const char *addr4); 111 void gncAddressSetPhone (GncAddress *addr, const char *phone); 112 void gncAddressSetFax (GncAddress *addr, const char *fax); 113 void gncAddressSetEmail (GncAddress *addr, const char *email); 114 void gncAddressClearDirty (GncAddress *address); 115 /** @} */ 116 117 /** @name Get Functions 118 @{ */ 119 120 const char * gncAddressGetName (const GncAddress *addr); 121 const char * gncAddressGetAddr1 (const GncAddress *addr); 122 const char * gncAddressGetAddr2 (const GncAddress *addr); 123 const char * gncAddressGetAddr3 (const GncAddress *addr); 124 const char * gncAddressGetAddr4 (const GncAddress *addr); 125 const char * gncAddressGetPhone (const GncAddress *addr); 126 const char * gncAddressGetFax (const GncAddress *addr); 127 const char * gncAddressGetEmail (const GncAddress *addr); 128 /** @} */ 129 130 gboolean gncAddressIsDirty (const GncAddress *addr); 131 132 /** \brief compare two addresses 133 134 \return 0 if identical, -1 if a is empty or less than b 135 and +1 if a is more than b or if b is empty. 136 */ 137 int gncAddressCompare (const GncAddress *a, const GncAddress *b); 138 139 /** \brief Deeply compare two addresses 140 141 \return TRUE if all fields match, FALSE otherwise 142 */ 143 gboolean gncAddressEqual(const GncAddress *a, const GncAddress *b); 144 145 #define ADDRESS_NAME "name" 146 #define ADDRESS_ONE "number" 147 #define ADDRESS_TWO "street" 148 #define ADDRESS_THREE "locality" 149 #define ADDRESS_FOUR "city" 150 #define ADDRESS_PHONE "phone" 151 #define ADDRESS_FAX "fax" 152 #define ADDRESS_EMAIL "email" 153 #define ADDRESS_OWNER "owner" 154 155 #endif /* GNC_ADDRESS_H_ */ 156 /** @} */ 157 /** @} */ 158