Difference between revisions of "Using the API"

From GnuCash
Jump to: navigation, search
(Documentation: Add note about SQL Schema being unchanged.)
(fix link; cosmetics)
 
(5 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This page collects some examples on how to use the C API in gnucash for basic data type manipulation. The C API (also called "the engine") is the abstraction layer from any backend. That is, the GUI or plugin programmer should never access any XML or SQL himself but instead he only uses the functions from the C API to access the data.
+
{| class="wikitable" style="margin: auto;"
 +
! scope="row"|Languages
 +
| [[He/{{PAGENAME:שימוש ב API}}|עִברִית]]
 +
|}
 +
This page collects some examples on how to use the C API of GnuCash for basic data type manipulation. The C API (also called "the engine") is the abstraction layer from any backend. That is, the GUI or plugin programmer should never access any XML or SQL himself but instead he only uses the functions from the C API to access the data.
  
 
== Documentation ==
 
== Documentation ==
As for documentation: Unfortunately there doesn't exist any up-to-date coherent set of documentation. Part of it is in doxygen, but part of it are only in the C header files.
+
As for documentation: Unfortunately there doesn't exist any up-to-date coherent set of documentation. Part of it is in [[Doxygen]], but part of it are only in the C header files.
  
[https://code.gnucash.org/docs/MAINT/modules.html A module overview] is available for those parts that are documented in doxygen. For example, there is a module group entitled "GnuCash Engine: Core, Non-GUI Accounting Functions" which contains the doxygen-ized parts of this, including the "Account", but not including Transaction and Split which are the other important basic data types.
+
[{{URL:docs:API}}modules.html A module overview] is available for those parts that are processed by doxygen. For example, there is a module group entitled "GnuCash Engine: Core, Non-GUI Accounting Functions" which contains the doxygen-ized parts of this, including the "Account", but not including Transaction and Split which are the other important basic data types.
  
[[Media:gnucash_erd.png|Entity-Relationship Diagram]] is an up-to-date (May 2011, but the schema is unchangedin mid-2017) Entity-Relationship-Diagram (ERD) which shows those most important types of gnucash (in the form of tables, as common for an ERD):
+
[[Media:gnucash_erd.png|Entity-Relationship Diagram]] is an up-to-date (May 2011, but the schema is unchanged in mid-2017) Entity-Relationship-Diagram (ERD) which shows those most important types of GnuCash (in the form of tables, as common for an ERD):
 
* Split
 
* Split
 
* Transaction
 
* Transaction
Line 14: Line 18:
  
 
The only place that is for sure up-to-date are the header files:
 
The only place that is for sure up-to-date are the header files:
* src/engine/Split.h
+
* libgnucash/engine/Split.h
* src/engine/Transaction.h
+
* libgnucash/engine/Transaction.h
* src/engine/Account.h
+
* libgnucash/engine/Account.h
* src/engine/gnc-commodity.h
+
* libgnucash/engine/gnc-commodity.h
* src/libqof/qof/qofbook.h
+
* libgnucash/engine/qofbook.h
  
:Hint: You might notice that QofBook appears not in the src/engine/ directory but instead in the src/libqof/qof/ directory. These are the remnants of a previous attempt to establish an abstraction layer for some even more generic form of data type which is not yet specialized to financial accounting. In my (cstim's) opinion this attempt was unsuitable for gnucash and also not carried out very well, but right now we simply have to live with the fact that the majority of the basic data types are in src/engine/ whereas some other basic types are in src/libqof/qof/. (To be precise, the src/engine code depends on src/libqof/qof and not the other way round, but this is just an implementation detail and not important for you.) You can just consider both directories as one common collection of the C API, and you can just think of both directories as two equally important parts of the C API.
+
;This section is from a very old in-tree build:If you intend to use those basic types from outside of GnuCash, the following set of libraries contains the functions needed for this basic C API:<s>
 +
: src/libqof/qof/libgnc-qof.la
 +
: src/core-utils/libgnc-core-utils.la
 +
: src/gnc-module/libgnc-module.la
 +
: src/engine/libgncmod-engine.la
 +
: src/backend/xml/libgncmod-backend-xml.la
 +
: src/app-utils/libgncmod-app-utils.la</s>
 +
:in increasing order, i.e. the latter ones depend on the former ones.
  
If you intend to use those basic types from outside of gnucash, the following set of libraries contains the functions needed for this basic C API:
+
;CuteCash is now removed:<s>In the C++ cutecash project, consequently those five important types appear again in separate header files which contain the C++ wrapper classes for the respective basic types:
src/libqof/qof/libgnc-qof.la
+
:* src/gnc/Split.hpp
src/core-utils/libgnc-core-utils.la
+
:* src/gnc/Transaction.hpp
src/gnc-module/libgnc-module.la
+
:* src/gnc/Account.hpp
src/engine/libgncmod-engine.la
+
:* src/gnc/Commodity.hpp
src/backend/xml/libgncmod-backend-xml.la
+
:* src/gnc/Book.hpp</s>
src/app-utils/libgncmod-app-utils.la
 
in increasing order, i.e. the latter ones depend on the former ones.
 
 
 
In the C++ cutecash project, consequently those five important types appear again in separate header files which contain the C++ wrapper classes for the respective basic types:
 
* src/gnc/Split.hpp
 
* src/gnc/Transaction.hpp
 
* src/gnc/Account.hpp
 
* src/gnc/Commodity.hpp
 
* src/gnc/Book.hpp
 
  
 
== Creating a new transaction ==
 
== Creating a new transaction ==
 
Here's the code to create a new transaction (abbreviated by "txn") and populate it with data, using "almost correct" C code (in reality, all the variable declarations must appear on top and not within the code):
 
Here's the code to create a new transaction (abbreviated by "txn") and populate it with data, using "almost correct" C code (in reality, all the variable declarations must appear on top and not within the code):
 +
<syntaxhighlight lang="C">
 
  Account *account = ...; // get this from somewhere
 
  Account *account = ...; // get this from somewhere
 
  QofBook *book = gnc_account_get_book(account);
 
  QofBook *book = gnc_account_get_book(account);
Line 45: Line 48:
 
  Transaction *transaction = xaccMallocTransaction(book); // Creating the new transaction
 
  Transaction *transaction = xaccMallocTransaction(book); // Creating the new transaction
 
  xaccTransBeginEdit(transaction); // Opening it for editing
 
  xaccTransBeginEdit(transaction); // Opening it for editing
 +
</syntaxhighlight>
  
 
The txn is created. We can set the txn-related data fields:
 
The txn is created. We can set the txn-related data fields:
  
 +
<syntaxhighlight lang="C">
 
  xaccTransSetDatePostedSecs(transaction, 1234567); // Date of this txn
 
  xaccTransSetDatePostedSecs(transaction, 1234567); // Date of this txn
 
  xaccTransSetNum(transaction, "X23");
 
  xaccTransSetNum(transaction, "X23");
 
  xaccTransSetNotes(transaction, "Some notes, bla bla");
 
  xaccTransSetNotes(transaction, "Some notes, bla bla");
 +
</syntaxhighlight>
  
As gnucash is capable of multi-currency handling, every txn must have a "transaction currency" set:
+
As GnuCash is capable of multi-currency handling, every txn must have a "transaction currency" set:
 
   
 
   
 +
<syntaxhighlight lang="C">
 
  Commodity *currency = xaccAccountGetCommodity(account);
 
  Commodity *currency = xaccAccountGetCommodity(account);
 
  xaccTransSetCurrency(transaction, currency); // Txn must have a commodity/currency set
 
  xaccTransSetCurrency(transaction, currency); // Txn must have a commodity/currency set
 +
</syntaxhighlight>
  
 
The actual amount/value of a transaction is given by its two or more splits. We create the first split:
 
The actual amount/value of a transaction is given by its two or more splits. We create the first split:
  
 +
<syntaxhighlight lang="C">
 
  Split *split = xaccMallocSplit(book);
 
  Split *split = xaccMallocSplit(book);
 
  xaccTransAppendSplit(transaction, split); // Split belongs to this txn
 
  xaccTransAppendSplit(transaction, split); // Split belongs to this txn
Line 65: Line 74:
 
  xaccSplitSetValue(split, amount);
 
  xaccSplitSetValue(split, amount);
 
  xaccSplitSetAmount(split, amount);
 
  xaccSplitSetAmount(split, amount);
 +
</syntaxhighlight>
  
 
As for the SetValue and SetAmount: In multi-currency or stock trading txn, the amount is different from the value and vice versa. As long as you're dealing with exactly one currency, both value and amount are set to be the same value.
 
As for the SetValue and SetAmount: In multi-currency or stock trading txn, the amount is different from the value and vice versa. As long as you're dealing with exactly one currency, both value and amount are set to be the same value.
Line 70: Line 80:
 
Then we create the second split so that we have a normal two-split transaction, as usual in the double-entry bookkeeping:
 
Then we create the second split so that we have a normal two-split transaction, as usual in the double-entry bookkeeping:
  
 +
<syntaxhighlight lang="C">
 
  Account* other_account = ...; // need to get this from somewhere
 
  Account* other_account = ...; // need to get this from somewhere
 
  Split *split2 = xaccMallocSplit(book);
 
  Split *split2 = xaccMallocSplit(book);
Line 77: Line 88:
 
  xaccSplitSetValue(split, other_amount);
 
  xaccSplitSetValue(split, other_amount);
 
  xaccSplitSetAmount(split, other_amount);
 
  xaccSplitSetAmount(split, other_amount);
 +
</syntaxhighlight>
  
 
In the end, we must finish the transaction editing by calling the CommitEdit function:
 
In the end, we must finish the transaction editing by calling the CommitEdit function:
  
 +
<syntaxhighlight lang="C">
 
  xaccTransCommitEdit(transaction); // We are finished editing
 
  xaccTransCommitEdit(transaction); // We are finished editing
 +
</syntaxhighlight>
 +
 +
== Usage Examples ==
 +
Some examples are in [[Python_shell#Usage_examples]].

Latest revision as of 16:12, 24 October 2023

Languages עִברִית

This page collects some examples on how to use the C API of GnuCash for basic data type manipulation. The C API (also called "the engine") is the abstraction layer from any backend. That is, the GUI or plugin programmer should never access any XML or SQL himself but instead he only uses the functions from the C API to access the data.

Documentation

As for documentation: Unfortunately there doesn't exist any up-to-date coherent set of documentation. Part of it is in Doxygen, but part of it are only in the C header files.

A module overview is available for those parts that are processed by doxygen. For example, there is a module group entitled "GnuCash Engine: Core, Non-GUI Accounting Functions" which contains the doxygen-ized parts of this, including the "Account", but not including Transaction and Split which are the other important basic data types.

Entity-Relationship Diagram is an up-to-date (May 2011, but the schema is unchanged in mid-2017) Entity-Relationship-Diagram (ERD) which shows those most important types of GnuCash (in the form of tables, as common for an ERD):

  • Split
  • Transaction
  • Account
  • Commodity (typedef name: gnc_commodity)
  • Book (typedef name: QofBook)

The only place that is for sure up-to-date are the header files:

  • libgnucash/engine/Split.h
  • libgnucash/engine/Transaction.h
  • libgnucash/engine/Account.h
  • libgnucash/engine/gnc-commodity.h
  • libgnucash/engine/qofbook.h
This section is from a very old in-tree build
If you intend to use those basic types from outside of GnuCash, the following set of libraries contains the functions needed for this basic C API:
src/libqof/qof/libgnc-qof.la
src/core-utils/libgnc-core-utils.la
src/gnc-module/libgnc-module.la
src/engine/libgncmod-engine.la
src/backend/xml/libgncmod-backend-xml.la
src/app-utils/libgncmod-app-utils.la
in increasing order, i.e. the latter ones depend on the former ones.
CuteCash is now removed
In the C++ cutecash project, consequently those five important types appear again in separate header files which contain the C++ wrapper classes for the respective basic types:
  • src/gnc/Split.hpp
  • src/gnc/Transaction.hpp
  • src/gnc/Account.hpp
  • src/gnc/Commodity.hpp
  • src/gnc/Book.hpp

Creating a new transaction

Here's the code to create a new transaction (abbreviated by "txn") and populate it with data, using "almost correct" C code (in reality, all the variable declarations must appear on top and not within the code):

 Account *account = ...; // get this from somewhere
 QofBook *book = gnc_account_get_book(account);
 
 Transaction *transaction = xaccMallocTransaction(book); // Creating the new transaction
 xaccTransBeginEdit(transaction); // Opening it for editing

The txn is created. We can set the txn-related data fields:

 xaccTransSetDatePostedSecs(transaction, 1234567); // Date of this txn
 xaccTransSetNum(transaction, "X23");
 xaccTransSetNotes(transaction, "Some notes, bla bla");

As GnuCash is capable of multi-currency handling, every txn must have a "transaction currency" set:

 Commodity *currency = xaccAccountGetCommodity(account);
 xaccTransSetCurrency(transaction, currency); // Txn must have a commodity/currency set

The actual amount/value of a transaction is given by its two or more splits. We create the first split:

 Split *split = xaccMallocSplit(book);
 xaccTransAppendSplit(transaction, split); // Split belongs to this txn
 xaccAccountInsertSplit(account, split); // Split belongs to this account
 gnc_numeric amount = gnc_numeric_create(123, 100); // 1.23
 xaccSplitSetValue(split, amount);
 xaccSplitSetAmount(split, amount);

As for the SetValue and SetAmount: In multi-currency or stock trading txn, the amount is different from the value and vice versa. As long as you're dealing with exactly one currency, both value and amount are set to be the same value.

Then we create the second split so that we have a normal two-split transaction, as usual in the double-entry bookkeeping:

 Account* other_account = ...; // need to get this from somewhere
 Split *split2 = xaccMallocSplit(book);
 xaccTransAppendSplit(transaction, split2); // Split belongs to this txn
 xaccAccountInsertSplit(other_account, split2); // Split belongs to this account
 gnc_numeric other_amount = gnc_numeric_create(-123, 100); // -1.23, the negative value for above
 xaccSplitSetValue(split, other_amount);
 xaccSplitSetAmount(split, other_amount);

In the end, we must finish the transaction editing by calling the CommitEdit function:

 xaccTransCommitEdit(transaction); // We are finished editing

Usage Examples

Some examples are in Python_shell#Usage_examples.