Commodities
[GnuCash Engine: Core, Non-GUI Accounting Functions]

---

Detailed Description

A commodity is something of value that is easily tradeable or sellable; for example, currencies, stocks, bonds, grain, copper, and oil are all commodities. This file provides an API for defining a commodities, and for working with collections of commodities. All GnuCash financial transactions must identify the commodity that is being traded.

Warning:

The system used here does not follow the object handling and identification system (GUID's, Entities, etc.) that the other parts of GnuCash use. The API really should be ported over. This would allow us to get rid of the commodity table routines defined below.

Files
file	gnc-commodity.h
	Commodity handling public routines.
Commodity Quote Source functions
enum	QuoteSourceType {   SOURCE_SINGLE = 0, SOURCE_MULTI, SOURCE_UNKNOWN, SOURCE_MAX,   SOURCE_CURRENCY = SOURCE_MAX }
gboolean	gnc_quote_source_fq_installed (void)
void	gnc_quote_source_set_fq_installed (const GList *sources_list)
gint	gnc_quote_source_num_entries (QuoteSourceType type)
gnc_quote_source *	gnc_quote_source_add_new (const char *name, gboolean supported)
gnc_quote_source *	gnc_quote_source_lookup_by_internal (const char *internal_name)
gnc_quote_source *	gnc_quote_source_lookup_by_ti (QuoteSourceType type, gint index)
gboolean	gnc_quote_source_get_supported (const gnc_quote_source *source)
QuoteSourceType	gnc_quote_source_get_type (const gnc_quote_source *source)
gint	gnc_quote_source_get_index (const gnc_quote_source *source)
const char *	gnc_quote_source_get_user_name (const gnc_quote_source *source)
const char *	gnc_quote_source_get_internal_name (const gnc_quote_source *source)
const char *	gnc_quote_source_get_old_internal_name (const gnc_quote_source *source)
Commodity Creation
gnc_commodity *	gnc_commodity_new (QofBook *book, const char *fullname, const char *namespace, const char *mnemonic, const char *cusip, int fraction)
void	gnc_commodity_destroy (gnc_commodity *cm)
void	gnc_commodity_copy (gnc_commodity *dest, const gnc_commodity *src)
gnc_commodity *	gnc_commodity_clone (const gnc_commodity *src, QofBook *dest_book)
Commodity Accessor Routines - Get
const char *	gnc_commodity_get_mnemonic (const gnc_commodity *cm)
const char *	gnc_commodity_get_namespace (const gnc_commodity *cm)
const char *	gnc_commodity_get_namespace_compat (const gnc_commodity *cm)
gnc_commodity_namespace *	gnc_commodity_get_namespace_ds (const gnc_commodity *cm)
const char *	gnc_commodity_get_fullname (const gnc_commodity *cm)
const char *	gnc_commodity_get_printname (const gnc_commodity *cm)
const char *	gnc_commodity_get_cusip (const gnc_commodity *cm)
const char *	gnc_commodity_get_unique_name (const gnc_commodity *cm)
int	gnc_commodity_get_fraction (const gnc_commodity *cm)
gint16	gnc_commodity_get_mark (const gnc_commodity *cm)
gboolean	gnc_commodity_get_quote_flag (const gnc_commodity *cm)
gnc_quote_source *	gnc_commodity_get_quote_source (const gnc_commodity *cm)
gnc_quote_source *	gnc_commodity_get_default_quote_source (const gnc_commodity *cm)
const char *	gnc_commodity_get_quote_tz (const gnc_commodity *cm)
Commodity Accessor Routines - Set
void	gnc_commodity_set_mnemonic (gnc_commodity *cm, const char *mnemonic)
void	gnc_commodity_set_namespace (gnc_commodity *cm, const char *namespace)
void	gnc_commodity_set_fullname (gnc_commodity *cm, const char *fullname)
void	gnc_commodity_set_cusip (gnc_commodity *cm, const char *cusip)
void	gnc_commodity_set_fraction (gnc_commodity *cm, int smallest_fraction)
void	gnc_commodity_user_set_quote_flag (gnc_commodity *cm, const gboolean flag)
void	gnc_commodity_set_quote_flag (gnc_commodity *cm, const gboolean flag)
void	gnc_commodity_set_quote_source (gnc_commodity *cm, gnc_quote_source *src)
void	gnc_commodity_set_quote_tz (gnc_commodity *cm, const char *tz)
Commodity Usage Count Adjustment Routines
void	gnc_commodity_increment_usage_count (gnc_commodity *cm)
void	gnc_commodity_decrement_usage_count (gnc_commodity *cm)
Commodity Comparison
gboolean	gnc_commodity_equiv (const gnc_commodity *a, const gnc_commodity *b)
gboolean	gnc_commodity_equal (const gnc_commodity *a, const gnc_commodity *b)
Currency Checks
gboolean	gnc_commodity_namespace_is_iso (const char *namespace)
gboolean	gnc_commodity_is_iso (const gnc_commodity *cm)
gboolean	gnc_commodity_is_currency (const gnc_commodity *cm)
Commodity Table
gnc_commodity_table *	gnc_commodity_table_get_table (QofBook *book)
gboolean	gnc_commodity_table_equal (gnc_commodity_table *t_1, gnc_commodity_table *t_2)
void	gnc_commodity_table_copy (gnc_commodity_table *dest, gnc_commodity_table *src, QofBook *dest_book)
#define	gnc_book_get_commodity_table   gnc_commodity_table_get_table
Commodity Table Lookup functions
gnc_commodity *	gnc_commodity_table_lookup (const gnc_commodity_table *table, const char *namespace, const char *mnemonic)
gnc_commodity *	gnc_commodity_table_lookup_unique (const gnc_commodity_table *table, const char *unique_name)
gnc_commodity *	gnc_commodity_table_find_full (const gnc_commodity_table *t, const char *namespace, const char *fullname)
gnc_commodity *	gnc_commodity_find_commodity_by_guid (const GUID *guid, QofBook *book)
gnc_commodity_namespace *	gnc_commodity_find_namespace_by_guid (const GUID *guid, QofBook *book)
Commodity Table Maintenance functions
gnc_commodity *	gnc_commodity_table_insert (gnc_commodity_table *table, gnc_commodity *comm)
void	gnc_commodity_table_remove (gnc_commodity_table *table, gnc_commodity *comm)
gboolean	gnc_commodity_table_add_default_data (gnc_commodity_table *table, QofBook *book)
Commodity Table Namespace functions
const char *	gnc_commodity_namespace_get_name (const gnc_commodity_namespace *ns)
GList *	gnc_commodity_namespace_get_commodity_list (const gnc_commodity_namespace *ns)
guint	gnc_commodity_table_get_number_of_namespaces (const gnc_commodity_table *tbl)
int	gnc_commodity_table_has_namespace (const gnc_commodity_table *table, const char *namespace)
GList *	gnc_commodity_table_get_namespaces (const gnc_commodity_table *t)
GList *	gnc_commodity_table_get_namespaces_list (const gnc_commodity_table *t)
gnc_commodity_namespace *	gnc_commodity_table_add_namespace (gnc_commodity_table *table, const char *namespace, QofBook *book)
gnc_commodity_namespace *	gnc_commodity_table_find_namespace (const gnc_commodity_table *table, const char *namespace)
void	gnc_commodity_table_delete_namespace (gnc_commodity_table *table, const char *namespace)
Commodity Table Accessor functions
guint	gnc_commodity_table_get_size (const gnc_commodity_table *tbl)
CommodityList *	gnc_commodity_table_get_commodities (const gnc_commodity_table *table, const char *namespace)
CommodityList *	gnc_commodity_table_get_quotable_commodities (const gnc_commodity_table *table)
gboolean	gnc_commodity_table_foreach_commodity (const gnc_commodity_table *table, gboolean(*f)(gnc_commodity *cm, gpointer user_data), gpointer user_data)
Commodity Table Private/Internal-Use Only Routines
void	gnc_commodity_set_mark (gnc_commodity *cm, gint16 mark)
gnc_commodity_table *	gnc_commodity_table_new (void)
void	gnc_commodity_table_destroy (gnc_commodity_table *table)
gnc_commodity *	gnc_commodity_obtain_twin (const gnc_commodity *from, QofBook *book)
gboolean	gnc_commodity_table_register (void)
void	gnc_commodity_begin_edit (gnc_commodity *cm)
void	gnc_commodity_commit_edit (gnc_commodity *cm)
Defines
#define	GNC_TYPE_COMMODITY   (gnc_commodity_get_type ())
#define	GNC_COMMODITY(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_COMMODITY, gnc_commodity))
#define	GNC_COMMODITY_CLASS(k)   (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_COMMODITY, gnc_commodityClass))
#define	GNC_IS_COMMODITY(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_COMMODITY))
#define	GNC_IS_COMMODITY_CLASS(k)   (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_COMMODITY))
#define	GNC_COMMODITY_GET_CLASS(o)   (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_COMMODITY, gnc_commodityClass))
#define	GNC_TYPE_COMMODITY_NAMESPACE   (gnc_commodity_namespace_get_type ())
#define	GNC_COMMODITY_NAMESPACE(o)   (G_TYPE_CHECK_INSTANCE_CAST ((o), GNC_TYPE_COMMODITY_NAMESPACE, gnc_commodity_namespace))
#define	GNC_COMMODITY_NAMESPACE_CLASS(k)   (G_TYPE_CHECK_CLASS_CAST((k), GNC_TYPE_COMMODITY_NAMESPACE, gnc_commodity_namespaceClass))
#define	GNC_IS_COMMODITY_NAMESPACE(o)   (G_TYPE_CHECK_INSTANCE_TYPE ((o), GNC_TYPE_COMMODITY_NAMESPACE))
#define	GNC_IS_COMMODITY_NAMESPACE_CLASS(k)   (G_TYPE_CHECK_CLASS_TYPE ((k), GNC_TYPE_COMMODITY_NAMESPACE))
#define	GNC_COMMODITY_NAMESPACE_GET_CLASS(o)   (G_TYPE_INSTANCE_GET_CLASS ((o), GNC_TYPE_COMMODITY_NAMESPACE, gnc_commodity_namespaceClass))
#define	GNC_COMMODITY_TABLE   "gnc_commodity_table"
#define	GNC_COMMODITY_NS_LEGACY   "GNC_LEGACY_CURRENCIES"
#define	GNC_COMMODITY_NS_ISO   "ISO4217"
#define	GNC_COMMODITY_NS_CURRENCY   "CURRENCY"
#define	GNC_COMMODITY_NS_NASDAQ   "NASDAQ"
#define	GNC_COMMODITY_NS_NYSE   "NYSE"
#define	GNC_COMMODITY_NS_EUREX   "EUREX"
#define	GNC_COMMODITY_NS_MUTUAL   "FUND"
#define	GNC_COMMODITY_NS_AMEX   "AMEX"
#define	GNC_COMMODITY_NS_ASX   "ASX"
Typedefs
typedef _GncCommodityClass	gnc_commodityClass
typedef _GncCommodityNamespaceClass	gnc_commodity_namespaceClass
typedef GList	CommodityList
Functions
GType	gnc_commodity_get_type (void)
GType	gnc_commodity_namespace_get_type (void)

---

Define Documentation

#define GNC_COMMODITY_NS_LEGACY   "GNC_LEGACY_CURRENCIES"

The commodity namespace definitions are used to tag a commodity by its type, or a stocks by the exchange where it is traded.

The LEGACY name is only used by the file i/o routines, and is converted to another commodity namespace before it is seen by the rest of the system. The ISO namespace represents currencies. With the exception of the NASDAQ namespace (which is used once in the binary importer) the rest of the namespace declarations are only used to populate an option menu in the commodity selection window.

Definition at line 97 of file gnc-commodity.h.

---

Enumeration Type Documentation

enum QuoteSourceType

The quote source type enum account types are used to determine how the transaction data in the account is displayed. These values can be safely changed from one release to the next.

Enumerator:

SOURCE_SINGLE	This quote source pulls from a single specific web site. For example, the yahoo_australia source only pulls from the yahoo web site.
SOURCE_MULTI	This quote source may pull from multiple web sites. For example, the australia source may pull from ASX, yahoo, etc.
SOURCE_UNKNOWN	This is a locally installed quote source that gnucash knows nothing about. May pull from single or multiple locations.
SOURCE_MAX
SOURCE_CURRENCY	The special currency quote source.

Definition at line 118 of file gnc-commodity.h.

{
  SOURCE_SINGLE = 0,    
  SOURCE_MULTI,         
  SOURCE_UNKNOWN,       
  SOURCE_MAX,
  SOURCE_CURRENCY = SOURCE_MAX, 
} QuoteSourceType;

---

Function Documentation

gnc_commodity* gnc_commodity_clone	(	const gnc_commodity *	src,
		QofBook *	dest_book
	)

allocate and copy

Definition at line 661 of file gnc-commodity.c.

{
  gnc_commodity * dest = g_object_new(GNC_TYPE_COMMODITY, NULL);
  qof_instance_init_data (&dest->inst, GNC_ID_COMMODITY, dest_book);

  dest->fullname = CACHE_INSERT(src->fullname);
  dest->mnemonic = CACHE_INSERT(src->mnemonic);
  dest->cusip = CACHE_INSERT(src->cusip);
  dest->quote_tz = CACHE_INSERT(src->quote_tz);

  dest->namespace = src->namespace;

  dest->mark = 0;
  dest->fraction = src->fraction;
  dest->quote_flag = src->quote_flag;

  gnc_commodity_set_quote_source (dest, gnc_commodity_get_quote_source (src));

  kvp_frame_delete (dest->inst.kvp_data);
  dest->inst.kvp_data = kvp_frame_copy (src->inst.kvp_data);

  reset_printname(dest);
  reset_unique_name(dest);

  return dest;
}

void gnc_commodity_copy	(	gnc_commodity *	dest,
		const gnc_commodity *	src
	)

Copy src into dest

Definition at line 647 of file gnc-commodity.c.

{
  gnc_commodity_set_fullname (dest, src->fullname);
  dest->namespace = src->namespace;
  gnc_commodity_set_fraction (dest, src->fraction);
  gnc_commodity_set_cusip (dest, src->cusip);
  gnc_commodity_set_quote_flag (dest, src->quote_flag);
  gnc_commodity_set_quote_source (dest, gnc_commodity_get_quote_source (src));
  gnc_commodity_set_quote_tz (dest, src->quote_tz);
  kvp_frame_delete (dest->inst.kvp_data);
  dest->inst.kvp_data = kvp_frame_copy (src->inst.kvp_data);
}

void gnc_commodity_decrement_usage_count

(

gnc_commodity *

cm

)

Decrement a commodity's internal counter that tracks how many accounts are using that commodity. For currencies, this may have the side effect of disabling the commodity's quote flag.

Parameters:

cm

A pointer to a commodity data structure.

Definition at line 1109 of file gnc-commodity.c.

{
  const char *str;

  ENTER("(cm=%p)", cm);

  if(!cm) {
    LEAVE("");
    return;
  }

  if(cm->usage_count == 0) {
    PWARN("usage_count already zero");
    LEAVE("");
    return;
  }

  cm->usage_count--;
  if((cm->usage_count == 0) && cm->quote_flag
      && gnc_commodity_get_auto_quote_control_flag(cm)
      && gnc_commodity_is_iso(cm)) {
    /* if this is a currency with auto quote control enabled and no more
     * accounts reference this currency, disable quote retrieval */
    gnc_commodity_set_quote_flag(cm, FALSE);
  }
  LEAVE("(usage_count=%d)", cm->usage_count);
}

void gnc_commodity_destroy

(

gnc_commodity *

cm

)

Destroy a commodity. Release all memory attached to this data structure.

Note:

This function does not (can not) check to see if the commodity is referenced anywhere.

Parameters:

cm

The commodity to destroy.

Definition at line 600 of file gnc-commodity.c.

{
  QofBook *book;
  gnc_commodity_table *table;
  if(!cm) return;

  book = qof_instance_get_book(&cm->inst);
  table = gnc_commodity_table_get_table(book);
  gnc_commodity_table_remove(table, cm);

  qof_event_gen (&cm->inst, QOF_EVENT_DESTROY, NULL);

  /* Set at creation */
  CACHE_REMOVE (cm->fullname);
  CACHE_REMOVE (cm->cusip);
  CACHE_REMOVE (cm->mnemonic);
  CACHE_REMOVE (cm->quote_tz);
  cm->namespace = NULL;

  /* Set through accessor functions */
  cm->quote_source = NULL;

  /* Automatically generated */
  g_free(cm->printname);
  cm->printname = NULL;

  g_free(cm->unique_name);
  cm->unique_name = NULL;

  cm->mark = 0;

#ifdef ACCOUNTS_CLEANED_UP
  /* Account objects are not actually cleaned up when a book is closed (in fact
   * a memory leak), but commodities are, so in currently this warning gets hit
   * quite frequently.  Disable the check until cleaning up of accounts objects
   * on close is implemented.  */
  if(cm->usage_count != 0) {
      PWARN("Destroying commodity (%p) with non-zero usage_count (%d).", cm,
              cm->usage_count);
  }
#endif

  /* qof_instance_release (&cm->inst); */
  g_object_unref(cm);
}

gboolean gnc_commodity_equal	(	const gnc_commodity *	a,
		const gnc_commodity *	b
	)

This routine returns TRUE if the two commodities are equal. Commodities are equal if they have the same namespace, mnemonic, fullname, exchange private code and fraction.

Definition at line 1157 of file gnc-commodity.c.

{
  if (a == b) return TRUE;

  if (!a || !b)
  {
    DEBUG ("one is NULL");
    return FALSE;
  }

  if (a->namespace != b->namespace)
  {
    DEBUG ("namespaces differ: %p(%s) vs %p(%s)",
           a->namespace, gnc_commodity_namespace_get_name(a->namespace),
           b->namespace, gnc_commodity_namespace_get_name(b->namespace));
    return FALSE;
  }

  if (safe_strcmp(a->mnemonic, b->mnemonic) != 0)
  {
    DEBUG ("mnemonics differ: %s vs %s", a->mnemonic, b->mnemonic);
    return FALSE;
  }

  if (safe_strcmp(a->fullname, b->fullname) != 0)
  {
    DEBUG ("fullnames differ: %s vs %s", a->fullname, b->fullname);
    return FALSE;
  }

  if (safe_strcmp(a->cusip, b->cusip) != 0)
  {
    DEBUG ("cusips differ: %s vs %s", a->cusip, b->cusip);
    return FALSE;
  }

  if (a->fraction != b->fraction)
  {
    DEBUG ("fractions differ: %d vs %d", a->fraction, b->fraction);
    return FALSE;
  }

  return TRUE;
}

gboolean gnc_commodity_equiv	(	const gnc_commodity *	a,
		const gnc_commodity *	b
	)

This routine returns TRUE if the two commodities are equivalent. Commodities are equivalent if they have the same namespace and mnemonic. Equivalent commodities may belong to different exchanges, may have different fullnames, and may have different fractions.

Definition at line 1147 of file gnc-commodity.c.

{
  if(a == b) return TRUE;
  if(!a || !b) return FALSE;
  if(a->namespace != b->namespace) return FALSE;
  if(safe_strcmp(a->mnemonic, b->mnemonic) != 0) return FALSE;
  return TRUE;
}

const char* gnc_commodity_get_cusip

(

const gnc_commodity *

cm

)

Retrieve the 'exchange code' for the specified commodity. This will be a pointer to a null terminated string of the form "AXQ14728", etc. This field is often used when presenting information to the user.

Note:

This is a unique code that specifies a particular item or set of shares of a commodity, not a code that specifies a stock exchange. That is the namespace field.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the exchange code for this commodity. This string is owned by the engine and should not be freed by the caller.

Definition at line 769 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  return cm->cusip;
}

