1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
<head>
<title>SWISH-Enhanced: SWISH-LIBRARY - Interface to the Swish-e C library </title>
<link href="./style.css" rel=stylesheet type="text/css" title="refstyle">
</head>
<body>
<h1 class="banner">
<a href="http://swish-e.org"><img border=0 src="images/swish.gif" alt="Swish-E Logo"></a><br>
<img src="images/swishbanner1.gif"><br>
<img src="images/dotrule1.gif"><br>
SWISH-LIBRARY - Interface to the Swish-e C library
</h1>
<hr>
<p>
<div class="navbar">
<a href="./SWISH-3.0.html">Prev</a> |
<a href="./index.html">Contents</a> |
<a href="./API.html">Next</a>
</div>
<p>
<div class="toc">
<A NAME="toc"></A>
<P><B>Table of Contents:</B></P>
<UL>
<LI><A HREF="#What_is_the_Swish_e_C_library_">What is the Swish-e C library?</A>
<LI><A HREF="#Installing_the_Swish_e_library">Installing the Swish-e library</A>
<LI><A HREF="#Library_Overview">Library Overview</A>
<LI><A HREF="#Available_Functions">Available Functions</A>
<UL>
<LI><A HREF="#Searching">Searching</A>
<LI><A HREF="#Reading_Results">Reading Results</A>
<LI><A HREF="#Accessing_the_Index_Header_Values">Accessing the Index Header Values</A>
<LI><A HREF="#Accessing_Property_Meta_Data">Accessing Property Meta Data</A>
<LI><A HREF="#Checking_for_Errors">Checking for Errors</A>
<LI><A HREF="#Utility_Functions">Utility Functions</A>
</UL>
<LI><A HREF="#Bug_Reports">Bug-Reports</A>
<LI><A HREF="#Author">Author</A>
<LI><A HREF="#Document_Info">Document Info</A>
</UL>
</div>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<P>
<H1><A NAME="What_is_the_Swish_e_C_library_">What is the Swish-e C library?</A></H1>
<P>
The C library in an interface to the Swish-e search code. It provides a way
to embed Swish-e into your applications. This API is based on Swish-e
version 2.3.
<P>
<STRONG>Note:</STRONG> This is a NEW API as of Swish-e version 2.3. The C language interface has
changed as has the perl interface to Swish-e. The new Perl interface is the
SWISH::API module and is included with the Swish-e distribution. The old
SWISHE perl module has been rewritten to work with the new API. The SWISHE
perl module is no longer included with the Swish-e distribution, but can be
downloaded from the Swish-e web site.
<P>
The advantage of the library is that the index files or files can be opened
one time and many queries made on the open index. This saves the startup
time required to fork and run the swish-e binary, and the expensive time of
opening up the index file. Some benchmarks have shown a three fold increase
in speed.
<P>
The downside is that your program now has more code and data in it (the
index tables can use quite a bit of memory), and if a fatal error happens
in swish it will bring down your program. These are things to think about,
especially if embedding swish into a web server such as Apache where there
are many processes serving requests.
<P>
The best way to learn about the library is to look at two files included
with the Swish-e distribution that make use of the library.
<DL>
<P><DT><STRONG><A NAME="item_src">src/libtest.c</A></STRONG><DD>
<P>
This file gives a basic overview of linking a C program with the Swish-e
library. Not all available functions are used in that example, but it
should give you a good overview of building a C program with swish-e.
<P>
To build and run libtest chdir to the src directory and run the commands:
<P>
<table>
<tr>
<td bgcolor="#eeeeee" width="1">
</td>
<td>
<pre> $ make libtest
$ ./libtest [optional name of index file]</pre>
</td>
</tr>
</table>
<P>
You will be prompted for the search words. The default index used is <EM>index.swish-e</EM>. This can be overridden by placing a list of index files in a
quote-protected string.
<P>
<table>
<tr>
<td bgcolor="#eeeeee" width="1">
</td>
<td>
<pre> $ ./libtest 'index1 index2 index3'</pre>
</td>
</tr>
</table>
<P><DT><STRONG><A NAME="item_perl">perl/API.xs</A></STRONG><DD>
<P>
The <EM>API.xs</EM> file is a Perl "xsub" interface to the C library and is part of
the SWISH::API Perl module. This is an object-oriented interface to the
Swish-e library and demonstrates how the various search "objects"
are created by C calls and how they are destroyed when no longer needed.
</DL>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H1><A NAME="Installing_the_Swish_e_library">Installing the Swish-e library</A></H1>
<P>
The Swish-e library is installed when you run "make install" when
building Swish-e. No extra installation steps are required.
<P>
The library consists of a header file "swish-e.h" and a library
"libswish-e.*" that can either be a static or shared library
depending on your platform.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H1><A NAME="Library_Overview">Library Overview</A></H1>
<P>
When you first attach to an index file (or index files) you are returned a
"swish handle". From the handle you create one or more
"search objects" which holds the parameters to query the index,
such as the query string, sort order, search phrase delimiter, limit
parameters and HTML structure bits. The "object" is really just a
pointer to a C structure, but it's helpful to think of it as an object that
data and functionality associated with it.
<P>
The search object is used to query the index. A query returns a
"results object". The results object holds the number of hits,
the parsed query per index, and the result set. The results object keeps
track of the current position in the result set. You may "seek"
to a specific record within the result set (useful for displaying a page of
results).
<P>
Finally, a result object represents a single result from the result list. A
result object provides access to the result's properties (such as file
name, rank, etc.).
<P>
In addition to results, there are functions available to access the header
values stored in the index file, functions to check and report errors, and
a few utility functions.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H1><A NAME="Available_Functions">Available Functions</A></H1>
<P>
Below is the list of available function included in the Swish-e C language
API.
<P>
These functions (and typedefs) are defined in the <EM>swish-e.h</EM> header file. The common objects (e.g. structures) used are:
<P>
<table>
<tr>
<td bgcolor="#eeeeee" width="1">
</td>
<td>
<pre> SW_HANDLE - swish handle that associates with an index file
SW_SEARCH - search "object" that holds search parameters
SW_RESULTS - results "object" that holds a result set
SW_RESULT - a single result used for accessing the result's properties
SW_FUZZYWORD - used for fuzzy (stemming) word conversion </pre>
</td>
</tr>
</table>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H2><A NAME="Searching">Searching</A></H2>
<DL>
<P><DT><STRONG><A NAME="item_SW_HANDLE">SW_HANDLE SwishInit(char *IndexFiles);</A></STRONG><DD>
<P>
This functions opens and reads the header info of the index files included
in IndexFiles string. The string should contain a space-separated list of
index files.
<P>
<table>
<tr>
<td bgcolor="#eeeeee" width="1">
</td>
<td>
<pre> SW_HANDLE myhandle;
myhandle = SwishInit("file1.idx");</pre>
</td>
</tr>
</table>
<P>
Typically you will open a handle at the beginning of your program and use
it to make multiple queries on an index.
<P>
This function will always return a swish handle. You must check for errors,
and on error free the memory used by the handle, or abort.
<P>
Here's an example of aborting:
<P>
<table>
<tr>
<td bgcolor="#eeeeee" width="1">
</td>
<td>
<pre> SW_HANDLE swish_handle;
swish_handle = SwishInit("file1.idx file2.idx");
if ( SwishError( swish_handle ) )
SwishAbortLastError( swish_handle );</pre>
</td>
</tr>
</table>
<P>
And here's an example of catching the error:
<P>
<table>
<tr>
<td bgcolor="#eeeeee" width="1">
</td>
<td>
<pre> SW_HANDLE swish_handle;
swish_handle = SwishInit("file1.idx file2.idx");
if ( SwishError( swish_handle ) )
{
printf("Failed to connect to swish. %s\n", SwishErrorString( swish_handle ) );
SwishClose( swish_handle ); /* free the memory used */
return 0;
}</pre>
</td>
</tr>
</table>
<P>
You may have more than one handle active at a time.
<P>
Swish-e will not tell you if the index file changes on disk (such as after
reindexing). In a persistent environment (e.g. mod_perl) the calling
program should check to see if the index file has changed on disk. A common
way to do this is to store the inode number before opening the index
<CODE>file(s),</CODE> and then stat the file name every so often and reopen
the index files if the inode number changes.
<P><DT><STRONG><A NAME="item_void">void SwishClose(SW_HANDLE handle);</A></STRONG><DD>
<P>
This function closes and frees the memory of a Swish handle. Every swish
handle should be freed when done searching the index. Failing to close the
handle will result in a memory leak.
<P><DT><STRONG><A NAME="item_SW_SEARCH">SW_SEARCH New_Search_Object(SW_HANDLE handle, const char *query);</A></STRONG><DD>
<P>
Returns a new search "object". The search object holds the
parameters used for searching an index. A single search object can be used
to query the index multiple times. The available settings listed below are
"sticky" in that they remain set on the search object until
change.
<P><DT><STRONG>void SwishSetStructure( SW_SEARCH srch, int structure );</STRONG><DD>
<P>
Sets the "structure" flag in the search object. The structure
flag is used to limit searches to parts of HTML files (such as to the title
or headers). The default is to not limit. This provides the functionality
of the -H command line switch.
<P><DT><STRONG>void SwishPhraseDelimiter( SW_SEARCH srch, char delimiter );</STRONG><DD>
<P>
Sets the phrase delimiter character. The default is double-quotes.
<P><DT><STRONG>void SwishSetSort( SW_SEARCH srch, char *sort );</STRONG><DD>
<P>
Sets the sort order of the results. This is the same as the -s switch used
with the swish-e binary.
<P><DT><STRONG>void SwishSetQuery( SW_SEARCH srch, char *query );</STRONG><DD>
<P>
Sets the query string in the search object. This typically is not needed
since it can be set when creating the search object or when executing a
query.
<P><DT><STRONG>void SwishSetSearchLimit( SW_SEARCH srch, char *propertyname, char *low, char *hi);</STRONG><DD>
<P>
Sets the limit parameters for a search. Provides the same functionality as
the -L command line switch. You may specify a range of property values that
search results must be within. You may call
<CODE>SwishSetSearchLimit()</CODE> only one time for each property (but can
set limits on more than one property at a time).
<P>
Unlike the other settings on the search object, once you run a query on the
search object you must call <CODE>SwishResetSearchLimit()</CODE> to change
or clear the limit parameters.
<P><DT><STRONG>void SwishResetSearchLimit( SW_SEARCH srch );</STRONG><DD>
<P>
Resets the limits set on a search object set by
<CODE>SwishSetSearchLimit().</CODE>
<P><DT><STRONG>void Free_Search_Object( SW_SEARCH srch );</STRONG><DD>
<P>
Frees the search object. This must be called when done with the search
object. Generally, you can reuse a search object for multiple queries so
typically you would call this right before calling
<CODE>SwishClose().</CODE>
<P>
You may free the search object before freeing and generated results
objects.
<P><DT><STRONG><A NAME="item_SW_RESULTS">SW_RESULTS SwishExecute( SW_SEARCH search, const char *query);</A></STRONG><DD>
<P>
Searches the index or indexes based on the parameters in the search object.
Returns a results object. See below for functions to access the data stored
in the results object.
<P>
You should always check for errors after calling
<CODE>SwishExecute().</CODE>
<P><DT><STRONG>SW_RESULTS SwishQuery(SW_HANDLE, const char *words );</STRONG><DD>
<P>
This is a short-cut function that bypasses the creation of a search object
(actually, bypasses the need to create and free a search object). This only
allows passing in a query string; other search parameters cannot be set.
The results are sorted by rank.
<P>
You should always check for errors after calling <CODE>SwishQuery().</CODE>
</DL>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H2><A NAME="Reading_Results">Reading Results</A></H2>
<DL>
<P><DT><STRONG><A NAME="item_int">int SwishHits( SW_RESULTS results );</A></STRONG><DD>
<P>
Returns the number of results in the results object.
<P><DT><STRONG><A NAME="item_SWISH_HEADER_VALUE">SWISH_HEADER_VALUE SwishParsedWords( SW_RESULTS, const char *index_name );</A></STRONG><DD>
<P>
Returns the tokenized query. Words are split by WordCharacters and
stopwords are removed. The parsed words are useful for highlighting search
terms in your program.
<P>
The "index_name" is the name of the index supplied in the
<CODE>SwishInit()</CODE> function call.
<P>
Returns a SWISH_HEADER_VALUE union of type SWISH_LIST which is a char **.
See src/libtest.c for an example of accessing the strings in this list, but
in general you may cast this to a (char **).
<P><DT><STRONG>SWISH_HEADER_VALUE SwishRemovedStopwords( SW_RESULTS, const char *index_name );</STRONG><DD>
<P>
Returns a list of stopwords removed from the input query.
<P>
Returns a SWISH_HEADER_VALUE union of type SWISH_LIST which is a char **.
See src/libtest.c for an example of accessing the strings in this list, but
in general you may cast this to a (char **).
<P><DT><STRONG>int SwishSeekResult( SW_RESULTS, int position );</STRONG><DD>
<P>
Sets the current seek position in the list of results, with position zero
being the first record (unlike -b where one is the first result).
<P>
Returns the position or a negative number on error.
<P><DT><STRONG><A NAME="item_SW_RESULT">SW_RESULT SwishNextResult( SW_RESULTS );</A></STRONG><DD>
<P>
Returns the next result, or NULL if not more results are available.
<P>
The result object returned does not need to be freed after use (unlike the
swish handle, search object, and results object).
<P><DT><STRONG><A NAME="item_const">const char *SwishResultPropertyStr(SW_RESULT, char *propertyname);</A></STRONG><DD>
<P>
This function is mostly useful for testing as it returns odd results on
errors.
<P>
Aborts if called with a NULL SW_RESULT object
<P>
Returns a string value of the specified property.
<P>
Returns the empty string "" if the current result does not have
the specified property assigned.
<P>
Returns the string "(null)" on invalid property name (i.e.
property name is not defined in the index) and sets an error (see below)
indicating the invalid property name.
<P>
The string returned does not need to be freed, but is only valid for the
current result. If you wish to save the string you must copy it locally.
<P>
Dates are formatted using the hard-coded format string: "%Y-%m-%d
%H:%M:%S" in localtime.
<P><DT><STRONG><A NAME="item_unsigned">unsigned long SwishResultPropertyULong(SW_RESULT r, char *propertyname);</A></STRONG><DD>
<P>
Returns a numeric property as an unsigned long. Numeric properties are used
for both PropertyNamesNumeric and PropertyNamesDate type of properties.
Dates are returned as a unix timestamp as reported by the system when the
index was created.
<P>
Swish-e will abort if called with a NULL SW_RESULT object. Without the
SW_RESULT object swish-e cannot set any error codes.
<P>
On error returns UMAX_LONG. This is commonly defined in limits.h. Check
<CODE>SwishError()</CODE> (see below) for the type of error.
<P>
If <CODE>SwishError()</CODE> returns false (zero) then it simply means that
this result does not have any data for the specified property.
<P>
If <CODE>SwishError()</CODE> returns true (non-zero) then either the
propertyname specified is invalid, or the property requested is not a
numeric (or date) property (e.g. it's a string property).
<P>
See below on how to fetch the specific error message when
<CODE>SwishError()</CODE> is true.
<P><DT><STRONG><A NAME="item_PropValue">PropValue *getResultPropValue (SW_RESULT r, char *propertyname, int ID );</A></STRONG><DD>
<P>
This is a low-level function to fetch a property regardless of type. This
is likely the best function for accessing properties.
<P>
Swish-e will abort if called with a NULL SW_RESULT object. Propertyname is
the name of the property. ID is the id number of the property, if known. ID
is not normally used in the API, but it's purpose is to avoid looking up
the property ID for every result displayed.
<P>
The return PropValue is a structure that contains a flag to indicate the
type, and a union that holds the property value. They flags and structure
are defined in swish-e.h.
<P>
The property must be copied locally and the returned "PropValue"
value must be freed by calling <CODE>freeResultPropValue()</CODE> to avoid
a memory leak.
<P>
On error returns NULL. Check <CODE>SwishError()</CODE> (see below) for the
type of error.
<P>
If returns NULL but <CODE>SwishError()</CODE> returns false (zero) then it
simply means that this result does not have any data for the specified
property.
<P>
If <CODE>SwishError()</CODE> returns true (non-zero) then the property name
specified is invalid (i.e. not defined for the index).
<P>
See below on how to fetch the specific error message when
<CODE>SwishError()</CODE> is true.
<P>
See perl/API.xs for an example on using this function.
<P><DT><STRONG>void freeResultPropValue(void)</STRONG><DD>
<P>
Frees the "PropValue" returned after calling
<CODE>getResultPropValue().</CODE>
<P><DT><STRONG>void Free_Results_Object( SW_RESULTS results );</STRONG><DD>
<P>
Frees the results object (frees the result set). This must be called when
done reading the results and before calling <CODE>SwishClose().</CODE>
</DL>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H2><A NAME="Accessing_the_Index_Header_Values">Accessing the Index Header Values</A></H2>
<P>
Each index file has associated header values that describe the index. These
functions provide access to this data. The header data is returned as a
union SWISH_HEADER_VALUE, and a pointer to a SWISH_HEADER_TYPE is passed in
and the returned value indicates the type of data that is returned. See
src/libtest.c and perl/API.xs for examples.
<DL>
<P><DT><STRONG>const char **SwishHeaderNames( SW_HANDLE );</STRONG><DD>
<P>
Returns the list of possible header names. This list is the same for all
index files of a given version of Swish-e. It provides a way to gain access
to all headers without having to list them in your program.
<P><DT><STRONG>const char **SwishIndexNames( SW_HANDLE );</STRONG><DD>
<P>
Returns a list of index files opened. This is just the list of index files
specified in the <CODE>SwishInit()</CODE> call. You need the name of the
index file to access a specific index's header values.
<P><DT><STRONG>SWISH_HEADER_VALUE SwishHeaderValue( SW_HANDLE, const char *index_name, const char *cur_header, SWISH_HEADER_TYPE *type );</STRONG><DD>
<P>
Fetches the header value for the given index file, and the header name. The
call sets the "type" passed in to the type of value returned.
<P>
See src/libtest.c and perl/API.xs for examples.
<P><DT><STRONG>SWISH_HEADER_VALUE SwishResultIndexValue( SW_RESULT, const char *name, SWISH_HEADER_TYPE *type );</STRONG><DD>
<P>
This is like <CODE>SwishHeaderValue()</CODE> above, but instead of
supplying an index file name and a swish handle, supply a result object and
the header value is fetched from the result's related index file.
</DL>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H2><A NAME="Accessing_Property_Meta_Data">Accessing Property Meta Data</A></H2>
<P>
In addition to the pre-defined standard properties, you have the option of
adding additional "meta" properties to be indexed and/or added to
the list of properties returned with each result. Consult the sections on
the MetaNames and PropteryNames directives in the CONFIGURATION FILE for an
explanation of how to do this.
<P>
These functions provide access to the meta data stored in an index. You can
use them to determine what meta/property information is available for an
index including all the pre-defined standard properties. See libtest.c for
an example.
<DL>
<P><DT><STRONG><A NAME="item_SWISH_META_LIST">SWISH_META_LIST SwishMetaList( SW_HANDLE, const char *index_name );</A></STRONG><DD>
<P>
Returns the list of meta entries for the given index file as a
null-terminated array of SW_META objects. Use the functions below to
extract specific fields from the SW_META structure. Meta's are distinct
from properties.
<P><DT><STRONG>SWISH_META_LIST SwishPropertyList( SW_HANDLE, const char *index_name );</STRONG><DD>
<P>
This function is the same as <CODE>SwishMetaList()</CODE> but it returns an
array of properties as opposed to meta objects. Property attributes can be
extracted in the same was as meta objects using the functions below.
<P><DT><STRONG>SWISH_META_LIST SwishResultMetaList( SW_RESULT );</STRONG><DD>
<P>
This is like <CODE>SwishMetaList()</CODE> above but determines the index to
use from a result object.
<P><DT><STRONG>SWISH_META_LIST SwishResultPropertyList( SW_RESULT );</STRONG><DD>
<P>
This is like <CODE>SwishPropertyList()</CODE> above but like
<CODE>SwishResultMetaList()</CODE> uses a result object instead of an index
name.
<P><DT><STRONG>const char *SwishMetaName( SW_META );</STRONG><DD>
<P>
Given a SW_META object returned by one of the above, this function will
return the meta/property's name. You can use this name to access a
property's value for a given as described above.
<P><DT><STRONG>int SwishMetaType( SW_META );</STRONG><DD>
<P>
Get the data type for the given meta/property. Known types are listed in
swish-e.h
<P><DT><STRONG><A NAME="item_SwishMetaID">SwishMetaID( SW_META );</A></STRONG><DD>
<P>
Get the internal ID number for the given meta/property. These id's are
unique per index file but are not unique per results.
</DL>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H2><A NAME="Checking_for_Errors">Checking for Errors</A></H2>
<P>
You should check for errors after all calls. The last error is stored in
the swish handle object, and is only valid until the next operation (which
resets the error flags).
<P>
Currently, some errors are flagged as "critical" errors. In these
cases you should destroy (by calling the <CODE>SwishClose()</CODE> function
) the current swish handle. If you have other objects in scope (e.g. a
search object or results object) destroy those first.
<P>
The types of errors that are critical can be seen in src/error.c. Currently
the list includes:
<P>
<table>
<tr>
<td bgcolor="#eeeeee" width="1">
</td>
<td>
<pre> Could not open index file
Unknown index file format
Index file(s) is empty
Index file error
Invalid swish handle
Invalid results object</pre>
</td>
</tr>
</table>
<DL>
<P><DT><STRONG>int SwishError( SW_HANDLE );</STRONG><DD>
<P>
This returns true if an error condition exists. It returns the error
number, which is a integer less than zero on error. This should be checked
before calling any of the other error functions below.
<P><DT><STRONG>const char *SwishErrorString( SW_HANDLE );</STRONG><DD>
<P>
This returns a general text description of the current error.
<P><DT><STRONG>const char *SwishLastErrorMsg( SW_HANDLE );</STRONG><DD>
<P>
In some cases this will return a string with specifics about the current
error. For example, <CODE>SwishErrorString()</CODE> may return
"Unknown metaname", but <CODE>SwishLastErrorMsg()</CODE> will
return a string with the name of the unknown metaname.
<P><DT><STRONG>int SwishCriticalError( SW_HANDLE );</STRONG><DD>
<P>
Returns true if the current error condition is a critical error. On
critical errors you should free up any current objects and call
<CODE>SwishClose()</CODE> as swish may be in an unstable state.
<P><DT><STRONG>void SwishAbortLastError( SW_HANDLE );</STRONG><DD>
<P>
This is a convenience function that will format and print the last error
message, and then abort the program.
<P><DT><STRONG>void set_error_handle( FILE *where );</STRONG><DD>
<P>
Sets where errors and warnings are printed (when printed by swish). For
historical reasons, when swish-e first starts up errors and warnings are
sent to stdout.
<P><DT><STRONG>void SwishErrorsToStderr( void );</STRONG><DD>
<P>
A convenience method to send errors to stderr instead of stdout.
</DL>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H2><A NAME="Utility_Functions">Utility Functions</A></H2>
<DL>
<P><DT><STRONG>const char *SwishWordsByLetter(SWISH * sw, char *indexname, char c);</STRONG><DD>
<P>
Returns all the words in the index "indexname" that begin with
the letter passed in. Returns NULL if the name of the index file is
invalid.
<P>
This fuction may change in the future since only 8-bit chars can currently
be used.
<P><DT><STRONG><A NAME="item_char">char * SwsishStemWord( SW_HANDLE sw, char *in_word );</A></STRONG><DD>
<P>
Deprecated
<P>
This can be used to convert a word to its stem. It uses only the original
Porter Stemmer.
<P><DT><STRONG><A NAME="item_SW_FUZZYWORD">SW_FUZZYWORD SwishFuzzyWord( SW_RESULT r, char *word );</A></STRONG><DD>
<P>
Stems "word" based on the fuzzy mode selected during indexing.
<P>
The fuzzy mode used during indexing is stored in the index file. Since each
result is linked to a given index file this method allows stemming a word
based on it's index file.
<P>
One possible use for this is to highlight search terms in a document
summary, which would be based on a given result.
<P>
The methods below can be used to access the data returned. The SW_FUZZYWORD
object must be freed when done to avoid a memory leak.
<P><DT><STRONG>const char **SwishFuzzyWordList( SW_FUZZYWORD fw );</STRONG><DD>
<P>
Returns a null terminated list of strings returned by the stemmer. In most
cases this will be a single string.
<P>
Here's an example:
<P>
<table>
<tr>
<td bgcolor="#eeeeee" width="1">
</td>
<td>
<pre> SW_FYZZYWORD fuzzy_word = SwishFuzzyWord( result );
const char **word_list = SwishFuzzyWordList( fuzzy_word );
while ( *word_list )
{
printf("%s\n", *word_list );
word_list++;
}
SwishFuzzyWordFree( fuzzy_word );</pre>
</td>
</tr>
</table>
<P>
If the stemmer does not convert the string (for example attempting to stem
numeric data) the word_list will contain the original word. To tell if the
stemmer actually stemmed the word check the return value with
<CODE>SwishFuzzyWordError().</CODE>
<P><DT><STRONG>int SwishFuzzyWordError( SW_FUZZYWORD fw );</STRONG><DD>
<P>
This returns zero if the stemming operation was sucessfull, otherwise it
returns a value indicating the reason the word was not stemmed. The return
values are defined in the swish-e src/stemmer.h file.
<P>
Not all stemmers set this value correctly. But since
<CODE>SwishFuzzyWordList()</CODE> will return a valid string regardless of
the return value, you can often just ignore this setting. That's what I do.
<P><DT><STRONG>int SwishFuzzyWordCount( SW_FUZZYWORD fw );</STRONG><DD>
<P>
Returns the count of string in the word list available by calling
<CODE>SwishFuzzyWordList().</CODE>
<P>
This is normally just one, but in the case of DoubleMetaphone it can be one
or two (i.e. DoubleMetaphone can return one or two strings).
<P><DT><STRONG>const char *SwishFuzzyMode( SW_RESULT r );</STRONG><DD>
<P>
Returns the name of the stemmer used for the given result (which is related
to an index).
<P><DT><STRONG>void SwishFuzzyWordFree( SW_FUZZYWORD fw );</STRONG><DD>
<P>
Frees the memory used by the SW_FUZZYWORD.
</DL>
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H1><A NAME="Bug_Reports">Bug-Reports</A></H1>
<P>
Please report bug reports to the Swish-e discussion group. Feel also free
to improve or enhance this feature.
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H1><A NAME="Author">Author</A></H1>
<P>
Original interface: Aug 2000 Jose Ruiz <A
HREF="mailto:jmruiz@boe.es">jmruiz@boe.es</A>
<P>
Updated: Aug 22, 2002 - Bill Moseley
<P>
Interface redesigned for Swish-e version 2.3 Oct 17, 2002 - Bill Moseley
<P>
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<H1><A NAME="Document_Info">Document Info</A></H1>
<P>
$Id: SWISH-LIBRARY.pod,v 1.12 2004/05/01 01:24:17 whmoseley Exp $
<P>
.
[ <B><FONT SIZE=-1><A HREF="#toc">TOC</A></FONT></B> ]
<HR>
<p>
<div class="navbar">
<a href="./SWISH-3.0.html">Prev</a> |
<a href="./index.html">Contents</a> |
<a href="./API.html">Next</a>
</div>
<p>
<P ALIGN="CENTER">
<IMG ALT="" WIDTH="470" HEIGHT="10" SRC="images/dotrule1.gif"></P>
<P ALIGN="CENTER">
<div class="footer">
<BR>SWISH-E is distributed with <B>no warranty</B> under the terms of the
<A HREF="http://www.fsf.org/copyleft/gpl.html">GNU Public License</A>,<BR>
Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA<BR>
Public questions may be posted to
the <A HREF="http://swish-e.org/Discussion/">SWISH-E Discussion</A>.
</div>
</body>
</html>
|
