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 : gboolean gnc_commodity_get_auto_quote_control_flag (const gnc_commodity *cm);
323 :
324 : /** Retrieve the mnemonic for the specified commodity. This will be a
325 : * pointer to a null terminated string of the form "ACME", "QWER",
326 : * etc.
327 : *
328 : * @param cm A pointer to a commodity data structure.
329 : *
330 : * @return A pointer to the mnemonic for this commodity. This string
331 : * is owned by the engine and should not be freed by the caller.
332 : */
333 : const char * gnc_commodity_get_mnemonic(const gnc_commodity * cm);
334 :
335 : /** Retrieve the namespace for the specified commodity. This will be
336 : * a pointer to a null terminated string of the form "AMEX",
337 : * "NASDAQ", etc.
338 : *
339 : * @param cm A pointer to a commodity data structure.
340 : *
341 : * @return A pointer to the namespace for this commodity. This string
342 : * is owned by the engine and should not be freed by the caller.
343 : */
344 : const char * gnc_commodity_get_namespace(const gnc_commodity * cm);
345 :
346 : /** Retrieve the namespace data structure for the specified commodity.
347 : * This will be a pointer to another data structure.
348 : *
349 : * @param cm A pointer to a commodity data structure.
350 : *
351 : * @return A pointer to the namespace data structure for this
352 : * commodity.
353 : */
354 : gnc_commodity_namespace *gnc_commodity_get_namespace_ds(const gnc_commodity * cm);
355 :
356 : /** Retrieve the full name for the specified commodity. This will be
357 : * a pointer to a null terminated string of the form "Acme Systems,
358 : * Inc.", etc.
359 : *
360 : * @param cm A pointer to a commodity data structure.
361 : *
362 : * @return A pointer to the full name for this commodity. This string
363 : * is owned by the engine and should not be freed by the caller.
364 : */
365 : const char * gnc_commodity_get_fullname(const gnc_commodity * cm);
366 :
367 : /** Retrieve the 'print' name for the specified commodity. This will
368 : * be a pointer to a null terminated string of the form "Acme
369 : * Systems, Inc. (ACME)", etc.
370 : *
371 : * @param cm A pointer to a commodity data structure.
372 : *
373 : * @return A pointer to the print name for this commodity. This
374 : * string is owned by the engine and should not be freed by the
375 : * caller.
376 : */
377 : const char * gnc_commodity_get_printname(const gnc_commodity * cm);
378 :
379 : /** Retrieve the 'exchange code' for the specified commodity. This
380 : * will be a pointer to a null terminated string of the form
381 : * "AXQ14728", etc. This field is often used when presenting
382 : * information to the user.
383 : *
384 : * @note This is a unique code that specifies a particular item or
385 : * set of shares of a commodity, not a code that specifies a stock
386 : * exchange. That is the namespace field.
387 : *
388 : * @param cm A pointer to a commodity data structure.
389 : *
390 : * @return A pointer to the exchange code for this commodity. This
391 : * string is owned by the engine and should not be freed by the
392 : * caller.
393 : */
394 : const char * gnc_commodity_get_cusip(const gnc_commodity * cm);
395 :
396 : /** Retrieve the 'unique' name for the specified commodity. This will
397 : * be a pointer to a null terminated string of the form "AMEX::ACME",
398 : * etc. This field is often used when performing comparisons or
399 : * other functions invisible to the user.
400 : *
401 : * @param cm A pointer to a commodity data structure.
402 : *
403 : * @return A pointer to the 'unique' name for this commodity. This
404 : * string is owned by the engine and should not be freed by the
405 : * caller.
406 : */
407 : const char * gnc_commodity_get_unique_name(const gnc_commodity * cm);
408 :
409 : /** Retrieve the fraction for the specified commodity. This will be
410 : * an integer value specifying the number of fractional units that
411 : * one of these commodities can be divided into. Should always be a
412 : * power of 10.
413 : *
414 : * @param cm A pointer to a commodity data structure.
415 : *
416 : * @return The number of fractional units that one of these
417 : * commodities can be divided into.
418 : */
419 : int gnc_commodity_get_fraction(const gnc_commodity * cm);
420 :
421 : /** Retrieve the automatic price quote flag for the specified
422 : * commodity. This flag indicates whether stock quotes should be
423 : * retrieved for the specified stock.
424 : *
425 : * @param cm A pointer to a commodity data structure.
426 : *
427 : * @return TRUE if quotes should be pulled for this commodity, FALSE
428 : * otherwise.
429 : */
430 : gboolean gnc_commodity_get_quote_flag(const gnc_commodity *cm);
431 :
432 : /** Retrieve the automatic price quote source for the specified
433 : * commodity. This will be a pointer to a null terminated string of
434 : * the form "Yahoo (Asia)", etc.
435 : *
436 : * @param cm A pointer to a commodity data structure.
437 : *
438 : * @return A pointer to the price quote source for this commodity.
439 : */
440 : /*@ dependent @*/
441 : gnc_quote_source* gnc_commodity_get_quote_source(const gnc_commodity *cm);
442 : /*@ dependent @*/
443 : gnc_quote_source* gnc_commodity_get_default_quote_source(const gnc_commodity *cm);
444 :
445 : /** Retrieve the automatic price quote timezone for the specified
446 : * commodity. This will be a pointer to a null terminated string of
447 : * the form "America/New_York", etc.
448 : *
449 : * @param cm A pointer to a commodity data structure.
450 : *
451 : * @return A pointer to the price quote timezone for this commodity.
452 : * This string is owned by the engine and should not be freed by the
453 : * caller.
454 : */
455 : const char* gnc_commodity_get_quote_tz(const gnc_commodity *cm);
456 :
457 : /** Retrieve the user-defined symbol for the specified commodity. This
458 : * will be a pointer to a nul terminated string like "£", "US$", etc.
459 : *
460 : * @param cm A pointer to a commodity data structure.
461 : *
462 : * @return A pointer to the user-defined symbol for this commodity.
463 : * NULL means that the user didn't define any symbol, and that fallback to
464 : * e.g. the mnemonic is in order. This string is owned by the engine and
465 : * should not be freed by the caller.
466 : */
467 : const char* gnc_commodity_get_user_symbol(const gnc_commodity *cm);
468 :
469 : /** Retrieve the default symbol for the specified commodity. This will
470 : * be a pointer to a nul terminated string like "£", "US$", etc. Note
471 : * that for the locale currency, you probably want to look at the
472 : * system-provided symbol first. See gnc_commodity_get_nice_symbol.
473 : *
474 : * @param cm A pointer to a commodity data structure.
475 : *
476 : * @return A pointer to the default symbol for this commodity.
477 : */
478 : const char* gnc_commodity_get_default_symbol(const gnc_commodity *cm);
479 :
480 : /** Retrieve a symbol for the specified commodity, suitable for
481 : * display to the user. This will be a pointer to a nul terminated
482 : * string like "£", "US$", etc. That function is locale-aware and
483 : * will base its choice of symbol on the user-configured symbol,
484 : * the locale a
485 : *
486 : * @param cm A pointer to a commodity data structure.
487 : *
488 : * @return A pointer to the symbol for this commodity.
489 : */
490 : const char*gnc_commodity_get_nice_symbol(const gnc_commodity *cm);
491 : /** @} */
492 :
493 : /** @name Commodity Accessor Routines - Set
494 : @{
495 : */
496 :
497 : void gnc_commodity_set_auto_quote_control_flag (gnc_commodity *cm, const gboolean flag);
498 :
499 : /** Set the mnemonic for the specified commodity. This should be a
500 : * pointer to a null terminated string of the form "ACME", "QWER",
501 : * etc.
502 : *
503 : * @param cm A pointer to a commodity data structure.
504 : *
505 : * @param mnemonic A pointer to the mnemonic for this commodity.
506 : * This string belongs to the caller and will be duplicated by the
507 : * engine.
508 : */
509 : void gnc_commodity_set_mnemonic(gnc_commodity * cm, const char * mnemonic);
510 :
511 : /** Set the namespace for the specified commodity. This should be a
512 : * pointer to a null terminated string of the form "AMEX", "NASDAQ",
513 : * etc.
514 : *
515 : * @param cm A pointer to a commodity data structure.
516 : *
517 : * @param new_namespace A pointer to the namespace for this commodity.
518 : * This string belongs to the caller and will be duplicated by the
519 : * engine.
520 : */
521 : void gnc_commodity_set_namespace(gnc_commodity * cm, const char * new_namespace);
522 :
523 : /** Set the full name for the specified commodity. This should be
524 : * a pointer to a null terminated string of the form "Acme Systems,
525 : * Inc.", etc.
526 : *
527 : * @param cm A pointer to a commodity data structure.
528 : *
529 : * @param fullname A pointer to the full name for this commodity.
530 : * This string belongs to the caller and will be duplicated by the
531 : * engine.
532 : */
533 : void gnc_commodity_set_fullname(gnc_commodity * cm, const char * fullname);
534 :
535 : /** Set the 'exchange code' for the specified commodity. This should
536 : * be a pointer to a null terminated string of the form "AXQ14728",
537 : * etc.
538 : *
539 : * @note This is a unique code that specifies a particular item or
540 : * set of shares of a commodity, not a code that specifies a stock
541 : * exchange. That is the namespace field.
542 : *
543 : * @param cm A pointer to a commodity data structure.
544 : *
545 : * @param cusip A pointer to the cusip or other exchange specific
546 : * data for this commodity. This string belongs to the caller and
547 : * will be duplicated by the engine.
548 : */
549 : void gnc_commodity_set_cusip(gnc_commodity * cm, const char * cusip);
550 :
551 : /** Set the fraction for the specified commodity. This should be
552 : * an integer value specifying the number of fractional units that
553 : * one of these commodities can be divided into. Should always be a
554 : * power of 10.
555 : *
556 : * @param cm A pointer to a commodity data structure.
557 : *
558 : * @param smallest_fraction The number of fractional units that one of
559 : * these commodities can be divided into.
560 : */
561 : void gnc_commodity_set_fraction(gnc_commodity * cm, int smallest_fraction);
562 :
563 : /** Set the automatic price quote flag for the specified commodity,
564 : * based on user input. This flag indicates whether stock quotes
565 : * should be retrieved for the specified stock.
566 : *
567 : * It is necessary to have a separate function to distinguish when
568 : * this setting is being modified by a user so that the
569 : * auto-enabling/auto-disabling of currencies can be handled
570 : * properly.
571 : *
572 : * @param cm A pointer to a commodity data structure.
573 : *
574 : * @param flag TRUE if quotes should be pulled for this commodity, FALSE
575 : * otherwise.
576 : */
577 : void gnc_commodity_user_set_quote_flag(gnc_commodity *cm,
578 : const gboolean flag);
579 :
580 : /** Set the automatic price quote flag for the specified commodity.
581 : * This flag indicates whether stock quotes should be retrieved for
582 : * the specified stock.
583 : *
584 : * @param cm A pointer to a commodity data structure.
585 : *
586 : * @param flag TRUE if quotes should be pulled for this commodity, FALSE
587 : * otherwise.
588 : */
589 : void gnc_commodity_set_quote_flag(gnc_commodity *cm, const gboolean flag);
590 :
591 : /** Set the automatic price quote source for the specified commodity.
592 : * This should be a pointer to a null terminated string of the form
593 : * "Yahoo (Asia)", etc. Legal values can be found in the
594 : * quote_sources array in the file gnc-ui-util.c.
595 : *
596 : * @param cm A pointer to a commodity data structure.
597 : *
598 : * @param src A pointer to the price quote source for this commodity.
599 : */
600 : void gnc_commodity_set_quote_source(gnc_commodity *cm, gnc_quote_source *src);
601 :
602 : /** Set the automatic price quote timezone for the specified
603 : * commodity. This should be a pointer to a null terminated string
604 : * of the form "America/New_York", etc. Legal values can be found in
605 : * the known_timezones array in the file src/gnome-utils/dialog-commodity.c.
606 : *
607 : * @param cm A pointer to a commodity data structure.
608 : *
609 : * @param tz A pointer to the price quote timezone for this commodity.
610 : * This string belongs to the caller and will be duplicated by the
611 : * engine.
612 : */
613 : void gnc_commodity_set_quote_tz(gnc_commodity *cm, const char *tz);
614 :
615 : /** Set a user-defined symbol for the specified commodity. This should
616 : * be a pointer to a nul terminated string like "£", "US$", etc.
617 : *
618 : * @param cm A pointer to a commodity data structure.
619 : *
620 : * @param tz A pointer to the symbol for this commodity. This string
621 : * belongs to the caller and will be duplicated by the engine.
622 : */
623 : void gnc_commodity_set_user_symbol(gnc_commodity *cm, const char *user_symbol);
624 : /** @} */
625 :
626 : /** @name Commodity Usage Count Adjustment Routines
627 : @{
628 : */
629 :
630 : /** Increment a commodity's internal counter that tracks how many
631 : * accounts are using that commodity. For currencies, this may have
632 : * the side effect of enabling the commodity's quote flag.
633 : *
634 : * @param cm A pointer to a commodity data structure.
635 : */
636 : void
637 : gnc_commodity_increment_usage_count(gnc_commodity *cm);
638 :
639 : /** Decrement a commodity's internal counter that tracks how many
640 : * accounts are using that commodity. For currencies, this may have
641 : * the side effect of disabling the commodity's quote flag.
642 : *
643 : * @param cm A pointer to a commodity data structure.
644 : */
645 : void
646 : gnc_commodity_decrement_usage_count(gnc_commodity *cm);
647 : /** @} */
648 :
649 :
650 : /** @name Commodity Comparison
651 : @{
652 : */
653 :
654 : /** This routine returns TRUE if the two commodities are equivalent.
655 : * Commodities are equivalent if they have the same namespace and
656 : * mnemonic. Equivalent commodities may belong to different
657 : * exchanges, may have different fullnames, and may have different
658 : * fractions.
659 : */
660 : gboolean gnc_commodity_equiv(const gnc_commodity * a, const gnc_commodity * b);
661 :
662 : /** This routine returns TRUE if the two commodities are equal.
663 : * Commodities are equal if they have the same namespace, mnemonic,
664 : * fullname, exchange private code and fraction.
665 : */
666 : gboolean gnc_commodity_equal(const gnc_commodity * a, const gnc_commodity * b);
667 :
668 : /** This routine returns 0 if the two commodities are equal, 1 otherwise.
669 : * Commodities are equal if they have the same namespace, mnemonic,
670 : * fullname, exchange private code and fraction.
671 : * This function is useful for list-traversal comparison purposes where
672 : * The semantics are 0, <0, or >0 (equal, greater than, less than) rather
673 : * than "true or false"
674 : */
675 : int gnc_commodity_compare(const gnc_commodity * a, const gnc_commodity * b);
676 :
677 : /** A wrapper around gnc_commodity_compare() which offers the function
678 : * declaration that is needed for g_list_find_custom(), which needs
679 : * void pointers instead of gnc_commodity ones.
680 : */
681 : int gnc_commodity_compare_void(const void * a, const void * b);
682 : /** @} */
683 :
684 :
685 : /** @name Currency Checks
686 : @{
687 : */
688 :
689 : /** Checks to see if the specified commodity namespace is the
690 : * namespace for ISO 4217 currencies.
691 : *
692 : * @param commodity_namespace The string to check.
693 : *
694 : * @return TRUE if the string indicates an ISO currency, FALSE otherwise. */
695 : gboolean gnc_commodity_namespace_is_iso(const char *commodity_namespace);
696 :
697 : /** Checks to see if the specified commodity is an ISO 4217 recognized currency.
698 : *
699 : * @param cm The commodity to check.
700 : *
701 : * @return TRUE if the commodity represents a currency, FALSE otherwise. */
702 : gboolean gnc_commodity_is_iso(const gnc_commodity * cm);
703 :
704 : /** Checks to see if the specified commodity is an ISO 4217 recognized
705 : * currency or a legacy currency.
706 : *
707 : * @param cm The commodity to check.
708 : *
709 : * @return TRUE if the commodity represents a currency, FALSE otherwise. */
710 : gboolean gnc_commodity_is_currency(const gnc_commodity *cm);
711 :
712 : /** @} */
713 :
714 :
715 : /* =============================================================== */
716 : /** @name Commodity Table
717 : @{
718 : */
719 :
720 : /** Returns the commodity table associated with a book.
721 : */
722 : /*@ dependent @*/
723 : gnc_commodity_table * gnc_commodity_table_get_table(QofBook *book);
724 :
725 : /** @} */
726 : /* ---------------------------------------------------------- */
727 : /** @name Commodity Table Lookup functions
728 : @{
729 : */
730 : gnc_commodity * gnc_commodity_table_lookup(const gnc_commodity_table * table,
731 : const char * commodity_namespace,
732 : const char * mnemonic);
733 : gnc_commodity *
734 : gnc_commodity_table_lookup_unique(const gnc_commodity_table *table,
735 : const char * unique_name);
736 : gnc_commodity * gnc_commodity_table_find_full(const gnc_commodity_table * t,
737 : const char * commodity_namespace,
738 : const char * fullname);
739 :
740 : /*@ dependent @*/
741 : gnc_commodity * gnc_commodity_find_commodity_by_guid(const GncGUID *guid,
742 : QofBook *book);
743 :
744 : /** @} */
745 : /* ---------------------------------------------------------- */
746 :
747 : /** @name Commodity Table Maintenance functions
748 : @{
749 : */
750 :
751 : /** Add a new commodity to the commodity table. This routine handles
752 : * the cases where the commodity already exists in the database (does
753 : * nothing), or another entries has the same namespace and mnemonic
754 : * (updates the existing entry).
755 : *
756 : * @param table A pointer to the commodity table
757 : *
758 : * @param comm A pointer to the commodity to add.
759 : *
760 : * @return The added commodity. Null on error.
761 : *
762 : * @note The commodity pointer passed to this function should not be
763 : * used after its return, as it may have been destroyed. Use the
764 : * return value which is guaranteed to be valid. */
765 : /*@ dependent @*/
766 : gnc_commodity * gnc_commodity_table_insert(gnc_commodity_table * table,
767 : gnc_commodity * comm);
768 :
769 : /** Remove a commodity from the commodity table. If the commodity to
770 : * remove doesn't exist, nothing happens.
771 : *
772 : * @param table A pointer to the commodity table
773 : *
774 : * @param comm A pointer to the commodity to remove. */
775 : void gnc_commodity_table_remove(gnc_commodity_table * table,
776 : gnc_commodity * comm);
777 :
778 : /** Add all the standard namespaces and currencies to the commodity
779 : * table. This routine creates the namespaces for the NYSE, NASDAQ,
780 : * etc. It also adds all of the ISO 4217 currencies to the commodity
781 : * table.
782 : *
783 : * @param table A pointer to the commodity table.
784 : *
785 : * @param book Unused. */
786 : gboolean gnc_commodity_table_add_default_data(gnc_commodity_table *table, QofBook *book);
787 :
788 : /** @} */
789 : /* ---------------------------------------------------------- */
790 : /** @name Commodity Table Namespace functions
791 : @{
792 : */
793 :
794 : /** Return the textual name of a namespace data structure.
795 : *
796 : * @param ns A pointer to the namespace data structure.
797 : *
798 : * @return A pointer to the name of the namespace. This string is
799 : * owned by the engine and should not be freed by the caller. */
800 : const char * gnc_commodity_namespace_get_name (const gnc_commodity_namespace *ns) ;
801 :
802 : /** Return the textual name of a namespace data structure in a form suitable to
803 : * present to the user.
804 : *
805 : * @param ns A pointer to the namespace data structure.
806 : *
807 : * @return A pointer to the gui friendly name of the namespace. This string is
808 : * owned by the engine and should not be freed by the caller.
809 : *
810 : * @notes The returned string is marked for translation, but not translated yet.
811 : * If you want it translated pass the return value on to gettext.
812 : */
813 : const char * gnc_commodity_namespace_get_gui_name (const gnc_commodity_namespace *ns) ;
814 :
815 :
816 : /** Return a list of all commodity data structures in the specified namespace.
817 : *
818 : * @return A pointer to the list of structures. NULL if an invalid
819 : * argument was supplied.
820 : *
821 : * @note This list is owned by the caller who must free the list. */
822 : GList * gnc_commodity_namespace_get_commodity_list(const gnc_commodity_namespace * ns);
823 :
824 :
825 : /** Test to see if the indicated namespace exits in the commodity table.
826 : *
827 : * @param table A pointer to the commodity table
828 : *
829 : * @param commodity_namespace The new namespace to check.
830 : *
831 : * @return 1 if the namespace exists. 0 if it doesn't exist, or the
832 : * routine was passed a bad argument. */
833 : int gnc_commodity_table_has_namespace(const gnc_commodity_table * table,
834 : const char * commodity_namespace);
835 :
836 : /** Return a list of all namespaces in the commodity table. This
837 : * returns both system and user defined namespaces.
838 : *
839 : * @return A pointer to the list of names. NULL if an invalid
840 : * argument was supplied.
841 : *
842 : * @note It is the callers responsibility to free the list. */
843 : GList * gnc_commodity_table_get_namespaces(const gnc_commodity_table * t);
844 :
845 : /** Return a list of all namespace data structures in the commodity table. This
846 : * returns both system and user defined namespace structures.
847 : *
848 : * @return A pointer to the list of structures. NULL if an invalid
849 : * argument was supplied.
850 : *
851 : * @note This list is owned by the caller who must free the list. */
852 : GList * gnc_commodity_table_get_namespaces_list(const gnc_commodity_table * t);
853 :
854 : /** This function adds a new string to the list of commodity namespaces.
855 : * If the new namespace already exists, nothing happens.
856 : *
857 : * @param table A pointer to the commodity table
858 : *
859 : * @param commodity_namespace The new namespace to be added.
860 : *
861 : * @param book The book that the new namespace will belong to.
862 : *
863 : * @return A pointer to the newly created namespace. */
864 : gnc_commodity_namespace * gnc_commodity_table_add_namespace(gnc_commodity_table * table,
865 : const char * commodity_namespace,
866 : QofBook *book);
867 :
868 : /** This function finds a commodity namespace in the set of existing commodity namespaces.
869 : *
870 : * @param table A pointer to the commodity table
871 : *
872 : * @param commodity_namespace The new namespace to be added.
873 : *
874 : * @return The a pointer to the namespace found, or NULL if the
875 : * namespace doesn't exist. */
876 : gnc_commodity_namespace * gnc_commodity_table_find_namespace(const gnc_commodity_table * table,
877 : const char * commodity_namespace);
878 :
879 : /** This function deletes a string from the list of commodity namespaces.
880 : * If the namespace does not exist, nothing happens.
881 : *
882 : * @param table A pointer to the commodity table
883 : *
884 : * @param commodity_namespace The namespace to be deleted.
885 : *
886 : * @note This routine will destroy any commodities that exist as part
887 : * of this namespace. Use it carefully. */
888 : void gnc_commodity_table_delete_namespace(gnc_commodity_table * table,
889 : const char * commodity_namespace);
890 : /** @} */
891 : /* ---------------------------------------------------------- */
892 : /** @name Commodity Table Accessor functions
893 : @{
894 : */
895 :
896 : /** Returns the number of commodities in the commodity table.
897 : *
898 : * @param tbl A pointer to the commodity table
899 : *
900 : * @return The number of commodities in the table. 0 if there are no
901 : * commodities, or the routine was passed a bad argument. */
902 : guint gnc_commodity_table_get_size(const gnc_commodity_table* tbl);
903 :
904 : /** Return a list of all commodities in the commodity table that are
905 : * in the given namespace.
906 : *
907 : * @param table A pointer to the commodity table
908 : *
909 : * @param commodity_namespace A string indicating which commodities should be
910 : * returned. It is a required argument.
911 : *
912 : * @return A pointer to the list of commodities. NULL if an invalid
913 : * argument was supplied, or the namespace could not be found.
914 : *
915 : * @note It is the callers responsibility to free the list. */
916 : CommodityList * gnc_commodity_table_get_commodities(
917 : const gnc_commodity_table * table, const char * commodity_namespace);
918 :
919 : /** This function returns a list of commodities for which price quotes
920 : * should be retrieved. It will scan the entire commodity table (or
921 : * a subset) and check each commodity to see if the price_quote_flag
922 : * field has been set. All matching commodities are queued onto a
923 : * list, and the head of that list is returned. Use the command-line
924 : * given expression as a filter on the commodities to be returned. If
925 : * non-null, only commodities in namespace that match the specified
926 : * regular expression are checked. If none was given, all
927 : * commodities are checked.
928 : *
929 : * @param table A pointer to the commodity table
930 : *
931 : * @return A pointer to a list of commodities. NULL if invalid
932 : * arguments were supplied or if there no commodities are flagged for
933 : * quote retrieval.
934 : *
935 : * @note It is the callers responsibility to free the list. */
936 : CommodityList * gnc_commodity_table_get_quotable_commodities(
937 : const gnc_commodity_table * table);
938 :
939 : /** Call a function once for each commodity in the commodity table.
940 : * This table walk returns whenever the end of the table is reached,
941 : * or the function returns FALSE.
942 : *
943 : * @param table A pointer to the commodity table
944 : *
945 : * @param f The function to call for each commodity.
946 : *
947 : * @param user_data A pointer that is passed into the function
948 : * unchanged by the table walk routine. */
949 : gboolean gnc_commodity_table_foreach_commodity(const gnc_commodity_table * table,
950 : gboolean (*f)(gnc_commodity *cm,
951 : gpointer user_data),
952 : gpointer user_data);
953 : /** @} */
954 :
955 :
956 : /* ---------------------------------------------------------- */
957 : /** @name Commodity Table Private/Internal-Use Only Routines
958 : @{
959 : */
960 :
961 : /** You probably shouldn't be using gnc_commodity_table_new() directly,
962 : * it's for internal use only. You should probably be using
963 : * gnc_commodity_table_get_table()
964 : */
965 : gnc_commodity_table * gnc_commodity_table_new(void);
966 : void gnc_commodity_table_destroy(gnc_commodity_table * table);
967 :
968 : /** Given the commodity 'findlike', this routine will find and return the
969 : * equivalent commodity (commodity with the same 'unique name') in
970 : * the indicated book. This routine is primarily useful for setting
971 : * up clones of things across multiple books.
972 : */
973 : gnc_commodity * gnc_commodity_obtain_twin (const gnc_commodity *findlike, QofBook *book);
974 :
975 : /** You should probably not be using gnc_commodity_table_register()
976 : * It is an internal routine for registering the gncObject for the
977 : * commodity table.
978 : */
979 : gboolean gnc_commodity_table_register (void);
980 :
981 : void gnc_commodity_begin_edit (gnc_commodity *cm);
982 : void gnc_commodity_commit_edit (gnc_commodity *cm);
983 :
984 : /** Get the internal KVP from of the currency.
985 : * You should rather use the individual accessors for individual properties
986 : */
987 : #define gnc_commodity_get_kvp_frame(cm) \
988 : qof_instance_get_slots(QOF_INSTANCE(cm))
989 :
990 : /** @} */
991 :
992 : /** @name Monetary value, commodity identity and numeric value
993 : @{
994 : */
995 : struct _gnc_monetary
996 : {
997 : gnc_commodity *commodity;
998 : gnc_numeric value;
999 : };
1000 :
1001 : typedef struct _gnc_monetary gnc_monetary;
1002 :
1003 : /* A list of monetary values. This could be a hash table, but as currently
1004 : * used it rarely contains more than one or two different commodities so
1005 : * it doesn't seem worth the trouble.
1006 : */
1007 : typedef GList MonetaryList;
1008 :
1009 : /** @name Constructors
1010 : @{
1011 : Make a gnc_monetary from a gnc_commodity and gnc_numeric */
1012 : static inline
1013 44 : gnc_monetary gnc_monetary_create(gnc_commodity *commod, gnc_numeric val)
1014 : {
1015 : gnc_monetary out;
1016 44 : out.commodity = commod;
1017 44 : out.value = val;
1018 44 : return out;
1019 : }
1020 : /** @} */
1021 :
1022 : /** @name Accessors
1023 : @{
1024 : */
1025 : static inline
1026 0 : gnc_commodity * gnc_monetary_commodity(gnc_monetary a)
1027 : {
1028 0 : return a.commodity;
1029 : }
1030 :
1031 : static inline
1032 0 : gnc_numeric gnc_monetary_value(gnc_monetary a)
1033 : {
1034 0 : return a.value;
1035 : }
1036 : /** @} */
1037 :
1038 : /** @name Manipulate MonetaryList lists
1039 : @{
1040 : */
1041 :
1042 : /** Add a gnc_monetary to the list */
1043 : MonetaryList *gnc_monetary_list_add_monetary(MonetaryList *list, gnc_monetary mon);
1044 :
1045 : /** Add something to the list given a commodity and value */
1046 : static inline
1047 44 : MonetaryList *gnc_monetary_list_add_value(MonetaryList *list,
1048 : gnc_commodity *commod,
1049 : gnc_numeric value)
1050 : {
1051 44 : return gnc_monetary_list_add_monetary(list,
1052 44 : gnc_monetary_create(commod, value));
1053 : }
1054 :
1055 : /** Delete all the zero-value entries from a list */
1056 : MonetaryList *gnc_monetary_list_delete_zeros(MonetaryList *list);
1057 :
1058 : /** Free a monetary list and all the items it points to */
1059 : void gnc_monetary_list_free(MonetaryList *list);
1060 : /** @} */
1061 :
1062 : /** @} */
1063 :
1064 : #ifdef __cplusplus
1065 : } /* extern "C" */
1066 : #endif
1067 :
1068 : #endif /* GNC_COMMODITY_H */
1069 : /** @} */
1070 : /** @} */
|
