Subversion Repositories currency_converter

Rev

Rev 5 | Go to most recent revision | Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 daniel-mar 1
<html>
2
 
3
<head>
4
        <title>ViaThinkSoft Currency Converter - DLL specification</title>
5
</head>
6
 
7
<body>
8
 
9
<h1>ViaThinkSoft Currency Converter - DLL specification</h1>
10
 
11
<h2>Table of Contents</h2>
12
 
13
<p>These functions are exported by <b>CurConv.dll</b>:</p>
14
 
15
<ul>
16
        <li><a href="#DeleteAPIKey">DeleteAPIKey</a></li>
17
        <li><a href="#WriteAPIKey">WriteAPIKey</a></li>
18
        <li><a href="#ReadAPIKey">ReadAPIKey</a></li>
19
        <li><a href="#Convert">Convert</a></li>
20
        <li><a href="#AcceptedCurrencies">AcceptedCurrencies</a></li>
21
        <li><a href="#DownloadNow">DownloadNow</a></li>
22
</ul>
23
 
24
<h2 id="DeleteAPIKey">DeleteAPIKey</h3>
25
 
26
<h3>Syntax</h4>
27
<h4>Delphi</h5>
28
<pre>
29
function DeleteAPIKey(UserMode: BOOL; DontShowErrors: BOOL): HRESULT; stdcall;
30
</pre>
31
<h4>C</h5>
32
<pre>
33
HRESULT __stdcall DeleteAPIKey(BOOL UserMode, BOOL DontShowErrors);
34
</pre>
35
 
36
<h3>Description</h4>
37
<p>Deletes the API key from the registry.</p>
38
 
39
<h3>Parameters</h4>
40
<ul>
41
        <li>UserMode: If true, the API key will be deleted from <code>HKEY_LOCAL_USER</code>, otherwise it will be deleted on <code>HKEY_LOCAL_MACHINE</code>.</li>
42
        <li>DontShowErrors: If true, no errors will be displayed. If true, errors will result in a dialog box, in addition to the result code.</li>
43
</ul>
44
 
45
<h3>Returns</h4>
46
<ul>
47
        <li>S_VTSCONV_OK (0x20000000) if the key could be successfully deleted.</li>
48
        <li>S_VTSCONV_NOTHING (0x20000001) if no key could be found.</li>
49
        <li>E_VTSCONV_GENERIC_FAILURE (0xA0000000) if an error occured.</li>
50
</ul>
51
 
52
<h2 id="WriteAPIKey">WriteAPIKey</h3>
53
 
54
<h3>Syntax</h4>
55
<h4>Delphi</h5>
56
<pre>
57
function WriteAPIKey(key: LPCTSTR; UserMode: BOOL; DontShowErrors: BOOL): HRESULT; stdcall;
58
function WriteAPIKeyW(key: LPCWSTR; UserMode: BOOL; DontShowErrors: BOOL): HRESULT; stdcall;
59
function WriteAPIKeyA(key: LPCSTR; UserMode: BOOL; DontShowErrors: BOOL): HRESULT; stdcall;
60
</pre>
61
<h4>C</h5>
62
<pre>
63
HRESULT __stdcall WriteAPIKeyW(LPCWSTR key, BOOL UserMode, BOOL DontShowErrors);
64
HRESULT __stdcall WriteAPIKeyA(LPCSTR key, BOOL UserMode, BOOL DontShowErrors);
65
</pre>
66
 
67
<h3>Description</h4>
68
<p>Writes the API key into the registry. This is usually not neccessary, since the convert functions are able to query the key from the user using the GUI.</p>
69
 
70
<h3>Parameters</h4>
71
<ul>
72
        <li>key: The 32 digit key you received from currencylayer.com</li>
73
        <li>UserMode: If true, the API key will be written into <code>HKEY_LOCAL_USER</code>, otherwise it will be written to <code>HKEY_LOCAL_MACHINE</code>.</li>
74
        <li>DontShowErrors: If true, no errors will be displayed. If true, errors will result in a dialog box, in addition to the result code.</li>
75
</ul>
76
 
77
<h3>Returns</h4>
78
<ul>
79
        <li>S_VTSCONV_OK (0x20000000) if the key could be successfully deleted.</li>
80
        <li>E_VTSCONV_GENERIC_FAILURE (0xA0000000) if an error occured, e.g. if the registry is write protected.</li>
81
        <li>E_VTSCONV_BAD_ARGS (0xA0000001) if the key is invalid.</li>
82
</ul>
83
 
84
<h2 id="ReadAPIKey">ReadAPIKey</h3>
85
 
86
<h3>Syntax</h4>
87
<h4>Delphi</h5>
88
<pre>
89
function ReadAPIKey(key: LPTSTR; DontShowErrors: BOOL): HRESULT; stdcall;
90
function ReadAPIKeyW(key: LPWSTR; DontShowErrors: BOOL): HRESULT; stdcall;
91
function ReadAPIKeyA(key: LPSTR; DontShowErrors: BOOL): HRESULT; stdcall;
92
</pre>
93
<h4>C</h5>
94
<pre>
95
HRESULT __stdcall ReadAPIKeyW(LPWSTR key, BOOL DontShowErrors);
96
HRESULT __stdcall ReadAPIKeyA(LPSTR key, BOOL DontShowErrors);
97
</pre>
98
 