int gnc_commodity_get_fraction

(

const gnc_commodity *

cm

)

Retrieve the fraction for the specified commodity. This will be an integer value specifying the number of fractional units that one of these commodities can be divided into. Should always be a power of 10.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

The number of fractional units that one of these commodities can be divided into.

Definition at line 780 of file gnc-commodity.c.

{
  if(!cm) return 0;
  return cm->fraction;
}

const char* gnc_commodity_get_fullname

(

const gnc_commodity *

cm

)

Retrieve the full name for the specified commodity. This will be a pointer to a null terminated string of the form "Acme Systems, Inc.", etc.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the full name for this commodity. This string is owned by the engine and should not be freed by the caller.

Definition at line 745 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  return cm->fullname;
}

gint16 gnc_commodity_get_mark

(

const gnc_commodity *

cm

)

Retrieve the 'mark' field for the specified commodity.

Note:

This is a private field used by the Postgres back end.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

The value of the mark field.

Definition at line 791 of file gnc-commodity.c.

{
  if(!cm) return 0;
  return cm->mark;
}

const char* gnc_commodity_get_mnemonic

(

const gnc_commodity *

cm

)

Retrieve the mnemonic for the specified commodity. This will be a pointer to a null terminated string of the form "ACME", "QWER", etc.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the mnemonic for this commodity. This string is owned by the engine and should not be freed by the caller.

