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 : : 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 : : /** @} */
|