99
<h3>Description</h4>
100
<p>Reads the API key from the registry.</p>
101
 
102
<h3>Parameters</h4>
103
<ul>
104
        <li>key: A buffer where the 32 digit key will be written to. There should be at least 33 chars memory reserved (32 chars key + 1 char zero termination).</li>
105
        <li>UserMode: If true, the API key will be written into <code>HKEY_LOCAL_USER</code>, otherwise it will be written to <code>HKEY_LOCAL_MACHINE</code>.</li>
106
        <li>DontShowErrors: If true, no errors will be displayed. If true, errors will result in a dialog box, in addition to the result code.</li>
107
</ul>
108
 
109
<h3>Returns</h4>
110
<ul>
111
        <li>S_VTSCONV_OK (0x20000000) if the key could be successfully deleted.</li>
112
        <li>E_VTSCONV_GENERIC_FAILURE (0xA0000000) if an error occured, e.g. if the registry is write protected.</li>
113
        <li>E_VTSCONV_STOREDKEY_INVALID (0xA0000002) if the key stored in the registry is invalid.</li>
114
        <li>E_VTSCONV_NO_STOREDKEY (0xA0000003) if there is no key stored in the registry.</li>
115
</ul>
116
 
117
<h2 id="Convert">Convert</h3>
118
 
119
<h3>Syntax</h4>
120
<h4>Delphi</h5>
121
<pre>
122
function Convert(Value: Double; CurFrom, CurTo: LPCTSTR; MaxAge: integer; Flags: TVtsCurConvFlags; HistoricDate: TDate): Double; stdcall;
123
function ConvertW(Value: Double; CurFrom, CurTo: LPCWSTR; MaxAge: integer; Flags: TVtsCurConvFlags; HistoricDate: TDate): Double; stdcall;
124
function ConvertA(Value: Double; CurFrom, CurTo: LPCSTR; MaxAge: integer; Flags: TVtsCurConvFlags; HistoricDate: TDate): Double; stdcall;
125
</pre>
126
<h4>C</h5>
127
<pre>
128
Double __stdcall ConvertW(Double Value, LPCWSTR CurFrom, LPCWSTR CurTo, int MaxAge, DWORD Flags, DATE HistoricDate);
129
Double __stdcall ConvertA(Double Value, LPCSTR CurFrom, LPCSTR CurTo, int MaxAge; DWORD Flags, DATE HistoricDate);
130
</pre>
131
 
132
<h3>Description</h4>
133
<p>Converts into a differnt currency.</p>
134
 
135
<h3>Parameters</h4>
136
<ul>
137
        <li>Value: The amount of money in the source currency you want to convert into the target currency.</li>
138
        <li>CurFrom: The source currency, formatted as defined in ISO-4217 (3 chars, e.g. "USD")</li>
139
        <li>CurTo: The target currency, formatted as defined in ISO-4217 (3 chars, e.g. "USD")</li>
140
        <li>MaxAge: Defines, after which amount of time the exchange data needs to be re-downloaded from the server.<ul>
141
                <li>-1: Only download once</li>
142
                <li&gt;0: Always download, on each request (attention: API keys may have limited amount of accesses per month)</li>
143
                <li>&gt;0: Download after the supplied amount of time (in seconds)</li>
144
        </ul></li>
145
        <li>Flags: Is a sum of following components:<ul>
146
                <li>CONVERT_DONT_SHOW_ERRORS (1): Don't show errors in a dialog box.</li>
147
                <li>CONVERT_FALLBACK_TO_CACHE (2): If download failed, use the previous downloaded cache file, even if it is older than MaxAge.</li>
148
                <li>CONVERT_USE_SSL (4): Use SSL to download the data. Note that only a paid subscription allows download via SSL.</li>
149
                <li>CONVERT_CONFIRM_WEB_ACCESS (8): Ask the user each time the API tries to download from the web.</li>
150
                <li>CONVERT_NO_INTERACTIVE_API_KEY_INPUT (16): Don't ask the user for an API key in case the API key is missing or invalid.</li>
151
        </ul></li>
152
        <li>HistoricDate:<ul>
153
                <li&gt;0: Use the current exchange data</li>
154
                <li>any valid DATE: use an historic exchange</li>
155
        </ul></li>
156
</ul>
157
 
158
<h3>Returns</h4>
159
<ul>
160
        <li>-1 if an error occured</li>
161
        <li>&gt;=0 the amount of money in the target currency</li>
162
</ul>
163
 
164
<h2 id="AcceptedCurrencies">AcceptedCurrencies</h3>
165
 