Definition at line 693 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  return cm->mnemonic;
}

const char* gnc_commodity_get_namespace

(

const gnc_commodity *

cm

)

Retrieve the namespace for the specified commodity. This will be a pointer to a null terminated string of the form "AMEX", "NASDAQ", etc.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the namespace for this commodity. This string is owned by the engine and should not be freed by the caller.

Definition at line 716 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  return gnc_commodity_namespace_get_name(cm->namespace);
}

const char* gnc_commodity_get_namespace_compat

(

const gnc_commodity *

cm

)

Retrieve the namespace for the specified commodity. This will be a pointer to a null terminated string of the form "AMEX", "NASDAQ", etc. The only difference between function and gnc_commodity_get_namespace() is that this function returns ISO4217 instead of CURRENCY for backward compatability with the 1.8 data files.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the namespace for this commodity. This string is owned by the engine and should not be freed by the caller.

Definition at line 723 of file gnc-commodity.c.

{
  if (!cm || !cm->namespace) return NULL;
  if (cm->namespace->iso4217) {
    /* Data files are still written with ISO4217. */
    return GNC_COMMODITY_NS_ISO;
  }
  return gnc_commodity_namespace_get_name(cm->namespace);
}

gnc_commodity_namespace* gnc_commodity_get_namespace_ds

