Debian Codegraph @

README

raw
1 Copyright (c) 2002-2010 Benoit Grégoire
2
3 # LibOFX
4 LibOFX library is an API designed to allow applications to very easily support OFX command responses, usually provided by financial institutions. See http://www.ofx.net/ for details and specification. This project was first started as my end of degree project, with the objective to add OFX support to [GnuCash](https://www.gnucash.org/) If you can read French, the original project presentation is included in the doc directory. I finally decided to make it into a generic library, so all OpenSource financial software can benefit.
5
6
7 LibOFX strives to achieve the following design goals:
8
9 * Simplicity: OFX is a VERY complex spec. However, few if any software needs all this complexity. The library tries to hide this complexity by "flattening" the data structures, doing timezone conversions, currency conversion, etc.
10 * Data directly usable from C, without conversion: A date is a C `time_t`, money is a float, strings are `char[]`, etc.
11 * C style interface: Although LibOFX is written in C++, it provides an interface usable transparently from both C and C++, using a single header file.
12
13 LibOFX was implemented directly from the full OFX 1.6 spec, and currently supports:
14 * Banking transactions and statements.
15 * Credit card and statements.
16 * Investment transactions.
17 * OFX 2.0
18
19 Future projects for LibOFX include:
20 * Header parsing
21 * DTD autodetection
22 * Currency conversion
23 * QIF import
24 * QIF export (integrated inside the library)
25 * OFX export
26
27 # Additional tools
28 In addition to the library, three utilities are included with LibOFX:
29
30 ## ofxdump
31 ofxdump prints to stdout, in human-readable form, everything the library understands about a particular OFX response file, and sends errors to stderr. It is a C++ code example and demo of the library (it uses every functions and every structures of LibOFX).
32
33 Usage: `ofxdump _path_to_ofx_file_/_ofx_filename_`
34
35 ## ofx2qif
36 ofx2qif is a OFX "file" to QIF (Quicken Interchange Format) converter. It was written as a C code example, and as a way for LibOFX to immediately provide something useful, as an incentive for people to try out the library. It is not recommended that financial software use the output of this utility for OFX support. The QIF file format is very primitive, and much information is lost. The utility currently supports every transaction tags of the qif format except the address lines, and supports many of the tags of `!Account`. It should generate QIF files that will import successfully in just about every software with QIF support.
37 I do not plan on working on this utility much further, but I would be more than happy to accept contributions.
38
39 Usage: `ofx2qif _path_to_ofx_file_/_ofx_filename_ > _output_filename_.qif`
40
41 ## ofxconnect
42 ofxconnect is a sample app to demonstrate & test new Direct Connect APIs.
43 It also serves as an implementation sample, so you can understand how to use it in your own code.
44
45 ### The Direct Connect protocol
46
47 Direct Connect consists of two separate steps: First, contacting the partner
48 server to retrieve information about your bank. Second, contacting your bank
49 to retrieve your accounts and statements. The partner server should be
50 contacted when the user sets up his accounts.
51
52 Common mistakes with the partner server are to contact it EVERY time you
53 contact the bank, and contacting it just once to cache the contact
54 info for all banks. The former is overkill, the latter means users won't
55 have up-to-date bank contact information.
56
57 ### Usage
58
59 Step-by-step guide to using the ofxconnect utility:
60
61 1. Retrieve the list of banks
62
63 ```shell
64 $ ofxconnect -b
65 ```
66
67 2. Find your bank in the list. Retrieve the FI partner ID's (fipid's) for that bank
68
69 ```shell
70 $ ofxconnect -f "Wells Fargo"
71 101458
72 102078
73 5571
74 ```
75
76 3. Retrieve the service capabilities of each fipid to find the one which has the services you want.\
77 Note that all the 6-digit fipids don't seem to work well with LibOFX right now.
78
79 ```shell
80 $ ofxconnect -v 5571
81 Statements? Yes
82 Billpay? Yes
83 Investments? No
84 ```
85
86 4. Retrieve and view the list of all your accounts
87
88 ```shell
89 $ ofxconnect -a --fipid=5571 --user=myusername --pass=mypassword accounts.ofx
90 $ ofxdump accounts.ofx 2>/dev/null
91 ```
92
93 5. Look for entries like this:
94
95 ```
96 Account ID: 999888777 00 123456789
97 Account name: Bank account 1234567890
98 Account type: CHECKING
99 Bank ID: 999888777
100 Branch ID: 00
101 Account #: 1234567890
102 ```
103
104 6. Retrieve a statement for one of the accounts
105
106 ```shell
107 $ ofxconnect -s --fipid=5571 --user=myusername --pass=mypassword --bank=xxx --account=xxx --type=x --past=xx statement.ofx
108 $ ofxdump statement.ofx 2>/dev/null
109 ````
110
111 The `--bank` and `--account` parameters should be exactly like the "Bank ID" and "Account #" results from the account request.\
112 The `--type` is: `1=CHECKING`, `2=INVESTMENT`, `3=CREDITCARD`. Other types are not supported.\
113 The `--past` is how many days previous from today you want.
114
115 ### Testing in live environment
116
117 When building using Autotools build system, issuing `make check` in the ofxconnect folder should test against a live test server:
118
119 > There is an OFX test server which is used by the developers to ensure
120 > that the OFX connection works correctly. The providers of this server
121 > have asked us not to post the connection information publicly.
122 >
123 > Therefore, the test script file which connects to this server is
124 > encrypted using a GnuPG key: OFX Test Server <[email protected]>.
125 >
126 > You will need this private key to unlock this file. If you are an
127 > active, contributing member of the open source OFX community, please
128 > e-mail me for this key. Please do not share the key with anyone who does
129 > not fit this description. Please do not post the key on any mailing list
130 > or any other archived forum. If the key does become comprimised, please
131 > e-mail me, or the libofx-devel list and we'll cancel that key and
132 > encrypt it using a new one.
133 >
134 > Thanks
135 >
136 > Ace Jones <[email protected]>
137
138 # Dependencies
139
140 ## OpenSP
141 LibOFX is based on the excellent OpenSP library written by James Clark, and now part of the [OpenJADE](http://openjade.sourceforge.net/) project. OpenSP by itself is not widely distributed. OpenJADE 1.3.1 includes a version on OpenSP that will link, however, it has some major problems with LibOFX and isn't recommended. Since LibOFX uses the generic interface to OpenSP, it should be compatible with all recent versions of OpenSP (It has been developed with OpenSP-1.5pre5). LibOFX is written in C++, but provides a C style interface usable transparently from both C and C++ using a single include file.
142
143 ### LibOFX <==> OpenSP compatibility matrix:
144 | OpenSP version | Status | Comments |
145 |-----------------------------------------------------|--------------------------------|--------------------------------------------------------------------------------------------|
146 | 1.3.4 (included in most distro with OpenJADE 1.3.1) | NOT COMPATIBLE | OpenSP doesn't parse OFX files correctly. LibOFX < 0.23 will probably only output garbage. |
147 | 1.4 | NOT TESTED ||
148 | 1.5pre5 | COMPATIBLE with all versions ||
149 | 1.5pre8 | COMPATIBLE with LibOFX >= 0.23 ||
150 | 1.5 | COMPATIBLE with LibOFX >= 0.23 ||
151
152 ### Locating the OpenSP library file
153 The [`FindOpenSP.cmake`](cmake/modules/FindOpenSP.cmake) module attempts to locate the library and its headers on the filesystem. If it fails to do so, or if you want to tell it to use a specific library file instead, you can pass [CMake switches](#cmake-switches) to do so.
154
155 Note that the [upstream CMake](https://gitlab.kitware.com/cmake/cmake/-/blob/master/Modules/FindOpenSP.cmake) ships the [`FindOpenSP.cmake`](cmake/modules/FindOpenSP.cmake) module as of version 3.25, so its copy included with LibOFX sourcecode is used only if your CMake version is older than that.
156
157 ### On the SP_MULTI_BYTE
158 LibOFX must know if OpenSP library was compiled with the `SP_MULTI_BYTE` defined. The `FindOpenSP` module will attempt to detect the `SP_MULTI_BYTE`, based on OpenSP's `config.h`. If, however, you see strings such as `SAEET` or `SAEET▄ù≡ù` instead of `STATEMENT` in ofxdump's output, it means that the library was misconfigured.
159 In such case you can force LibOFX to override the detected value by setting the `FORCE_OPENSP_MULTIBYTE` [CMake switch](#cmake-switches) to either `ON` or `OFF`. Note that this switch defaults to `AUTO` to use the auto-detected value.
160
161 ## Iconv
162 Used to convert the encoding, not required but very recommended.
163
164 ## Libxml++
165 Required by the ofxconnect tool. Needs to be compatible with version 2.6 of the ABI, see https://libxmlplusplus.github.io/libxmlplusplus/#abi-versions for details.
166
167 ## Libcurl
168 Required by the ofxconnect tool.
169
170 # Building
171
172 ## Using CMake build system
173
174 You can use CMake to build LibOFX. See the `CMakeLists.txt` in root folder for the currently required version.
175 CMake is designed so that the build process can be done in a separate directory. This is highly recommended for users and required for packagers.
176 To build LibOFX in the subdirectory `build/`, type:
177
178 ```shell
179 $ cmake -B build -S . # add "-G Ninja" if ninja is installed (optional, see "CMake switches" section below)
180 $ ccmake -B build -S . # to change the configuration of the build process (optional, see "CMake switches" section below).
181 ```
182
183 ## CMake switches
184 There are several CMake options available that can be enabled/disabled to change the set of features enabled or the compilation behavior:
185
186
187 | Switch | Value | Default | Purpose |
188 |-------------------------------|:-----------------------------------------------------------------------------------------------------------------------------:|:-----------------------------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
189 | `-D BUILD_SHARED_LIBS` | `ON`/`OFF` | `ON` | Whether to build LibOFX dynamically (shared) or statically |
190 | `-D ENABLE_ICONV` | `ON`/`OFF` | `ON` | Enables ICONV support for encoding conversion |
191 | `-D ENABLE_OFX2QIF` | `ON`/`OFF` | `ON` | Enables OFX file to QIF (Quicken Interchange Format) file converter |
192 | `-D ENABLE_OFXDUMP` | `ON`/`OFF` | `ON` | Enables ofxdump utility which prints, in human readable form, everything the library understands about a file |
193 | `-D ENABLE_OFXCONNECT` | `ON`/`OFF` | `ON` | Enables ofxconnect utility which allows to test OFX Direct Connect |
194 | `-D FORCE_OPENSP_MULTIBYTE` | `AUTO`/`ON`/`OFF` | `AUTO` | Whether to use the auto-detected value of the `SP_MULTI_BYTE` (`AUTO`), or to override it to `ON` or `OFF`. See [On the SP_MULTI_BYTE](#on-the-spmultibyte) notes. |
195 | `-D CMAKE_BUILD_TYPE` | Various | `RelWithDebInfo` | Chooses the build type; refer to CMake manual for a list of possible types |
196 | `-D CMAKE_TOOLCHAIN_FILE` | A path, e.g. `[vcpkg root]/scripts/buildsystems/vcpkg.cmake`, where `[vcpkg root]` is your clone of the vcpkg Git repository. | None | A path to the toolchain file. Implies `ENABLE_VCPKG_INTEGRATION=ON` |
197 | `-D ENABLE_VCPKG_INTEGRATION` | `ON`/`OFF` | `OFF` | An alternative way to enable vcpkg integration. A attempt will be made to detect the location of the `vcpkg.cmake` toolchain file using `VCPKG_ROOT` environment variable. |
198 | `-D OpenSP_INCLUDE_DIR` | A path, e.g. `/usr/include/opensp` | Whatever `FindOpenSP.cmake` detects | A path to the OpenSP library includes. Normally `FindOpenSP.cmake` module should locate it, but if it can't or you want to override it, you can use this switch. |
199 | `-D OpenSP_LIBRARY` | A path, e.g. `/usr/lib/libosp.so.5` | Whatever `FindOpenSP.cmake` detects | Like the `OpenSP_INCLUDE_DIR` above, but for the library file itself. |
200
201 ### Vcpkg integration
202
203 vcpkg is a command-line package manager for C++, supported on macOS, Linux and Windows platforms. It is a preferred way of obtaining the dependencies due to its ability to deploy them according to a declarative [vcpkg.json](vcpkg.json) manifest file provided with the source code. This allows to maintain a set of dependencies and their corresponding versions independently for each branch and automatically switching between them as needed. It also guarantees reproducibility of the dev environment and substantially reduces the effort required to set up a working environment.
204
205 Refer to the [Getting Started](https://github.com/microsoft/vcpkg#getting-started) guide on project's website on how to get started if you're not yet familiar with it.
206
207 In order to build LibOFX with it, simply enabling an additional switch in your CMake command should be enough:\
208 `-DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake`, where `[vcpkg root]` is your clone of the vcpkg Git repository. Alternatively, if you have `VCPKG_ROOT` environment variable set-up, you can simply enable `-D ENABLE_VCPKG_INTEGRATION=ON` switch to have it autodetect the location of the vcpkg toolchain file. See notes on the [CMake switches](#cmake-switches) available as well.
209
210 Vcpkg will automatically set-up all the required optional dependencies, per the [CMake switches](#cmake-switches) enabled via the command line.
211
212 ## Using classic Autotools build system
213
214 Make sure you have the OpenSP library installed (`libosp.so`) before compiling. You can grab it at http://openjade.sourceforge.net/. The recommended version is OpenSP 1.5.
215 If you have a version of OpenJade or OpenSP already installed before compiling OpenSP, make sure that you use `./configure --prefix=/usr` to build OpenSP. Otherwise, LibOFX will probably link with the older, incompatible version of OpenSP.
216
217 Then type:\
218 1. `./autogen.sh` (for LibOFX cloned from repository)\
219 or `./configure` (for a distributed tarball)\
220 2. `make`\
221 And as root type:
222 3. `make install`
223
224 # Consuming (using as a dependency in your project)
225
226 LibOFX is distributed with both PkgConfig libofx.pc (materialized from [libofx.pc.in](libofx.pc.in)) and [CMake config-file package](https://cmake.org/cmake/help/latest/manual/cmake-packages.7.html) (materialized from [LibOFXConfig.cmake.in](LibOFXConfig.cmake.in)). If possible, use the latter, as it is more robust
227 and can automatically locate the OpenSP dependency library via the [`FindOpenSP.cmake`](#locating-the-opensp-library-file).
228
229 A copy of [`FindOpenSP.cmake`](#locating-the-opensp-library-file) module is distributed alongside the CMake config-file package for use in case your CMake version does not ship it. See a note in
230 [`FindOpenSP.cmake`](#locating-the-opensp-library-file) for details on that.
231
232
233 ## FAQ/Troubleshooting
234
235 ### Q: vcpkg fails to build ofxconnect due to missing Libxml++
236
237 LibOFX depends on [Libxml++ library that compatible with version 2.6 of its ABI](#libxml), meanwhile vcpkg provides a version compatible with ABI 5.0. Unfortunately, at this point there is no workaround for it if building with vcpkg.
238
239 ### Q: Getting "configure: error: unable to link a test program, is OpenSP installed?"
240
241 BE CAREFUL: When you compile OpenSP, by default it will install in /usr/local. On many versions of linux (Most RedHat, All Mandrake up to 8.3) `/usr/local/lib/` is not part of `/etc/ld.so.conf`. In this case LibOFX will either:
242 1) Fail to link at all
243 2) Link with `libosp.so.0` (1.3.4, which probably got installed as part of OpenJade) and not work.
244 Even if you add `/usr/local/lib/` to `/etc/ld.so.conf`, LibOFX will probably still link with OpenSP 1.3.4 at runtime. Symptoms will be complaints of many unclosed statements when running ofxdump on an ofx file.
245
246 I STRONGLY URGE YOU to avoid these problems and compile OpenSP using
247 `./configure --prefix=/usr`
248 If you really want to install OpenSP in `/usr/local/lib`, you must add `--with-opensp-libs=/usr/local/lib` to LibOFX's `./configure` or `./autogen.sh`
249
250 ### Q: Problems compiling OpenSP 1.4
251
252 If you are getting errors like:
253 `../include/Message.h:157: 'class OpenSP::Messenger' is inaccessible nsgmls.cxx:60: within this context)`
254
255 Try to change private to protected in file `OpenSP-1.4/nsgmls/RasEventHandler.h`, on line 105.
256
257 ### Q: ofxdump does now work right. It seems some values are cut in half, or one out of two letter is missing.
258
259 See the [On the SP_MULTI_BYTE](#on-the-spmultibyte) notes.
260
261 # API Documentation
262 Full documentation of the API and library internals generated using doxygen is available. For a quick start, you should learn all you need to know to get started by reading the `libofx.h` file in the INC directory, and `ofxdump.cpp` in the ofxdump directory.
263
264 # Get involved!
265 * Please note that despite a very detailed spec, OFX is by nature very hard to test. I only have access to the specifications examples, and
266 my own bank (Desjardins). But I need people to run as many OFX files from different banks as they can thru LibOFX, and report the result.
267 * This is my first attempt at writing an API. I need comments from financial software writers about `inc/libofx.h` What do YOU need?
268
269 Benoit Grégoire\
270 [email protected]
271