Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>MHonArc v2.5 -- Appendix: Application Programming Interface | |
5 | </title> | |
6 | <style> | |
7 | .cb_head { | |
8 | font-family: monospace; | |
9 | border-color: black; | |
10 | border-style: solid none none none; | |
11 | border-top-width: thin; | |
12 | } | |
13 | .cb_body { | |
14 | padding-left: 1em; | |
15 | } | |
16 | </style> | |
17 | </head> | |
18 | <!-- | |
19 | <BODY background="ssbg75.jpg" | |
20 | text="#000000" link="#0000ee" vlink="#551a8b" alink="ff0000"> | |
21 | --> | |
22 | <body> | |
23 | ||
24 | <!--X-NavButtons-Start--> | |
25 | <table width="100%"> | |
26 | <tr valign="top"> | |
27 | <td align="left"><nobr><a href="app-utilsprg.html"><img src="prev.png"border=0 alt="[Prev]"></a> </nobr></td><td align="center" width="99%"><a href="mhonarc.html"><img src="up.png" border=0 alt="[TOC]"></a><a href="faq/faq.html"><img src="faq.png" border=0 alt="[FAQ]"></a><a href="app-bugs.html"><img src="bug.png" border=0 alt="[Bugs]"></a><a href="http://www.mhonarc.org/"><img src="home.png" border=0 alt="[Home]"></a></td><td align="right"><nobr> <a href="app-mimeconf.html"><img src="next.png" border=0 alt="[Next]"></a></nobr></td></tr></table> | |
28 | <!--X-NavButtons-End--> | |
29 | <hr> | |
30 | ||
31 | <h1><a name="appendixA">Appendix: Application Programming Interface</a></h1> | |
32 | ||
33 | <p>This appendix describes the simple API available to allow the | |
34 | embedding of MHonArc within other Perl programs. | |
35 | </p> | |
36 | ||
37 | <!--X-TOC-Start--> | |
38 | <ul> | |
39 | <li><a href="#init">Initialization</a> | |
40 | <li><a href="#process_input">Processing Input</a> | |
41 | <li><a href="#callback">Callbacks</a> | |
42 | <ul> | |
43 | <li><small><a href="#CBDbPreLoad">$mhonarc::CBDbPreLoad</a></small> | |
44 | <li><small><a href="#CBDbPreSave">$mhonarc::CBDbPreSave</a></small> | |
45 | <li><small><a href="#CBDbSave">$mhonarc::CBDbSave</a></small> | |
46 | <li><small><a href="#CBMessageBodyRead">$mhonarc::CBMessageBodyRead</a></small> | |
47 | <li><small><a href="#CBMessageHeadRead">$mhonarc::CBMessageHeadRead</a></small> | |
48 | <li><small><a href="#CBRawMessageBodyRead">$mhonarc::CBRawMessageBodyRead</a></small> | |
49 | <li><small><a href="#CBRcVarExpand">$mhonarc::CBRcVarExpand</a></small> | |
50 | </ul> | |
51 | <li><a href="#notes">Notes</a> | |
52 | </ul> | |
53 | <!--X-TOC-End--> | |
54 | ||
55 | <!-- ================================================================== --> | |
56 | <hr> | |
57 | <h2><a name="init">Initialization</a></h2> | |
58 | ||
59 | <p>Before calling any MHonarc routines, you must initialize the MHonArc | |
60 | library. The following code snippet shows you how to initialize | |
61 | MHonArc: | |
62 | </p> | |
63 | <pre> | |
64 | <i># Require MHonArc library</i> | |
65 | <b>require 'mhamain.pl';</b> | |
66 | <i># Initialize MHonArc</i> | |
67 | <b>mhonarc::initialize();</b> | |
68 | </pre> | |
69 | <table border=0 cellpadding=4> | |
70 | <tr valign=top> | |
71 | <td><strong>NOTE</strong></td> | |
72 | <td><p>The <tt>mhonarc::initialize()</tt> routine should only be | |
73 | called once within your program. | |
74 | </p> | |
75 | </td> | |
76 | </tr> | |
77 | </table> | |
78 | <table border=0 cellpadding=4> | |
79 | <tr valign=top> | |
80 | <td><strong>NOTE</strong></td> | |
81 | <td><p>If <tt>mhamain.pl</tt> is not in perl's library search path, you | |
82 | will need to add the directory path to perl's search path before | |
83 | calling <tt>require</tt>. | |
84 | </p> | |
85 | </td> | |
86 | </tr> | |
87 | </table> | |
88 | ||
89 | <!-- ================================================================== --> | |
90 | <hr> | |
91 | <h2><a name="process_input">Processing Input</a></h2> | |
92 | ||
93 | <p>To instruct MHonArc to process input, use the following | |
94 | routine: | |
95 | </p> | |
96 | <pre> | |
97 | <i># Tell MHonArc to start processing</i> | |
98 | <b>mhonarc::process_input();</b> | |
99 | </pre> | |
100 | <p>When <tt>mhonarc::process_input()</tt> is called with no | |
101 | arguments, it parses <tt>@ARGV</tt> for command-line arguments. | |
102 | If you pass a list of arguments into <tt>mhonarc::process_input()</tt> | |
103 | then that list will be processed for the command-line arguments. | |
104 | For example: | |
105 | </p> | |
106 | <pre> | |
107 | mhonarc::process_input( | |
108 | '-quiet', | |
109 | '-outdir', $archive_path, | |
110 | '-rcfile', $rcfile, | |
111 | $mailbox_filename | |
112 | ); | |
113 | </pre> | |
114 | <p>The return value of <tt>mhonarc::process_input()</tt> will be | |
115 | the CPU time, in seconds, MHonArc used. Example usage: | |
116 | </p> | |
117 | <pre> | |
118 | $cpu_time = mhonarc::process_input(); | |
119 | </pre> | |
120 | <p>To determine what the status of the processing was, you | |
121 | can query the <tt>$mhonarc::CODE</tt> variable. The value | |
122 | of this variable reflects what the exit status of MHonArc would | |
123 | be if invoked from the shell. I.e. If <tt>$mhonarc::CODE</tt> | |
124 | is equal to 0, then no errors occured during processing. A | |
125 | non-zero value indicates some error occured. Example usage: | |
126 | </p> | |
127 | <pre> | |
128 | mhonarc::process_input( | |
129 | '-quiet', | |
130 | '-outdir', $archive_path, | |
131 | '-rcfile', $rcfile, | |
132 | $mailbox_filename | |
133 | ); | |
134 | if ($mhonarc::CODE) { | |
135 | # error code here | |
136 | } | |
137 | </pre> | |
138 | <table border=0 cellpadding=4> | |
139 | <tr valign=top> | |
140 | <td><strong>NOTE</strong></td> | |
141 | <td><p>If <tt>$mhonarc::CODE</tt> is equal to <tt>75</tt>, this | |
142 | indicates that MHonArc was unable to obtain a lock on the archive. | |
143 | This exit code is recognized by MTAs like <tt>sendmail</tt> to | |
144 | requeue a message and try to deliver it again later. This is | |
145 | useful when MHonArc is invoked by a <tt>sendmail</tt> alias. | |
146 | </p> | |
147 | </td> | |
148 | </tr> | |
149 | </table> | |
150 | ||
151 | <p>It is okay to call <tt>mhonarc::process_input()</tt> multiple times | |
152 | within a single program. This is useful if your program wants | |
153 | to process multiple archives. | |
154 | </p> | |
155 | ||
156 | <!-- ================================================================== --> | |
157 | <hr> | |
158 | <h2><a name="callback">Callbacks</a></h2> | |
159 | ||
160 | <p>Support is available for registering callbacks to be invoked | |
161 | when MHonArc is processing input. To register a callback, all | |
162 | you need to do is set the appriopriate MHonArc | |
163 | variable to a routine reference (hard or symbolic). For example, | |
164 | to set the callback when a message header is read, you can do | |
165 | something like the following: | |
166 | </p> | |
167 | <pre> | |
168 | $mhonarc::CBMessageHeadRead = \&my_callback_routine; | |
169 | </pre> | |
170 | <table border=0 cellpadding=4> | |
171 | <tr valign=top> | |
172 | <td><strong>NOTE</strong></td> | |
173 | <td><p>The | |
174 | <a href="install.html#sitelib"><b><tt>mhasiteinit.pl</tt></b></a> | |
175 | site initialization library can be used to register callbacks. | |
176 | The advantages for using <tt>mhasiteinit.pl</tt> is that it is | |
177 | executed each time MHonArc is executed, and you do not have | |
178 | to create custom front-ends to MHonArc if all you want to | |
179 | do is register callbacks. See | |
180 | <cite><a href="install.html">Installation</a></cite> and the | |
181 | example <tt>mhasiteinit.pl</tt> provided in the <tt>examples/</tt> | |
182 | directory of the MHonArc distribution for more | |
183 | information about <tt>mhasiteinit.pl</tt>. | |
184 | </p> | |
185 | </td> | |
186 | </tr> | |
187 | </table> | |
188 | ||
189 | <p>What follows is the type of callbacks supported by MHonArc: | |
190 | </p> | |
191 | ||
192 | <!-- .................................................................. --> | |
193 | <h3 class="cb_head"><a name="CBDbPreLoad">$mhonarc::CBDbPreLoad</a></h3> | |
194 | ||
195 | <div class="cb_body"> | |
196 | <p>Invoked just before the | |
197 | <a href="resources/dbfile.html">database file</a> is loaded. | |
198 | </p> | |
199 | ||
200 | <p><b>Synopsis:</b></p> | |
201 | <pre> | |
202 | $do_load = &$mhonarc::CBDbPreLoad($pathname); | |
203 | </pre> | |
204 | ||
205 | <p><b>Arguments:</b></p> | |
206 | <dl> | |
207 | <dt><tt>$pathname</tt></dt> | |
208 | <dd><p>Pathname to <a href="resources/dbfile.html">database file</a> | |
209 | that will be loaded. | |
210 | </p> | |
211 | </dl> | |
212 | ||
213 | <p><b>Return Value:</b></p> | |
214 | <p>If a true value, MHonArc will load the database denoted by | |
215 | <tt>$pathname</tt>. If a false value, MHonArc will skip loading the | |
216 | database file. | |
217 | </p> | |
218 | ||
219 | <p><b>Notes:</b></p> | |
220 | <ul> | |
221 | <li><p>This callback, along with | |
222 | <a href="#CBPreSave"><tt>$mhonarc::CBDbPreSave</tt></a> (in theory), | |
223 | can be used to provide a customized loading and saving of MHonArc | |
224 | archive information. | |
225 | </p> | |
226 | </ul> | |
227 | </div> | |
228 | ||
229 | <!-- .................................................................. --> | |
230 | <h3 class="cb_head"><a name="CBDbPreSave">$mhonarc::CBDbPreSave</a></h3> | |
231 | ||
232 | <div class="cb_body"> | |
233 | <p>Invoked before data is saved to the | |
234 | <a href="resources/dbfile.html">database file</a>. | |
235 | </p> | |
236 | ||
237 | <p><b>Synopsis:</b></p> | |
238 | <pre> | |
239 | $do_save = &$mhonarc::CBDbPreSave($pathname, $tmp_pathname); | |
240 | </pre> | |
241 | ||
242 | <p><b>Arguments:</b></p> | |
243 | <dl> | |
244 | <dt><tt>$pathname</tt></dt> | |
245 | <dd><p>Pathname to database file that will be written to. | |
246 | </p> | |
247 | ||
248 | <dt><tt>$tmp_pathname</tt></dt> | |
249 | <dd><p>Pathname temporary file that data will be written to before | |
250 | replacing <tt>$pathname</tt>. Data is written to a temporary | |
251 | file first to prevent any I/O, or other, errors leaving a corrupt | |
252 | database. If the data is written successfully, MHonArc renames | |
253 | <tt>$tmp_pathname</tt> to <tt>$pathname</tt>. | |
254 | </p> | |
255 | </dl> | |
256 | ||
257 | <p><b>Return Value:</b></p> | |
258 | <p>If a true value, MHonArc will save the data to | |
259 | <tt>$pathname</tt>. If a false value, MHonArc will skip writing | |
260 | the database file. | |
261 | </p> | |
262 | ||
263 | <p><b>Notes:</b></p> | |
264 | <ul> | |
265 | <li><p>Generally, this function should always return a true value. This | |
266 | can easily be done by having the following statement at the end of | |
267 | the callback: <code>return 1;</code> | |
268 | </p> | |
269 | <p>A possible scenario where a false value may be returned if for | |
270 | cases where a customized format is used to save the data and the | |
271 | <a href="#CBDbPreLoad"><tt>$mhonarc::CBDbPreLoad</tt></a> function | |
272 | is defined to provide a customized way to load database data. | |
273 | </p> | |
274 | </ul> | |
275 | </div> | |
276 | ||
277 | <!-- .................................................................. --> | |
278 | <h3 class="cb_head"><a name="CBDbSave">$mhonarc::CBDbSave</a></h3> | |
279 | ||
280 | <div class="cb_body"> | |
281 | <p>Invoked when data has been written to | |
282 | <a href="resources/dbfile.html">database file</a>. | |
283 | </p> | |
284 | ||
285 | <p><b>Synopsis:</b></p> | |
286 | <pre> | |
287 | &$mhonarc::CBDbSave($db_fh); | |
288 | </pre> | |
289 | ||
290 | <p><b>Arguments:</b></p> | |
291 | <dl> | |
292 | <dt><tt>$db_fh</tt></dt> | |
293 | <dd><p>Open filehandle to database file. This filehandle can be | |
294 | used to write custom information to the database file. | |
295 | </p> | |
296 | <p><b>Note:</b> Any data written to <tt>$db_fh</tt> must be legal | |
297 | Perl code. | |
298 | </p> | |
299 | </dl> | |
300 | ||
301 | <p><b>Return Value:</b></p> | |
302 | <p>N/A</p> | |
303 | ||
304 | </div> | |
305 | ||
306 | <!-- .................................................................. --> | |
307 | <h3 class="cb_head"><a name="CBMessageBodyRead">$mhonarc::CBMessageBodyRead</a></h3> | |
308 | ||
309 | <div class="cb_body"> | |
310 | <p>The callback function after a mail message body has been read a converted. | |
311 | </p> | |
312 | ||
313 | <p><b>Synopsis:</b></p> | |
314 | <pre> | |
315 | &$mhonarc::CBMessageBodyRead( | |
316 | $fields_hash_ref, $html_text_ref, $files_array_ref); | |
317 | </pre> | |
318 | ||
319 | <p><b>Arguments:</b></p> | |
320 | <dl> | |
321 | <dt><tt>$fields_hash_ref</tt></dt> | |
322 | <dd><p>Reference to hash containing parsed message header. The | |
323 | structure of this hash is the same as described for | |
324 | the <a href="#CBMessageHeadRead"><tt>$mhonarc::CBMessageHeadRead</tt></a> | |
325 | callback. | |
326 | </p> | |
327 | ||
328 | <dt><tt>$html_text_ref</tt></dt> | |
329 | <dd><p>Reference to string contain the HTML markup for the | |
330 | body. Modifications to the referenced data will be | |
331 | reflected in the message page generated. Therefore, | |
332 | care should be observed when doing any modification. | |
333 | </p> | |
334 | <p>If MHonArc was unable to convert the body of the | |
335 | message, the following expression will evaluate to | |
336 | true: | |
337 | </p> | |
338 | <pre> | |
339 | $$html_text_ref eq ""</pre> | |
340 | <p>If this is the case, you could set the value | |
341 | of $$html_text_ref to something else to customize | |
342 | the warning text MHonArc uses in the message page | |
343 | written. | |
344 | </p> | |
345 | ||
346 | <dt><tt>$files_array_ref</tt></dt> | |
347 | <dd><p>Reference to array of derived files when the body | |
348 | was converted. Each file is typically relative | |
349 | to <tt>$mhonarc::OUTDIR</tt>, unless it is a full pathname. | |
350 | the <tt>mhonarc::OSis_absolute_path($filename)</tt> can | |
351 | be used to determine if a file is an absolute | |
352 | pathname or not. Note, it is possible that a | |
353 | file could designate a directory; this indicates | |
354 | that the directory, and all files in the directory, | |
355 | are derived. | |
356 | </p> | |
357 | <p>Modifications to the array will affect the list | |
358 | of derived files MHonArc stores for the message. | |
359 | You can add files to the array if your routine | |
360 | creates files, but you can also delete items if | |
361 | your routine removes files; <b>CAUTION</b>: the HTML markup | |
362 | typically contains links to derived files so removing | |
363 | files could cause broken links unless <tt>$html_text_ref</tt> | |
364 | is modified to reflect the file deletions. | |
365 | </p> | |
366 | </dl> | |
367 | ||
368 | <p><b>Return Value:</b></p> | |
369 | <p>N/A</p> | |
370 | ||
371 | <p><b>Notes:</b></p> | |
372 | <ul> | |
373 | <li><p>To distinquish between | |
374 | <a href="resources/single.html">SINGLE</a> | |
375 | operation mode and | |
376 | archive operation mode, you can check the <tt>$mhonarc::SINGLE</tt> | |
377 | variable. For example: | |
378 | </p> | |
379 | <pre> | |
380 | if ($mhonarc::SINGLE) { | |
381 | # single message-based processing here | |
382 | } else { | |
383 | # archive-based processing here | |
384 | } | |
385 | </pre> | |
386 | ||
387 | <li><p>The <tt>$mhonarc::CBMessageBodyRead</tt> routine can be used | |
388 | to trigger automatic virus scanning of attachments. | |
389 | </p> | |
390 | </ul> | |
391 | </div> | |
392 | ||
393 | <!-- .................................................................. --> | |
394 | <h3 class="cb_head"><a name="CBMessageHeadRead">$mhonarc::CBMessageHeadRead</a></h3> | |
395 | ||
396 | <div class="cb_body"> | |
397 | <p>The callback function after a | |
398 | mail message header is read and before any other processing is done. | |
399 | Note, the function is called after any exclusion checks | |
400 | (<a href="resources/checknoarchive.html">CHECKNOARCHIVE</a> and | |
401 | <a href="resources/msgexcfilter.html">MSGEXCFILTER</a>) | |
402 | are | |
403 | performed by MHonArc. | |
404 | </p> | |
405 | <p><b>Synopsis:</b></p> | |
406 | <pre> | |
407 | $boolean = &$mhonarc::CBMessageHeadRead( | |
408 | $fields_hash_ref, $raw_header_txt); | |
409 | </pre> | |
410 | ||
411 | <p><b>Arguments:</b></p> | |
412 | <dl> | |
413 | <dt><tt>$fields_hash_ref</tt></dt> | |
414 | <dd><p>Reference to hash containing parsed message header. Keys | |
415 | are the lowercase field names and the values are references | |
416 | to array contain the values for each field. If a field | |
417 | is only declared once in the header, the array will only | |
418 | contain one item. | |
419 | For example, to access the raw subject text, | |
420 | do the following: | |
421 | <code>$fields_hash_ref->{'subject'}[0];</code> | |
422 | </p> | |
423 | <p>The hash also contains special keys represented the values | |
424 | MHonArc has extracted when parsing the message header. | |
425 | The values of these keys are regular scalars and NOT | |
426 | array references. The following summarizes the keys | |
427 | made available: | |
428 | </p> | |
429 | <dl> | |
430 | <dt><tt>x-mha-index</tt></dt> | |
431 | <dd>The assigned index given to the message by MHonArc. | |
432 | </dd> | |
433 | <dt><tt>x-mha-message-id</tt></dt> | |
434 | <dd>The message-id MHonArc extracted. Note, if the | |
435 | message did not specified a message ID, MHonArc | |
436 | auto-generates one. | |
437 | </dd> | |
438 | <dt><tt>x-mha-from</tt></dt> | |
439 | <dd>Who MHonArc thinkgs the message is from. This value | |
440 | is controled by the <a href="resources/fromfields.html">FROMFIELDS</a> | |
441 | resource. | |
442 | </dd> | |
443 | <dt><tt>x-mha-subject</tt></dt> | |
444 | <dd>The message subject that will be used by MHonArc. The | |
445 | value may be different from the raw subject text of the message | |
446 | since <a href="resources/subjectstripcode.html">SUBJECTSTRIPCODE</a> | |
447 | code will have been applied. | |
448 | If no subject is defined, then the value is the empty string. | |
449 | </dd> | |
450 | <dt><tt>x-mha-content-type</tt></dt> | |
451 | <dd>The content-type of the message MHonArc will use for | |
452 | the message. | |
453 | </dd> | |
454 | </dl> | |
455 | <p>For example, to access the subject text that MHonArc will use, | |
456 | do the following: | |
457 | <code>$fields_hash_ref->{'x-mha-subject'};</code> | |
458 | </p> | |
459 | </dd> | |
460 | ||
461 | <dt><tt>$raw_header_txt</tt></dt> | |
462 | <dd><p>The raw header data of the message. This data may be | |
463 | useful if pattern matches are desired against header | |
464 | data. | |
465 | </p> | |
466 | </dd> | |
467 | </dl> | |
468 | ||
469 | <p><b>Return Value:</b></p> | |
470 | <p>The return value is used by MHonArc to determine if the | |
471 | message should be excluded from any further processing. | |
472 | If the return value evaluates to true, then MHonArc will | |
473 | continue processing of the message. If the return value | |
474 | evaluates to false, the message will be excluded. | |
475 | </p> | |
476 | ||
477 | <p><b>Notes:</b></p> | |
478 | <ul> | |
479 | <li><p>To distinquish between | |
480 | <a href="resources/single.html">SINGLE</a> | |
481 | operation mode and | |
482 | archive operation mode, you can check the <tt>$mhonarc::SINGLE</tt> | |
483 | variable. For example: | |
484 | </p> | |
485 | <pre> | |
486 | if ($mhonarc::SINGLE) { | |
487 | # single message-based processing here | |
488 | } else { | |
489 | # archive-based processing here | |
490 | } | |
491 | </pre> | |
492 | ||
493 | <li><p>MHonArc resources exist that allow message exclusion | |
494 | capabilities: | |
495 | <a href="resources/checknoarchive.html">CHECKNOARCHIVE</a>, | |
496 | <a href="resources/expireage.html">EXPIREAGE</a>, | |
497 | <a href="resources/expiredate.html">EXPIREDATE</a>, | |
498 | and | |
499 | <a href="resources/msgexcfilter.html">MSGEXCFILTER</a>. | |
500 | If possible, use these resources to perform message exclusion filtering. | |
501 | </p> | |
502 | </ul> | |
503 | </div> | |
504 | ||
505 | <!-- .................................................................. --> | |
506 | <h3 class="cb_head"><a name="CBRawMessageBodyRead">$mhonarc::CBRawMessageBodyRead</a></h3> | |
507 | ||
508 | <div class="cb_body"> | |
509 | <p>Invoked with the raw message body data is read from input. I.e. | |
510 | The message body has not been converted. | |
511 | </p> | |
512 | ||
513 | <p><b>Synopsis:</b></p> | |
514 | <pre> | |
515 | &$mhonarc::CBRawMessageBodyRead($fields_hash_ref, $body_data_ref); | |
516 | </pre> | |
517 | ||
518 | <p><b>Arguments:</b></p> | |
519 | <dl> | |
520 | <dt><tt>$fields_hash_ref</tt></dt> | |
521 | <dd><p>Reference to hash containing parsed message header. The | |
522 | structure of this hash is the same as described for | |
523 | the <a href="#CBMessageHeadRead"><tt>$mhonarc::CBMessageHeadRead</tt></a> | |
524 | callback. | |
525 | </p> | |
526 | ||
527 | <dt><tt>$body_data_ref</tt></dt> | |
528 | <dd><p>Reference to string contain the raw data of the message | |
529 | body. Modifications to the referenced data can be performed | |
530 | to change what data MHonArc will process. | |
531 | </p> | |
532 | ||
533 | </dl> | |
534 | ||
535 | <p><b>Return Value:</b></p> | |
536 | <p>N/A</p> | |
537 | ||
538 | </div> | |
539 | ||
540 | <!-- .................................................................. --> | |
541 | <h3 class="cb_head"><a name="CBRcVarExpand">$mhonarc::CBRcVarExpand</a></h3> | |
542 | ||
543 | <div class="cb_body"> | |
544 | <p>Invoked when a resource variable is to be expanded. With this callback, | |
545 | you can override and/or augment MHonArc's built-in resource variable | |
546 | expansion support. | |
547 | </p> | |
548 | ||
549 | <p><b>Synopsis:</b></p> | |
550 | <pre> | |
551 | ($result, $do_expand_again, $can_clip) = | |
552 | &$mhonarc::CBRcVarExpand($mha_index, $var_name, $arg_string); | |
553 | </pre> | |
554 | ||
555 | <p><b>Arguments:</b></p> | |
556 | <dl> | |
557 | <dt><tt>$mha_index</tt></dt> | |
558 | <dd><p>The MHonArc index key of the current message. | |
559 | </p> | |
560 | ||
561 | <dt><tt>$var_name</tt></dt> | |
562 | <dd><p>The variable name being expanded. | |
563 | For example, given the resource variable reference, | |
564 | "<tt>$VARIABLE$</tt>", <tt>$var_name</tt> would be equal to | |
565 | "<tt>VARIABLE</tt>". | |
566 | </p> | |
567 | ||
568 | <dt><tt>$arg_string</tt></dt> | |
569 | <dd><p>The argument string for the resource variable reference. | |
570 | For example, given the resource variable reference, | |
571 | "<tt>$VARIABLE(arg1)$</tt>", <tt>$arg_string</tt> would be equal to | |
572 | "<tt>arg1</tt>". | |
573 | </p> | |
574 | <p><b>Note:</b> MHonArc generally uses the character '<tt>;</tt>' | |
575 | to separate multiple arguments to a resource variable. However, | |
576 | this is only convention, and if defining your own resource variable | |
577 | support via this callback, you can use whatever convention you like. | |
578 | </p> | |
579 | </dl> | |
580 | ||
581 | <p><b>Return Value:</b></p> | |
582 | <p>The return value is a list of values interpreted as follows:</p> | |
583 | <dl> | |
584 | <dt><tt>$result</tt></dt> | |
585 | <dd><p>The result (or replace text) for the variable. If | |
586 | the result is equal to <tt>undef</tt>, MHonArc's built-in | |
587 | expansion code will be invoked to expand <tt>$var_name</tt>. | |
588 | If <tt>$result</tt> is defined, then MHonArc's built-in | |
589 | expansion will be skipped. | |
590 | </p> | |
591 | </dd> | |
592 | ||
593 | <dt><tt>$do_expand_again</tt></dt> | |
594 | <dd><p>If a true value, MHonArc will parse <tt>$result</tt> and | |
595 | expand any resource variables contained within. | |
596 | <b>Note:</b> <tt>$mhonarc::CBRcVarExpand</tt> will be | |
597 | called for each resource variable found. | |
598 | </p> | |
599 | </dd> | |
600 | ||
601 | <dt><tt>$can_clip</tt></dt> | |
602 | <dd><p>If a true value, clipping is allowed to be performed. | |
603 | Clipping is done if max length specification is specified | |
604 | in the resource variable reference. | |
605 | </dd> | |
606 | </dl> | |
607 | ||
608 | ||
609 | <p><b>Notes:</b></p> | |
610 | <ul> | |
611 | <li><p>Use the <a href="resources/definevar.html">DEFINEVAR</a> resource | |
612 | whenever possible for defining custom resource variables. The | |
613 | <tt>$mhonarc::CBRcVarExpand</tt> should only be used for cases | |
614 | where the sematics of <a href="resources/definevar.html">DEFINEVAR</a> | |
615 | are insufficient. | |
616 | </p> | |
617 | ||
618 | <li><p>Colon variable modifiers, if specified in the resource | |
619 | variable reference, are applied by MHonArc after | |
620 | <tt>$mhonarc::CBRcVarExpand</tt> is invoked. | |
621 | </p> | |
622 | </ul> | |
623 | </div> | |
624 | ||
625 | <!-- ================================================================== --> | |
626 | <hr> | |
627 | <h2><a name="notes">Notes</a></h2> | |
628 | ||
629 | <ul> | |
630 | ||
631 | <li><p>This API documention is not complete. To get | |
632 | a better idea of what you may be able to do, have a look at the | |
633 | source code for the commands provided in the MHonArc distribution: | |
634 | <tt>mhonarc</tt>, <tt>mha-dbedit</tt>, | |
635 | <tt>mha-dbrecover</tt>, and <tt>mha-decode</tt>. You may also | |
636 | want to look at the source of <tt>mhamain.pl</tt>. | |
637 | </p> | |
638 | ||
639 | <li><p>Only a single archive can be processed at any given time. | |
640 | </p> | |
641 | ||
642 | </ul> | |
643 | ||
644 | <hr> | |
645 | <!--X-NavButtons-Start--> | |
646 | <table width="100%"> | |
647 | <tr valign="top"> | |
648 | <td align="left"><nobr><a href="app-utilsprg.html"><img src="prev.png"border=0 alt="[Prev]"></a> </nobr></td><td align="center" width="99%"><a href="mhonarc.html"><img src="up.png" border=0 alt="[TOC]"></a><a href="faq/faq.html"><img src="faq.png" border=0 alt="[FAQ]"></a><a href="app-bugs.html"><img src="bug.png" border=0 alt="[Bugs]"></a><a href="http://www.mhonarc.org/"><img src="home.png" border=0 alt="[Home]"></a></td><td align="right"><nobr> <a href="app-mimeconf.html"><img src="next.png" border=0 alt="[Next]"></a></nobr></td></tr></table> | |
649 | <!--X-NavButtons-End--> | |
650 | ||
651 | <hr> | |
652 | <address> | |
653 | $Date: 2002/05/02 01:34:30 $ <br> | |
654 | <img align="top" src="monicon.png" alt=""> | |
655 | <a href="http://www.mhonarc.org/" | |
656 | ><strong>MHonArc</strong></a><br> | |
657 | Copyright © 2001, <a href="http://www.earlhood.com/" | |
658 | >Earl Hood</a>, <a href="mailto:mhonarc@mhonarc.org" | |
659 | >mhonarc@mhonarc.org</a><br> | |
660 | </address> | |
661 | ||
662 | </body> | |
663 | </html> |