(

const gnc_commodity *

cm

)

Retrieve the namespace data strucure for the specified commodity. This will be a pointer to another data structure.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the namespace data structure for this commodity.

Definition at line 734 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  return cm->namespace;
}

const char* gnc_commodity_get_printname

(

const gnc_commodity *

cm

)

Retrieve the 'print' name for the specified commodity. This will be a pointer to a null terminated string of the form "Acme Systems, Inc. (ACME)", etc.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the print name for this commodity. This string is owned by the engine and should not be freed by the caller.

Definition at line 704 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  return cm->printname;
}

gboolean gnc_commodity_get_quote_flag

(

const gnc_commodity *

cm

)

Retrieve the automatic price quote flag for the specified commodity. This flag indicates whether stock quotes should be retrieved for the specified stock.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

TRUE if quotes should be pulled for this commodity, FALSE otherwise.

Definition at line 817 of file gnc-commodity.c.

{
  if(!cm) return FALSE;
  return (cm->quote_flag);
}

gnc_quote_source* gnc_commodity_get_quote_source

(

const gnc_commodity *

cm

)

Retrieve the automatic price quote source for the specified commodity. This will be a pointer to a null terminated string of the form "Yahoo (Asia)", etc.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the price quote source for this commodity.

Definition at line 828 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  if (!cm->quote_source && gnc_commodity_is_iso(cm))
    return &currency_quote_source;
  return cm->quote_source;
}

