Branch data Line data Source code
1 : : /********************************************************************
2 : : * gnc-commodity.h -- API for tradable commodities (incl. currency) *
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 : :
23 : : /** @addtogroup Engine
24 : : @{ */
25 : : /** @addtogroup Commodity Commodities
26 : : A commodity is something of value that is easily tradeable or
27 : : sellable; for example, currencies, stocks, bonds, grain,
28 : : copper, and oil are all commodities. This file provides
29 : : an API for defining a commodities, and for working with
30 : : collections of commodities. All GnuCash financial transactions
31 : : must identify the commodity that is being traded.
32 : :
33 : : @warning The system used here does not follow the object
34 : : handling and identification system (GncGUID's, Entities, etc.)
35 : : that the other parts of GnuCash use. The API really should be
36 : : ported over. This would allow us to get rid of the
37 : : commodity table routines defined below.
38 : :
39 : : @{ */
40 : : /** @file gnc-commodity.h
41 : : * @brief Commodity handling public routines
42 : : * @author Copyright (C) 2000 Bill Gribble
43 : : * @author Copyright (C) 2001 Linas Vepstas <linas@linas.org>
44 : : */
45 : :
46 : : #ifndef GNC_COMMODITY_H
47 : : #define GNC_COMMODITY_H
48 : :
49 : : typedef struct _GncCommodityClass gnc_commodityClass;
50 : : typedef struct _GncCommodityNamespaceClass gnc_commodity_namespaceClass;
51 : :
52 : : #include <glib.h>
53 : : #include <glib/gi18n.h>
54 : :
55 : : #include "gnc-engine.h"
56 : :
57 : : #ifdef __cplusplus
58 : : extern "C" {
59 : : #endif
60 : :
61 : : /* --- type macros --- */
62 : : #define GNC_TYPE_COMMODITY (gnc_commodity_get_type ())
63 : : #define GNC_COMMODITY(o) \
64 : : (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_COMMODITY, gnc_commodity))
65 : : #define GNC_COMMODITY_CLASS(k) \
66 : : (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_COMMODITY, gnc_commodityClass))
67 : : #define GNC_IS_COMMODITY(o) \
68 : : (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_COMMODITY))
69 : : #define GNC_IS_COMMODITY_CLASS(k) \
70 : : (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_COMMODITY))
71 : : #define GNC_COMMODITY_GET_CLASS(o) \
72 : : (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_COMMODITY, gnc_commodityClass))
73 : : GType gnc_commodity_get_type(void);
74 : :
75 : : /* --- type macros --- */
76 : : #define GNC_TYPE_COMMODITY_NAMESPACE (gnc_commodity_namespace_get_type ())
77 : : #define GNC_COMMODITY_NAMESPACE(o) \
78 : : (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_COMMODITY_NAMESPACE, gnc_commodity_namespace))
79 : : #define GNC_COMMODITY_NAMESPACE_CLASS(k) \
80 : : (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_COMMODITY_NAMESPACE, gnc_commodity_namespaceClass))
81 : : #define GNC_IS_COMMODITY_NAMESPACE(o) \
82 : : (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_COMMODITY_NAMESPACE))
83 : : #define GNC_IS_COMMODITY_NAMESPACE_CLASS(k) \
84 : : (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_COMMODITY_NAMESPACE))
85 : : #define GNC_COMMODITY_NAMESPACE_GET_CLASS(o) \
86 : : (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_COMMODITY_NAMESPACE, gnc_commodity_namespaceClass))
87 : : GType gnc_commodity_namespace_get_type(void);
88 : :
89 : :
90 : : #define GNC_COMMODITY_TABLE "gnc_commodity_table"
91 : :
92 : : /** The commodity namespace definitions are used to tag a commodity by
93 : : * its type, or a stocks by the exchange where it is traded.
94 : : *
95 : : * The LEGACY name is only used by the file i/o routines, and is
96 : : * converted to another commodity namespace before it is seen by the
97 : : * rest of the system. The ISO namespace represents currencies.
98 : : * With the exception of the NASDAQ namespace (which is used once in
99 : : * the binary importer) the rest of the namespace declarations are
100 : : * only used to populate an option menu in the commodity selection
101 : : * window.
102 : : */
103 : : #define GNC_COMMODITY_NS_LEGACY "GNC_LEGACY_CURRENCIES"
104 : : #define GNC_COMMODITY_NS_TEMPLATE "template"
105 : : /* The ISO define is deprecated in favor of CURRENCY */
106 : : #define GNC_COMMODITY_NS_ISO "ISO4217"
107 : : #define GNC_COMMODITY_NS_CURRENCY "CURRENCY"
108 : : #define GNC_COMMODITY_NS_NONCURRENCY "NONCURRENCY"
109 : :
110 : : #define GNC_COMMODITY_NS_NONISO_GUI NC_("Commodity Type", "All non-currency")
111 : : #define GNC_COMMODITY_NS_ISO_GUI NC_("Commodity Type", "Currencies")
112 : :
113 : : /** Max fraction is 10^9 because 10^10 would require changing it to an
114 : : * int64_t.
115 : : */
116 : : #define GNC_COMMODITY_MAX_FRACTION 1000000000
117 : :
118 : : typedef GList CommodityList;
119 : :
120 : : /** @name Commodity Quote Source functions
121 : : @{
122 : : */
123 : :
124 : : /** The quote source type enum account types are used to determine how
125 : : * the transaction data in the account is displayed. These values
126 : : * can be safely changed from one release to the next.
127 : : */
128 : : typedef enum
129 : : {
130 : : SOURCE_SINGLE = 0, /**< This quote source pulls from a single
131 : : * specific web site. For example, the
132 : : * yahoo_australia source only pulls from
133 : : * the yahoo web site. */
134 : : SOURCE_MULTI, /**< This quote source may pull from multiple
135 : : * web sites. For example, the australia
136 : : * source may pull from ASX, yahoo, etc. */
137 : : SOURCE_UNKNOWN, /**< This is a locally installed quote source
138 : : * that gnucash knows nothing about. May
139 : : * pull from single or multiple
140 : : * locations. */
141 : : SOURCE_MAX,
142 : : SOURCE_CURRENCY = SOURCE_MAX, /**< The special currency quote source. */
143 : : } QuoteSourceType;
144 : :
145 : : /** This function indicates whether or not the Finance::Quote module
146 : : * is installed on a user's computer. This includes any other related
147 : : * modules that gnucash need to process F::Q information.
148 : : *
149 : : * @return TRUE is F::Q is installed properly.
150 : : */
151 : : gboolean gnc_quote_source_fq_installed (void);
152 : :
153 : : /** This function returns the version of the Finance::Quote module
154 : : * installed on a user's computer. If no proper installation is found
155 : : * it will return NULL.
156 : : *
157 : : * @return a version string or NULL
158 : : */
159 : : const char* gnc_quote_source_fq_version (void);
160 : :
161 : : /** Return the number of entries for a given type of quote source.
162 : : *
163 : : * @param type The quote source type whose count should be returned.
164 : : *
165 : : * @return The number of entries for this type of quote source.
166 : : */
167 : : gint gnc_quote_source_num_entries(QuoteSourceType type);
168 : :
169 : : /** Create a new quote source. This is called by the F::Q startup code
170 : : * or the XML parsing code to add new entries to the list of
171 : : * available quote sources.
172 : : *
173 : : * @param name The internal name for this new quote source.
174 : : *
175 : : * @param supported TRUE if this quote source is supported by F::Q.
176 : : * Should only be set by the F::Q startup routine.
177 : : *
178 : : * @return A pointer to the newly created quote source.
179 : : */
180 : : gnc_quote_source *gnc_quote_source_add_new(const char * name, gboolean supported);
181 : :
182 : : /** Given the internal (gnucash or F::Q) name of a quote source, find
183 : : * the data structure identified by this name.
184 : : *
185 : : * @param internal_name The name of this quote source.
186 : : *
187 : : * @return A pointer to the price quote source that has the specified
188 : : * internal name.
189 : : */
190 : : /*@ dependent @*/
191 : : gnc_quote_source *gnc_quote_source_lookup_by_internal(const char * internal_name);
192 : :
193 : : /** Given the type/index of a quote source, find the data structure
194 : : * identified by this pair.
195 : : *
196 : : * @param type The type of this quote source.
197 : : *
198 : : * @param index The index of this quote source within its type.
199 : : *
200 : : * @return A pointer to the price quote source that has the specified
201 : : * type/index.
202 : : */
203 : : gnc_quote_source *gnc_quote_source_lookup_by_ti(QuoteSourceType type, gint index);
204 : :
205 : : /** Given a gnc_quote_source data structure, return the flag that
206 : : * indicates whether this particular quote source is supported by
207 : : * the user's F::Q installation.
208 : : *
209 : : * @param source The quote source in question.
210 : : *
211 : : * @return TRUE if the user's computer supports this quote source.
212 : : */
213 : : gboolean gnc_quote_source_get_supported (const gnc_quote_source *source);
214 : :
215 : : /** Given a gnc_quote_source data structure, return the type of this
216 : : * particular quote source. (SINGLE, MULTI, UNKNOWN)
217 : : *
218 : : * @param source The quote source in question.
219 : : *
220 : : * @return The type of this quote source.
221 : : */
222 : : QuoteSourceType gnc_quote_source_get_type (const gnc_quote_source *source);
223 : :
224 : : /** Given a gnc_quote_source data structure, return the index of this
225 : : * particular quote source within its type.
226 : : *
227 : : * @param source The quote source in question.
228 : : *
229 : : * @return The index of this quote source in its type.
230 : : */
231 : : gint gnc_quote_source_get_index (const gnc_quote_source *source);
232 : :
233 : : /** Given a gnc_quote_source data structure, return the user friendly
234 : : * name of this quote source. E.G. "Yahoo Australia" or "Australia
235 : : * (Yahoo, ASX, ...)"
236 : : *
237 : : * @param source The quote source in question.
238 : : *
239 : : * @return The user friendly name.
240 : : */
241 : : /*@ dependent @*/
242 : : const char *gnc_quote_source_get_user_name (const gnc_quote_source *source);
243 : :
244 : : /** Given a gnc_quote_source data structure, return the internal name
245 : : * of this quote source. This is the name used by both gnucash and
246 : : * by Finance::Quote. E.G. "yahoo_australia" or "australia"
247 : : *
248 : : * @param source The quote source in question.
249 : : *
250 : : * @return The internal name.
251 : : */
252 : : /*@ dependent @*/
253 : : const char *gnc_quote_source_get_internal_name (const gnc_quote_source *source);
254 : :
255 : : /** @} */
256 : :
257 : :
258 : : /** @name Commodity Creation
259 : : @{
260 : : */
261 : :
262 : : /** Create a new commodity. This function allocates a new commodity
263 : : * data structure, populates it with the data provided, and then
264 : : * generates the dynamic names that exist as part of a commodity.
265 : : *
266 : : * @note This function does not check to see if the commodity exists
267 : : * before adding a new commodity.
268 : : *
269 : : * @param book The book that the new commodity will belong to.
270 : : *
271 : : * @param fullname The complete name of this commodity. E.G. "Acme
272 : : * Systems, Inc."
273 : : *
274 : : * @param commodity_namespace An aggregation of commodities. E.G. ISO4217,
275 : : * Nasdaq, Downbelow, etc.
276 : : *
277 : : * @param mnemonic An abbreviation for this stock. For publicly
278 : : * traced stocks, this field should contain the stock ticker
279 : : * symbol. This field is used to get online price quotes, so it must
280 : : * match the stock ticker symbol used by the exchange where you want
281 : : * to get automatic stock quote updates. E.G. ACME, ACME.US, etc.
282 : : *
283 : : * @param cusip A string containing the CUSIP code or similar
284 : : * UNIQUE code for this commodity like the ISIN. The stock ticker is
285 : : * NOT appropriate as that goes in the mnemonic field.
286 : : *
287 : : * @param fraction The smallest division of this commodity
288 : : * allowed. I.E. If this is 1, then the commodity must be traded in
289 : : * whole units; if 100 then the commodity may be traded in 0.01
290 : : * units, etc.
291 : : *
292 : : * @return A pointer to the new commodity.
293 : : */
294 : : /*@ dependent @*/
295 : : gnc_commodity * gnc_commodity_new(QofBook *book,
296 : : /*@ null @*/ const char * fullname,
297 : : /*@ null @*/ const char * commodity_namespace,
298 : : /*@ null @*/ const char * mnemonic,
299 : : /*@ null @*/ const char * cusip,
300 : : int fraction);
301 : :
302 : : /** Destroy a commodity. Release all memory attached to this data structure.
303 : : * @note This function does not (can not) check to see if the
304 : : * commodity is referenced anywhere.
305 : : * @param cm The commodity to destroy.
306 : : */
307 : : void gnc_commodity_destroy(gnc_commodity * cm);
308 : :
309 : : /** Copy src into dest */
310 : : void gnc_commodity_copy(gnc_commodity * dest, const gnc_commodity *src);
311 : :
312 : : /** allocate and copy */
313 : : gnc_commodity * gnc_commodity_clone(const gnc_commodity *src, QofBook *dest_book);
314 : : /** @} */
315 : :
316 : :
317 : :
318 : : /** @name Commodity Accessor Routines - Get
319 : : @{
320 : : */
321 : :
322 : : /** Retrieve the mnemonic for the specified commodity. This will be a
323 : : * pointer to a null terminated string of the form "ACME", "QWER",
324 : : * etc.
325 : : *
326 : : * @param cm A pointer to a commodity data structure.
327 : : *
328 : : * @return A pointer to the mnemonic for this commodity. This string
329 : : * is owned by the engine and should not be freed by the caller.
330 : : */
331 : : const char * gnc_commodity_get_mnemonic(const gnc_commodity * cm);
332 : :
333 : : /** Retrieve the namespace for the specified commodity. This will be
334 : : * a pointer to a null terminated string of the form "AMEX",
335 : : * "NASDAQ", etc.
336 : : *
337 : : * @param cm A pointer to a commodity data structure.
338 : : *
339 : : * @return A pointer to the namespace for this commodity. This string
340 : : * is owned by the engine and should not be freed by the caller.
341 : : */
342 : : const char * gnc_commodity_get_namespace(const gnc_commodity * cm);
343 : :
344 : : /** Retrieve the namespace data structure for the specified commodity.
345 : : * This will be a pointer to another data structure.
346 : : *
347 : : * @param cm A pointer to a commodity data structure.
348 : : *
349 : : * @return A pointer to the namespace data structure for this
350 : : * commodity.
351 : : */
352 : : gnc_commodity_namespace *gnc_commodity_get_namespace_ds(const gnc_commodity * cm);
353 : :
354 : : /** Retrieve the full name for the specified commodity. This will be
355 : : * a pointer to a null terminated string of the form "Acme Systems,
356 : : * Inc.", etc.
357 : : *
358 : : * @param cm A pointer to a commodity data structure.
359 : : *
360 : : * @return A pointer to the full name for this commodity. This string
361 : : * is owned by the engine and should not be freed by the caller.
362 : : */
363 : : const char * gnc_commodity_get_fullname(const gnc_commodity * cm);
364 : :
365 : : /** Retrieve the 'print' name for the specified commodity. This will
366 : : * be a pointer to a null terminated string of the form "Acme
367 : : * Systems, Inc. (ACME)", etc.
368 : : *
369 : : * @param cm A pointer to a commodity data structure.
370 : : *
371 : : * @return A pointer to the print name for this commodity. This
372 : : * string is owned by the engine and should not be freed by the
373 : : * caller.
374 : : */
375 : : const char * gnc_commodity_get_printname(const gnc_commodity * cm);
376 : :
377 : : /** Retrieve the 'exchange code' for the specified commodity. This
378 : : * will be a pointer to a null terminated string of the form
379 : : * "AXQ14728", etc. This field is often used when presenting
380 : : * information to the user.
381 : : *
382 : : * @note This is a unique code that specifies a particular item or
383 : : * set of shares of a commodity, not a code that specifies a stock
384 : : * exchange. That is the namespace field.
385 : : *
386 : : * @param cm A pointer to a commodity data structure.
387 : : *
388 : : * @return A pointer to the exchange code for this commodity. This
389 : : * string is owned by the engine and should not be freed by the
390 : : * caller.
391 : : */
392 : : const char * gnc_commodity_get_cusip(const gnc_commodity * cm);
393 : :
394 : : /** Retrieve the 'unique' name for the specified commodity. This will
395 : : * be a pointer to a null terminated string of the form "AMEX::ACME",
396 : : * etc. This field is often used when performing comparisons or
397 : : * other functions invisible to the user.
398 : : *
399 : : * @param cm A pointer to a commodity data structure.
400 : : *
401 : : * @return A pointer to the 'unique' name for this commodity. This
402 : : * string is owned by the engine and should not be freed by the
403 : : * caller.
404 : : */
405 : : const char * gnc_commodity_get_unique_name(const gnc_commodity * cm);
406 : :
407 : : /** Retrieve the fraction for the specified commodity. This will be
408 : : * an integer value specifying the number of fractional units that
409 : : * one of these commodities can be divided into. Should always be a
410 : : * power of 10.
411 : : *
412 : : * @param cm A pointer to a commodity data structure.
413 : : *
414 : : * @return The number of fractional units that one of these
415 : : * commodities can be divided into.
416 : : */
417 : : int gnc_commodity_get_fraction(const gnc_commodity * cm);
418 : :
419 : : /** Retrieve the automatic price quote flag for the specified
420 : : * commodity. This flag indicates whether stock quotes should be
421 : : * retrieved for the specified stock.
422 : : *
423 : : * @param cm A pointer to a commodity data structure.
424 : : *
425 : : * @return TRUE if quotes should be pulled for this commodity, FALSE
426 : : * otherwise.
427 : : */
428 : : gboolean gnc_commodity_get_quote_flag(const gnc_commodity *cm);
429 : :
430 : : /** Retrieve the automatic price quote source for the specified
431 : : * commodity. This will be a pointer to a null terminated string of
432 : : * the form "Yahoo (Asia)", etc.
433 : : *
434 : : * @param cm A pointer to a commodity data structure.
435 : : *
436 : : * @return A pointer to the price quote source for this commodity.
437 : : */
438 : : /*@ dependent @*/
439 : : gnc_quote_source* gnc_commodity_get_quote_source(const gnc_commodity *cm);
440 : : /*@ dependent @*/
441 : : gnc_quote_source* gnc_commodity_get_default_quote_source(const gnc_commodity *cm);
442 : :
443 : : /** Retrieve the automatic price quote timezone for the specified
444 : : * commodity. This will be a pointer to a null terminated string of
445 : : * the form "America/New_York", etc.
446 : : *
447 : : * @param cm A pointer to a commodity data structure.
448 : : *
449 : : * @return A pointer to the price quote timezone for this commodity.
450 : : * This string is owned by the engine and should not be freed by the
451 : : * caller.
452 : : */
453 : : const char* gnc_commodity_get_quote_tz(const gnc_commodity *cm);
454 : :
455 : : /** Retrieve the user-defined symbol for the specified commodity. This
456 : : * will be a pointer to a nul terminated string like "£", "US$", etc.
457 : : *
458 : : * @param cm A pointer to a commodity data structure.
459 : : *
460 : : * @return A pointer to the user-defined symbol for this commodity.
461 : : * NULL means that the user didn't define any symbol, and that fallback to
462 : : * e.g. the mnemonic is in order. This string is owned by the engine and
463 : : * should not be freed by the caller.
464 : : */
465 : : const char* gnc_commodity_get_user_symbol(const gnc_commodity *cm);
466 : :
467 : : /** Retrieve the default symbol for the specified commodity. This will
468 : : * be a pointer to a nul terminated string like "£", "US$", etc. Note
469 : : * that for the locale currency, you probably want to look at the
470 : : * system-provided symbol first. See gnc_commodity_get_nice_symbol.
471 : : *
472 : : * @param cm A pointer to a commodity data structure.
473 : : *
474 : : * @return A pointer to the default symbol for this commodity.
475 : : */
476 : : const char* gnc_commodity_get_default_symbol(const gnc_commodity *cm);
477 : :
478 : : /** Retrieve a symbol for the specified commodity, suitable for
479 : : * display to the user. This will be a pointer to a nul terminated
480 : : * string like "£", "US$", etc. That function is locale-aware and
481 : : * will base its choice of symbol on the user-configured symbol,
482 : : * the locale a
483 : : *
484 : : * @param cm A pointer to a commodity data structure.
485 : : *
486 : : * @return A pointer to the symbol for this commodity.
487 : : */
488 : : const char*gnc_commodity_get_nice_symbol(const gnc_commodity *cm);
489 : : /** @} */
490 : :
491 : : /** @name Commodity Accessor Routines - Set
492 : : @{
493 : : */
494 : :
495 : : /** Set the mnemonic for the specified commodity. This should be a
496 : : * pointer to a null terminated string of the form "ACME", "QWER",
497 : : * etc.
498 : : *
499 : : * @param cm A pointer to a commodity data structure.
500 : : *
501 : : * @param mnemonic A pointer to the mnemonic for this commodity.
502 : : * This string belongs to the caller and will be duplicated by the
503 : : * engine.
504 : : */
505 : : void gnc_commodity_set_mnemonic(gnc_commodity * cm, const char * mnemonic);
506 : :
507 : : /** Set the namespace for the specified commodity. This should be a
508 : : * pointer to a null terminated string of the form "AMEX", "NASDAQ",
509 : : * etc.
510 : : *
511 : : * @param cm A pointer to a commodity data structure.
512 : : *
513 : : * @param new_namespace A pointer to the namespace for this commodity.
514 : : * This string belongs to the caller and will be duplicated by the
515 : : * engine.
516 : : */
517 : : void gnc_commodity_set_namespace(gnc_commodity * cm, const char * new_namespace);
518 : :
519 : : /** Set the full name for the specified commodity. This should be
520 : : * a pointer to a null terminated string of the form "Acme Systems,
521 : : * Inc.", etc.
522 : : *
523 : : * @param cm A pointer to a commodity data structure.
524 : : *
525 : : * @param fullname A pointer to the full name for this commodity.
526 : : * This string belongs to the caller and will be duplicated by the
527 : : * engine.
528 : : */
529 : : void gnc_commodity_set_fullname(gnc_commodity * cm, const char * fullname);
530 : :
531 : : /** Set the 'exchange code' for the specified commodity. This should
532 : : * be a pointer to a null terminated string of the form "AXQ14728",
533 : : * etc.
534 : : *
535 : : * @note This is a unique code that specifies a particular item or
536 : : * set of shares of a commodity, not a code that specifies a stock
537 : : * exchange. That is the namespace field.
538 : : *
539 : : * @param cm A pointer to a commodity data structure.
540 : : *
541 : : * @param cusip A pointer to the cusip or other exchange specific
542 : : * data for this commodity. This string belongs to the caller and
543 : : * will be duplicated by the engine.
544 : : */
545 : : void gnc_commodity_set_cusip(gnc_commodity * cm, const char * cusip);
546 : :
547 : : /** Set the fraction for the specified commodity. This should be
548 : : * an integer value specifying the number of fractional units that
549 : : * one of these commodities can be divided into. Should always be a
550 : : * power of 10.
551 : : *
552 : : * @param cm A pointer to a commodity data structure.
553 : : *
554 : : * @param smallest_fraction The number of fractional units that one of
555 : : * these commodities can be divided into.
556 : : */
557 : : void gnc_commodity_set_fraction(gnc_commodity * cm, int smallest_fraction);
558 : :
559 : : /** Set the automatic price quote flag for the specified commodity,
560 : : * based on user input. This flag indicates whether stock quotes
561 : : * should be retrieved for the specified stock.
562 : : *
563 : : * It is necessary to have a separate function to distinguish when
564 : : * this setting is being modified by a user so that the
565 : : * auto-enabling/auto-disabling of currencies can be handled
566 : : * properly.
567 : : *
568 : : * @param cm A pointer to a commodity data structure.
569 : : *
570 : : * @param flag TRUE if quotes should be pulled for this commodity, FALSE
571 : : * otherwise.
572 : : */
573 : : void gnc_commodity_user_set_quote_flag(gnc_commodity *cm,
574 : : const gboolean flag);
575 : :
576 : : /** Set the automatic price quote flag for the specified commodity.
577 : : * This flag indicates whether stock quotes should be retrieved for
578 : : * the specified stock.
579 : : *
580 : : * @param cm A pointer to a commodity data structure.
581 : : *
582 : : * @param flag TRUE if quotes should be pulled for this commodity, FALSE
583 : : * otherwise.
584 : : */
585 : : void gnc_commodity_set_quote_flag(gnc_commodity *cm, const gboolean flag);
586 : :
587 : : /** Set the automatic price quote source for the specified commodity.
588 : : * This should be a pointer to a null terminated string of the form
589 : : * "Yahoo (Asia)", etc. Legal values can be found in the
590 : : * quote_sources array in the file gnc-ui-util.c.
591 : : *
592 : : * @param cm A pointer to a commodity data structure.
593 : : *
594 : : * @param src A pointer to the price quote source for this commodity.
595 : : */
596 : : void gnc_commodity_set_quote_source(gnc_commodity *cm, gnc_quote_source *src);
597 : :
598 : : /** Set the automatic price quote timezone for the specified
599 : : * commodity. This should be a pointer to a null terminated string
600 : : * of the form "America/New_York", etc. Legal values can be found in
601 : : * the known_timezones array in the file src/gnome-utils/dialog-commodity.c.
602 : : *
603 : : * @param cm A pointer to a commodity data structure.
604 : : *
605 : : * @param tz A pointer to the price quote timezone for this commodity.
606 : : * This string belongs to the caller and will be duplicated by the
607 : : * engine.
608 : : */
609 : : void gnc_commodity_set_quote_tz(gnc_commodity *cm, const char *tz);
610 : :
611 : : /** Set a user-defined symbol for the specified commodity. This should
612 : : * be a pointer to a nul terminated string like "£", "US$", etc.
613 : : *
614 : : * @param cm A pointer to a commodity data structure.
615 : : *
616 : : * @param tz A pointer to the symbol for this commodity. This string
617 : : * belongs to the caller and will be duplicated by the engine.
618 : : */
619 : : void gnc_commodity_set_user_symbol(gnc_commodity *cm, const char *user_symbol);
620 : : /** @} */
621 : :
622 : : /** @name Commodity Usage Count Adjustment Routines
623 : : @{
624 : : */
625 : :
626 : : /** Increment a commodity's internal counter that tracks how many
627 : : * accounts are using that commodity. For currencies, this may have
628 : : * the side effect of enabling the commodity's quote flag.
629 : : *
630 : : * @param cm A pointer to a commodity data structure.
631 : : */
632 : : void
633 : : gnc_commodity_increment_usage_count(gnc_commodity *cm);
634 : :
635 : : /** Decrement a commodity's internal counter that tracks how many
636 : : * accounts are using that commodity. For currencies, this may have
637 : : * the side effect of disabling the commodity's quote flag.
638 : : *
639 : : * @param cm A pointer to a commodity data structure.
640 : : */
641 : : void
642 : : gnc_commodity_decrement_usage_count(gnc_commodity *cm);
643 : : /** @} */
644 : :
645 : :
646 : : /** @name Commodity Comparison
647 : : @{
648 : : */
649 : :
650 : : /** This routine returns TRUE if the two commodities are equivalent.
651 : : * Commodities are equivalent if they have the same namespace and
652 : : * mnemonic. Equivalent commodities may belong to different
653 : : * exchanges, may have different fullnames, and may have different
654 : : * fractions.
655 : : */
656 : : gboolean gnc_commodity_equiv(const gnc_commodity * a, const gnc_commodity * b);
657 : :
658 : : /** This routine returns TRUE if the two commodities are equal.
659 : : * Commodities are equal if they have the same namespace, mnemonic,
660 : : * fullname, exchange private code and fraction.
661 : : */
662 : : gboolean gnc_commodity_equal(const gnc_commodity * a, const gnc_commodity * b);
663 : :
664 : : /** This routine returns 0 if the two commodities are equal, 1 otherwise.
665 : : * Commodities are equal if they have the same namespace, mnemonic,
666 : : * fullname, exchange private code and fraction.
667 : : * This function is useful for list-traversal comparison purposes where
668 : : * The semantics are 0, <0, or >0 (equal, greater than, less than) rather
669 : : * than "true or false"
670 : : */
671 : : int gnc_commodity_compare(const gnc_commodity * a, const gnc_commodity * b);
672 : :
673 : : /** A wrapper around gnc_commodity_compare() which offers the function
674 : : * declaration that is needed for g_list_find_custom(), which needs
675 : : * void pointers instead of gnc_commodity ones.
676 : : */
677 : : int gnc_commodity_compare_void(const void * a, const void * b);
678 : : /** @} */
679 : :
680 : :
681 : : /** @name Currency Checks
682 : : @{
683 : : */
684 : :
685 : : /** Checks to see if the specified commodity namespace is the
686 : : * namespace for ISO 4217 currencies.
687 : : *
688 : : * @param commodity_namespace The string to check.
689 : : *
690 : : * @return TRUE if the string indicates an ISO currency, FALSE otherwise. */
691 : : gboolean gnc_commodity_namespace_is_iso(const char *commodity_namespace);
692 : :
693 : : /** Checks to see if the specified commodity is an ISO 4217 recognized currency.
694 : : *
695 : : * @param cm The commodity to check.
696 : : *
697 : : * @return TRUE if the commodity represents a currency, FALSE otherwise. */
698 : : gboolean gnc_commodity_is_iso(const gnc_commodity * cm);
699 : :
700 : : /** Checks to see if the specified commodity is an ISO 4217 recognized
701 : : * currency or a legacy currency.
702 : : *
703 : : * @param cm The commodity to check.
704 : : *
705 : : * @return TRUE if the commodity represents a currency, FALSE otherwise. */
706 : : gboolean gnc_commodity_is_currency(const gnc_commodity *cm);
707 : :
708 : : /** @} */
709 : :
710 : :
711 : : /* =============================================================== */
712 : : /** @name Commodity Table
713 : : @{
714 : : */
715 : :
716 : : /** Returns the commodity table associated with a book.
717 : : */
718 : : /*@ dependent @*/
719 : : gnc_commodity_table * gnc_commodity_table_get_table(QofBook *book);
720 : :
721 : : /** @} */
722 : : /* ---------------------------------------------------------- */
723 : : /** @name Commodity Table Lookup functions
724 : : @{
725 : : */
726 : : gnc_commodity * gnc_commodity_table_lookup(const gnc_commodity_table * table,
727 : : const char * commodity_namespace,
728 : : const char * mnemonic);
729 : : gnc_commodity *
730 : : gnc_commodity_table_lookup_unique(const gnc_commodity_table *table,
731 : : const char * unique_name);
732 : : gnc_commodity * gnc_commodity_table_find_full(const gnc_commodity_table * t,
733 : : const char * commodity_namespace,
734 : : const char * fullname);
735 : :
736 : : /*@ dependent @*/
737 : : gnc_commodity * gnc_commodity_find_commodity_by_guid(const GncGUID *guid,
738 : : QofBook *book);
739 : :
740 : : /** @} */
741 : : /* ---------------------------------------------------------- */
742 : :
743 : : /** @name Commodity Table Maintenance functions
744 : : @{
745 : : */
746 : :
747 : : /** Add a new commodity to the commodity table. This routine handles
748 : : * the cases where the commodity already exists in the database (does
749 : : * nothing), or another entries has the same namespace and mnemonic
750 : : * (updates the existing entry).
751 : : *
752 : : * @param table A pointer to the commodity table
753 : : *
754 : : * @param comm A pointer to the commodity to add.
755 : : *
756 : : * @return The added commodity. Null on error.
757 : : *
758 : : * @note The commodity pointer passed to this function should not be
759 : : * used after its return, as it may have been destroyed. Use the
760 : : * return value which is guaranteed to be valid. */
761 : : /*@ dependent @*/
762 : : gnc_commodity * gnc_commodity_table_insert(gnc_commodity_table * table,
763 : : gnc_commodity * comm);
764 : :
765 : : /** Remove a commodity from the commodity table. If the commodity to
766 : : * remove doesn't exist, nothing happens.
767 : : *
768 : : * @param table A pointer to the commodity table
769 : : *
770 : : * @param comm A pointer to the commodity to remove. */
771 : : void gnc_commodity_table_remove(gnc_commodity_table * table,
772 : : gnc_commodity * comm);
773 : :
774 : : /** Add all the standard namespaces and currencies to the commodity
775 : : * table. This routine creates the namespaces for the NYSE, NASDAQ,
776 : : * etc. It also adds all of the ISO 4217 currencies to the commodity
777 : : * table.
778 : : *
779 : : * @param table A pointer to the commodity table.
780 : : *
781 : : * @param book Unused. */
782 : : gboolean gnc_commodity_table_add_default_data(gnc_commodity_table *table, QofBook *book);
783 : :
784 : : /** @} */
785 : : /* ---------------------------------------------------------- */
786 : : /** @name Commodity Table Namespace functions
787 : : @{
788 : : */
789 : :
790 : : /** Return the textual name of a namespace data structure.
791 : : *
792 : : * @param ns A pointer to the namespace data structure.
793 : : *
794 : : * @return A pointer to the name of the namespace. This string is
795 : : * owned by the engine and should not be freed by the caller. */
796 : : const char * gnc_commodity_namespace_get_name (const gnc_commodity_namespace *ns) ;
797 : :
798 : : /** Return the textual name of a namespace data structure in a form suitable to
799 : : * present to the user.
800 : : *
801 : : * @param ns A pointer to the namespace data structure.
802 : : *
803 : : * @return A pointer to the gui friendly name of the namespace. This string is
804 : : * owned by the engine and should not be freed by the caller.
805 : : *
806 : : * @notes The returned string is marked for translation, but not translated yet.
807 : : * If you want it translated pass the return value on to gettext.
808 : : */
809 : : const char * gnc_commodity_namespace_get_gui_name (const gnc_commodity_namespace *ns) ;
810 : :
811 : :
812 : : /** Return a list of all commodity data structures in the specified namespace.
813 : : *
814 : : * @return A pointer to the list of structures. NULL if an invalid
815 : : * argument was supplied.
816 : : *
817 : : * @note This list is owned by the caller who must free the list. */
818 : : GList * gnc_commodity_namespace_get_commodity_list(const gnc_commodity_namespace * ns);
819 : :
820 : :
821 : : /** Test to see if the indicated namespace exits in the commodity table.
822 : : *
823 : : * @param table A pointer to the commodity table
824 : : *
825 : : * @param commodity_namespace The new namespace to check.
826 : : *
827 : : * @return 1 if the namespace exists. 0 if it doesn't exist, or the
828 : : * routine was passed a bad argument. */
829 : : int gnc_commodity_table_has_namespace(const gnc_commodity_table * table,
830 : : const char * commodity_namespace);
831 : :
832 : : /** Return a list of all namespaces in the commodity table. This
833 : : * returns both system and user defined namespaces.
834 : : *
835 : : * @return A pointer to the list of names. NULL if an invalid
836 : : * argument was supplied.
837 : : *
838 : : * @note It is the callers responsibility to free the list. */
839 : : GList * gnc_commodity_table_get_namespaces(const gnc_commodity_table * t);
840 : :
841 : : /** Return a list of all namespace data structures in the commodity table. This
842 : : * returns both system and user defined namespace structures.
843 : : *
844 : : * @return A pointer to the list of structures. NULL if an invalid
845 : : * argument was supplied.
846 : : *
847 : : * @note This list is owned by the caller who must free the list. */
848 : : GList * gnc_commodity_table_get_namespaces_list(const gnc_commodity_table * t);
849 : :
850 : : /** This function adds a new string to the list of commodity namespaces.
851 : : * If the new namespace already exists, nothing happens.
852 : : *
853 : : * @param table A pointer to the commodity table
854 : : *
855 : : * @param commodity_namespace The new namespace to be added.
856 : : *
857 : : * @param book The book that the new namespace will belong to.
858 : : *
859 : : * @return A pointer to the newly created namespace. */
860 : : gnc_commodity_namespace * gnc_commodity_table_add_namespace(gnc_commodity_table * table,
861 : : const char * commodity_namespace,
862 : : QofBook *book);
863 : :
864 : : /** This function finds a commodity namespace in the set of existing commodity namespaces.
865 : : *
866 : : * @param table A pointer to the commodity table
867 : : *
868 : : * @param commodity_namespace The new namespace to be added.
869 : : *
870 : : * @return The a pointer to the namespace found, or NULL if the
871 : : * namespace doesn't exist. */
872 : : gnc_commodity_namespace * gnc_commodity_table_find_namespace(const gnc_commodity_table * table,
873 : : const char * commodity_namespace);
874 : :
875 : : /** This function deletes a string from the list of commodity namespaces.
876 : : * If the namespace does not exist, nothing happens.
877 : : *
878 : : * @param table A pointer to the commodity table
879 : : *
880 : : * @param commodity_namespace The namespace to be deleted.
881 : : *
882 : : * @note This routine will destroy any commodities that exist as part
883 : : * of this namespace. Use it carefully. */
884 : : void gnc_commodity_table_delete_namespace(gnc_commodity_table * table,
885 : : const char * commodity_namespace);
886 : : /** @} */
887 : : /* ---------------------------------------------------------- */
888 : : /** @name Commodity Table Accessor functions
889 : : @{
890 : : */
891 : :
892 : : /** Returns the number of commodities in the commodity table.
893 : : *
894 : : * @param tbl A pointer to the commodity table
895 : : *
896 : : * @return The number of commodities in the table. 0 if there are no
897 : : * commodities, or the routine was passed a bad argument. */
898 : : guint gnc_commodity_table_get_size(const gnc_commodity_table* tbl);
899 : :
900 : : /** Return a list of all commodities in the commodity table that are
901 : : * in the given namespace.
902 : : *
903 : : * @param table A pointer to the commodity table
904 : : *
905 : : * @param commodity_namespace A string indicating which commodities should be
906 : : * returned. It is a required argument.
907 : : *
908 : : * @return A pointer to the list of commodities. NULL if an invalid
909 : : * argument was supplied, or the namespace could not be found.
910 : : *
911 : : * @note It is the callers responsibility to free the list. */
912 : : CommodityList * gnc_commodity_table_get_commodities(
913 : : const gnc_commodity_table * table, const char * commodity_namespace);
914 : :
915 : : /** This function returns a list of commodities for which price quotes
916 : : * should be retrieved. It will scan the entire commodity table (or
917 : : * a subset) and check each commodity to see if the price_quote_flag
918 : : * field has been set. All matching commodities are queued onto a
919 : : * list, and the head of that list is returned. Use the command-line
920 : : * given expression as a filter on the commodities to be returned. If
921 : : * non-null, only commodities in namespace that match the specified
922 : : * regular expression are checked. If none was given, all
923 : : * commodities are checked.
924 : : *
925 : : * @param table A pointer to the commodity table
926 : : *
927 : : * @return A pointer to a list of commodities. NULL if invalid
928 : : * arguments were supplied or if there no commodities are flagged for
929 : : * quote retrieval.
930 : : *
931 : : * @note It is the callers responsibility to free the list. */
932 : : CommodityList * gnc_commodity_table_get_quotable_commodities(
933 : : const gnc_commodity_table * table);
934 : :
935 : : /** Call a function once for each commodity in the commodity table.
936 : : * This table walk returns whenever the end of the table is reached,
937 : : * or the function returns FALSE.
938 : : *
939 : : * @param table A pointer to the commodity table
940 : : *
941 : : * @param f The function to call for each commodity.
942 : : *
943 : : * @param user_data A pointer that is passed into the function
944 : : * unchanged by the table walk routine. */
945 : : gboolean gnc_commodity_table_foreach_commodity(const gnc_commodity_table * table,
946 : : gboolean (*f)(gnc_commodity *cm,
947 : : gpointer user_data),
948 : : gpointer user_data);
949 : : /** @} */
950 : :
951 : :
952 : : /* ---------------------------------------------------------- */
953 : : /** @name Commodity Table Private/Internal-Use Only Routines
954 : : @{
955 : : */
956 : :
957 : : /** You probably shouldn't be using gnc_commodity_table_new() directly,
958 : : * it's for internal use only. You should probably be using
959 : : * gnc_commodity_table_get_table()
960 : : */
961 : : gnc_commodity_table * gnc_commodity_table_new(void);
962 : : void gnc_commodity_table_destroy(gnc_commodity_table * table);
963 : :
964 : : /** Given the commodity 'findlike', this routine will find and return the
965 : : * equivalent commodity (commodity with the same 'unique name') in
966 : : * the indicated book. This routine is primarily useful for setting
967 : : * up clones of things across multiple books.
968 : : */
969 : : gnc_commodity * gnc_commodity_obtain_twin (const gnc_commodity *findlike, QofBook *book);
970 : :
971 : : /** You should probably not be using gnc_commodity_table_register()
972 : : * It is an internal routine for registering the gncObject for the
973 : : * commodity table.
974 : : */
975 : : gboolean gnc_commodity_table_register (void);
976 : :
977 : : void gnc_commodity_begin_edit (gnc_commodity *cm);
978 : : void gnc_commodity_commit_edit (gnc_commodity *cm);
979 : :
980 : : /** Get the internal KVP from of the currency.
981 : : * You should rather use the individual accessors for individual properties
982 : : */
983 : : #define gnc_commodity_get_kvp_frame(cm) \
984 : : qof_instance_get_slots(QOF_INSTANCE(cm))
985 : :
986 : : /** @} */
987 : :
988 : : /** @name Monetary value, commodity identity and numeric value
989 : : @{
990 : : */
991 : : struct _gnc_monetary
992 : : {
993 : : gnc_commodity *commodity;
994 : : gnc_numeric value;
995 : : };
996 : :
997 : : typedef struct _gnc_monetary gnc_monetary;
998 : :
999 : : /* A list of monetary values. This could be a hash table, but as currently
1000 : : * used it rarely contains more than one or two different commodities so
1001 : : * it doesn't seem worth the trouble.
1002 : : */
1003 : : typedef GList MonetaryList;
1004 : :
1005 : : /** @name Constructors
1006 : : @{
1007 : : Make a gnc_monetary from a gnc_commodity and gnc_numeric */
1008 : : static inline
1009 : 44 : gnc_monetary gnc_monetary_create(gnc_commodity *commod, gnc_numeric val)
1010 : : {
1011 : : gnc_monetary out;
1012 : 44 : out.commodity = commod;
1013 : 44 : out.value = val;
1014 : 44 : return out;
1015 : : }
1016 : : /** @} */
1017 : :
1018 : : /** @name Accessors
1019 : : @{
1020 : : */
1021 : : static inline
1022 : 0 : gnc_commodity * gnc_monetary_commodity(gnc_monetary a)
1023 : : {
1024 : 0 : return a.commodity;
1025 : : }
1026 : :
1027 : : static inline
1028 : 0 : gnc_numeric gnc_monetary_value(gnc_monetary a)
1029 : : {
1030 : 0 : return a.value;
1031 : : }
1032 : : /** @} */
1033 : :
1034 : : /** @name Manipulate MonetaryList lists
1035 : : @{
1036 : : */
1037 : :
1038 : : /** Add a gnc_monetary to the list */
1039 : : MonetaryList *gnc_monetary_list_add_monetary(MonetaryList *list, gnc_monetary mon);
1040 : :
1041 : : /** Add something to the list given a commodity and value */
1042 : : static inline
1043 : 44 : MonetaryList *gnc_monetary_list_add_value(MonetaryList *list,
1044 : : gnc_commodity *commod,
1045 : : gnc_numeric value)
1046 : : {
1047 : 44 : return gnc_monetary_list_add_monetary(list,
1048 : 44 : gnc_monetary_create(commod, value));
1049 : : }
1050 : :
1051 : : /** Delete all the zero-value entries from a list */
1052 : : MonetaryList *gnc_monetary_list_delete_zeros(MonetaryList *list);
1053 : :
1054 : : /** Free a monetary list and all the items it points to */
1055 : : void gnc_monetary_list_free(MonetaryList *list);
1056 : : /** @} */
1057 : :
1058 : : /** @} */
1059 : :
1060 : : #ifdef __cplusplus
1061 : : } /* extern "C" */
1062 : : #endif
1063 : :
1064 : : #endif /* GNC_COMMODITY_H */
1065 : : /** @} */
1066 : : /** @} */
|