166
<h3>Syntax</h4>
167
<h4>Delphi</h5>
168
<pre>
169
function AcceptedCurrencies(WriteTo: LPTSTR; MaxAge: integer; Flags: TVtsCurConvFlags; HistoricDate: TDate): Integer; stdcall;
170
function AcceptedCurrenciesW(WriteTo: LPWSTR; MaxAge: integer; Flags: TVtsCurConvFlags; HistoricDate: TDate): Integer; stdcall;
171
function AcceptedCurrenciesA(WriteTo: LPSTR; MaxAge: integer; Flags: TVtsCurConvFlags; HistoricDate: TDate): Integer; stdcall;
172
</pre>
173
<h4>C</h5>
174
<pre>
175
int __stdcall AcceptedCurrencies(LPTSTR WriteTo, int MaxAge, DWORD Flags, DATE HistoricDate);
176
int __stdcall AcceptedCurrenciesW(LPWSTR WriteTo, int MaxAge, DWORD Flags, DATE HistoricDate);
177
int __stdcall AcceptedCurrenciesA(LPSTR WriteTo, int MaxAge, DWORD Flags, DATE HistoricDate);
178
</pre>
179
 
180
<h3>Description</h4>
181
<p>Shows a list of available currencies.</p>
182
 
183
<h3>Parameters</h4>
184
<ul>
185
        <li>WriteTo: A pointer to which the available currencies will be written to. Please reserve at least (NumOfCurrencies*3+1) characters of memory. To query how many currencies are available, please invoke the method once and set this parameter to NULL. All currencies will be appended in the format as defined in ISO-4217. Example: "USDEURCAD\0" will be a list of USD, EUR and CAD.</li>
186
        <li>MaxAge: Defines, after which amount of time the exchange data needs to be re-downloaded from the server.<ul>
187
                <li>-1: Only download once</li>
188
                <li&gt;0: Always download, on each request (attention: API keys may have limited amount of accesses per month)</li>
189
                <li>&gt;0: Download after the supplied amount of time (in seconds)</li>
190
        </ul></li>
191
        <li>Flags: Is a sum of following components:<ul>
192
                <li>CONVERT_DONT_SHOW_ERRORS (1): Don't show errors in a dialog box.</li>
193
                <li>CONVERT_FALLBACK_TO_CACHE (2): If download failed, use the previous downloaded cache file, even if it is older than MaxAge.</li>
194
                <li>CONVERT_USE_SSL (4): Use SSL to download the data. Note that only a paid subscription allows download via SSL.</li>
195
                <li>CONVERT_CONFIRM_WEB_ACCESS (8): Ask the user each time the API tries to download from the web.</li>
196
                <li>CONVERT_NO_INTERACTIVE_API_KEY_INPUT (16): Don't ask the user for an API key in case the API key is missing or invalid.</li>
197
        </ul></li>
198
        <li>HistoricDate:<ul>
199
                <li&gt;0: Use the current exchange data</li>
200
                <li>any valid DATE: use an historic exchange</li>
201
        </ul></li>
202
</ul>
203
 
204
<h3>Returns</h4>
205
<ul>
206
        <li>-1 if an error occured</li>
207
        <li>&gt;=0 the number of currencies found/written</li>
208
</ul>
209
 
210
<h2 id="DownloadNow">DownloadNow</h3>
211
 
212
<h3>Syntax</h4>
213
<h4>Delphi</h5>
214
<pre>
215
function DownloadNow(Flags: TVtsCurConvFlags; HistoricDate: TDate): HRESULT; stdcall;
216
</pre>
217
<h4>C</h5>
218
<pre>
219
HRESULT __stdcall DownloadNow(DWORD Flags, DATE HistoricDate);
220
</pre>
221
 
222
<h3>Description</h4>
223
<p>Forces the framework to download the currency table.</p>
224
 
225
<h3>Parameters</h4>
226
<ul>
227
        <li>Flags: Is a sum of following components:<ul>
228
                <li>CONVERT_DONT_SHOW_ERRORS (1): Don't show errors in a dialog box.</li>
229
                <li>CONVERT_FALLBACK_TO_CACHE (2): If download failed, use the previous downloaded cache file, even if it is older than MaxAge.</li>
230
                <li>CONVERT_USE_SSL (4): Use SSL to download the data. Note that only a paid subscription allows download via SSL.</li>
231
                <li>CONVERT_CONFIRM_WEB_ACCESS (8): Ask the user each time the API tries to download from the web.</li>
232
                <li>CONVERT_NO_INTERACTIVE_API_KEY_INPUT (16): Don't ask the user for an API key in case the API key is missing or invalid.</li>
233
        </ul></li>
234
        <li>HistoricDate:<ul>
235
                <li&gt;0: Use the current exchange data</li>
236
                <li>any valid DATE: use an historic exchange</li>
237
        </ul></li>
238
</ul>
239
 
240
<h3>Returns</h4>
241
<ul>
242
        <li>S_VTSCONV_OK (0x20000000) if the download was successful.</li>
243
        <li>E_VTSCONV_GENERIC_FAILURE (0xA0000000) if an error occured.</li>
244
</ul>
245
 
246
</body>
247
 
248
</html>