const char* gnc_commodity_get_quote_tz

(

const gnc_commodity *

cm

)

Retrieve the automatic price quote timezone for the specified commodity. This will be a pointer to a null terminated string of the form "America/New_York", etc.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the price quote timezone for this commodity. This string is owned by the engine and should not be freed by the caller.

Definition at line 850 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  return cm->quote_tz;
}

const char* gnc_commodity_get_unique_name

(

const gnc_commodity *

cm

)

Retrieve the 'unique' name for the specified commodity. This will be a pointer to a null terminated string of the form "AMEX::ACME", etc. This field is often used when performing comparisons or other functions invisible to the user.

Parameters:

cm

A pointer to a commodity data structure.

Returns:

A pointer to the 'unique' name for this commodity. This string is owned by the engine and should not be freed by the caller.

Definition at line 757 of file gnc-commodity.c.

{
  if(!cm) return NULL;
  return cm->unique_name;
}

void gnc_commodity_increment_usage_count

(

gnc_commodity *

cm

)

Increment a commodity's internal counter that tracks how many accounts are using that commodity. For currencies, this may have the side effect of enabling the commodity's quote flag.

Parameters:

cm

A pointer to a commodity data structure.

Definition at line 1078 of file gnc-commodity.c.

{
  const char *str;

  ENTER("(cm=%p)", cm);

  if(!cm) {
    LEAVE("");
    return;
  }

  if((cm->usage_count == 0) && !cm->quote_flag
      && gnc_commodity_get_auto_quote_control_flag(cm)
      && gnc_commodity_is_iso(cm)) {
    /* compatability hack - Gnucash 1.8 gets currency quotes when a
       non-default currency is assigned to an account.  */
    gnc_commodity_begin_edit(cm);
    gnc_commodity_set_quote_flag(cm, TRUE);
    gnc_commodity_set_quote_source(cm,
        gnc_commodity_get_default_quote_source(cm));
    gnc_commodity_commit_edit(cm);
  }
  cm->usage_count++;
  LEAVE("(usage_count=%d)", cm->usage_count);
}

