Difference between revisions of "Using the API"

Revision as of 20:22, 10 May 2011

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.

Documentation

As for documentation: Unfortunatly 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.

http://svn.gnucash.org/docs/HEAD/modules.html contains the overview of those parts that are 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.

https://github.com/downloads/jralls/gnucash/gnucash_erd.png is an up-to-date (May 2011) 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
• Book

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

• src/engine/Split.h
• src/engine/Transaction.h
• src/engine/Account.h
• src/engine/gnc-commodity.h
• src/libqof/qof/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.

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:

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

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

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

// Now 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);

// Now the second (other) Split
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
xaccSplitSetValue(split, amount);
xaccSplitSetAmount(split, amount);

xaccTransCommitEdit(transaction); // We are finished editing