gboolean gnc_commodity_is_currency

(

const gnc_commodity *

cm

)

Checks to see if the specified commodity is an ISO 4217 recognized currency or a legacy currency.

Parameters:

cm

The commodity to check.

Returns:

TRUE if the commodity represents a currency, FALSE otherwise.

Definition at line 1590 of file gnc-commodity.c.

{
    const char *ns_name;
    if (!cm) return FALSE;

    ns_name = gnc_commodity_namespace_get_name(cm->namespace);
    return (!safe_strcmp(ns_name, GNC_COMMODITY_NS_LEGACY) ||
            !safe_strcmp(ns_name, GNC_COMMODITY_NS_CURRENCY));
}

gboolean gnc_commodity_is_iso

(

const gnc_commodity *

cm

)

Checks to see if the specified commodity is an ISO 4217 recognized currency.

Parameters:

cm

The commodity to check.

Returns:

TRUE if the commodity represents a currency, FALSE otherwise.

Definition at line 1583 of file gnc-commodity.c.

{
  if (!cm || !cm->namespace) return FALSE;
  return cm->namespace->iso4217;
}

GList* gnc_commodity_namespace_get_commodity_list

(

const gnc_commodity_namespace *

ns

)

Return a list of all commodity data structures in the specified namespace.

Returns:

A pointer to the list of structures. NULL if an invalid argument was supplied.

Note:

This list is owned by the engine. The caller must not free the list.

Definition at line 1215 of file gnc-commodity.c.

{
  if (!namespace)
    return NULL;

  return namespace->cm_list;
}

const char* gnc_commodity_namespace_get_name

(

const gnc_commodity_namespace *

ns

)

Return the textual name of a namespace data strucure.

Parameters:

ns

A pointer to the namespace data strucure.

Returns:

A pointer to the name of the namespace. This string is owned by the engine and should not be freed by the caller.

Definition at line 1207 of file gnc-commodity.c.

{
  if (ns == NULL)
    return NULL;
  return ns->name;
}

gboolean gnc_commodity_namespace_is_iso

(

const char *

namespace

)

Checks to see if the specified commodity namespace is the namespace for ISO 4217 currencies.

Parameters:

namespace

The string to check.

Returns:

TRUE if the string indicates an ISO currency, FALSE otherwise.

Definition at line 1224 of file gnc-commodity.c.

{
  return ((safe_strcmp(namespace, GNC_COMMODITY_NS_ISO) == 0) ||
          (safe_strcmp(namespace, GNC_COMMODITY_NS_CURRENCY) == 0));
}

gnc_commodity* gnc_commodity_new	(	QofBook *	book,
		const char *	fullname,
		const char *	namespace,
		const char *	mnemonic,
		const char *	cusip,
		int	fraction
	)

Create a new commodity. This function allocates a new commodity data structure, populates it with the data provided, and then generates the dynamic names that exist as part of a commodity.

Note:

This function does not check to see if the commodity exists before adding a new commodity.

Parameters:

	book	The book that the new commodity will belong to.
	fullname	The complete name of this commodity. E.G. "Acme Systems, Inc."
	namespace	An aggregation of commodities. E.G. ISO4217, Nasdaq, Downbelow, etc.
	mnemonic	An abbreviation for this stock. For publicly traced stocks, this field should contain the stock ticker symbol. This field is used to get online price quotes, so it must match the stock ticker symbol used by the exchange where you want to get automatic stock quote updates. E.G. ACME, ACME.US, etc.
	cusip	A string containing the CUSIP code or similar UNIQUE code for this commodity. The stock ticker is NOT appropriate as that goes in the mnemonic field.
	fraction	The smallest division of this commodity allowed. I.E. If this is 1, then the commodity must be traded in whole units; if 100 then the commodity may be traded in 0.01 units, etc.

Returns:

A pointer to the new commodity.

Definition at line 559 of file gnc-commodity.c.

{
  gnc_commodity * retval = g_object_new(GNC_TYPE_COMMODITY, NULL);
  gnc_commodity_table *table;

  qof_instance_init_data (&retval->inst, GNC_ID_COMMODITY, book);
  table = gnc_commodity_table_get_table(book);
  if (namespace) {
    retval->namespace = gnc_commodity_table_find_namespace(table, namespace);
    if (!retval->namespace)
      retval->namespace = gnc_commodity_table_add_namespace(table, namespace, book);
  } else {
    retval->namespace = NULL;
  }
  
  retval->fullname = CACHE_INSERT(fullname);
  retval->mnemonic = CACHE_INSERT(mnemonic);
  retval->cusip = CACHE_INSERT(cusip);
  retval->fraction = fraction;
  retval->mark = 0;
  retval->quote_flag = 0;
  retval->quote_source = NULL;
  retval->quote_tz = CACHE_INSERT("");

  reset_printname(retval);
  reset_unique_name(retval);
  if (gnc_commodity_namespace_is_iso(namespace))
    retval->quote_source = gnc_quote_source_lookup_by_internal("currency");
  qof_event_gen (&retval->inst, QOF_EVENT_CREATE, NULL);

  return retval;
}

gnc_commodity* gnc_commodity_obtain_twin	(	const gnc_commodity *	from,
		QofBook *	book
	)

Given the commodity 'from', this routine will find and return the equivalent commodity (commodity with the same 'unique name') in the indicated book. This routine is primarily useful for setting up clones of things across multiple books.

Definition at line 1264 of file gnc-commodity.c.

{
  gnc_commodity *twin;
  const char * ucom;
  gnc_commodity_table * comtbl;

  if (!from) return NULL;
  comtbl = gnc_commodity_table_get_table (book);
  if (!comtbl) return NULL;

  ucom = gnc_commodity_get_unique_name (from);
  twin = gnc_commodity_table_lookup_unique (comtbl, ucom);
  if (!twin)
  {
    twin = gnc_commodity_clone (from, book);
    twin = gnc_commodity_table_insert (comtbl, twin);
  }
  return twin;
}

void gnc_commodity_set_cusip	(	gnc_commodity *	cm,
		const char *	cusip
	)

Set the 'exchange code' for the specified commodity. This should be a pointer to a null terminated string of the form "AXQ14728", etc.

Note:

This is a unique code that specifies a particular item or set of shares of a commodity, not a code that specifies a stock exchange. That is the namespace field.

Parameters:

	cm	A pointer to a commodity data structure.
	cusip	A pointer to the cusip or other exchange specific data for this commodity. This string belongs to the caller and will be duplicated by the engine.

Definition at line 928 of file gnc-commodity.c.

{
  if(!cm) return;
  if(cm->cusip == cusip) return;

  gnc_commodity_begin_edit(cm);
  CACHE_REMOVE (cm->cusip);
  cm->cusip = CACHE_INSERT (cusip);
  mark_commodity_dirty(cm);