data-id=acrobat-search-plug-in
Acrobat Search Plug-in
This chapter describes IAC support for the Acrobat Search plug-in, which allows users to perform text searches in PDF documents. It adds menus, menu items, toolbar buttons, and a Search panel to the Acrobat application. The Search plug-in exports a host function table (HFT) containing several methods that can be used by other Plugins.
Search supports interapplication communication in the form of DDE messages in Windows and Apple events in Mac OS. These messages and events allow remote clients to submit search queries and manipulate a list of indexes (the list of indexes is referred to as the shelf).
For more information, see the PDF Library documentation.
data-id=50532404_58297
data-id=search-plug-in-using-dde
Search plug-in using DDE
A client can connect to the Search plug-in with DDE using the service name "Acrobat Search" and the topic name "Acrobat Search".
DdeInitialize(&id, &DDE_ProcessMessage, APPCMD_CLIENTONLY, 0);
hszServerName = DdeCreateStringHandle(id, "Acrobat Search", 0);
hszTopicName = DdeCreateStringHandle(id, "Acrobat Search", 0);
hConv = DdeConnect(id, hszServerName, hszTopicName, NULL);
After a connection has been made, a single poke transaction will submit a search query. Two types of queries are supported: simple query and query.
data-id=simple-query-item
Simple query item
A simple query has the item name “SimpleQuery". When using a simple query, pass only a string that contains the query, using the ASQL query parser’s format (see QLangType_CQL in the table Query language type constants). It is not possible to choose another parser or to set word options using the simple query item.
data-id=query-item
Query item
A query has the item name “Query “. When using query, a QueryData structure is used. This structure contains the query, as well as specifying the query parser to use and additional options.
hszItemName = DdeCreateStringHandle(id, "Query", 0);
DdeClientTransaction(qd, nLen, hConv, hszItemName, CF_TEXT, XTYP_POKE,
1000, &dwResult);
DdeDisconnect(hConv)
The global data handle (qd) passed to the server must be in the following format:
typedef struct _QueryData {
eQLangType qlt;
boolean bOverrideWordOptions;
uns32 nWordOptions;
uns16 nMaxDocs;
uns16 nQueryOffset;
uns16 nNumSorts; //deprecated in Acrobat 6.0
uns16 nSortOffset[QP_MAX_SORT_FIELDS]; //deprecated in Acrobat 6.0
boolean bSortWays[QP_MAX_SORT_FIELDS]; //deprecated in Acrobat 6.0
unsigned char cData[1];
} QueryData;
data-id=query-options
Query options
OR of the values shown in Word option bit-flag constants.cData chunk. Each offset points to a NULL -terminated string containing the field name. This value has no effect in Acrobat 6.0 or later, because sort options are not valid.cData chunk that points to a NULL -terminated string containing the query to execute.0, the plug-in uses the current sort spec set by the user. This value has no effect in Acrobat 6.0 or later, because sort options are not valid.true indicates an ascending sort, and false indicates a descending sort. This value has no effect in Acrobat 6.0 or later, because sort options are not valid.data-id=50532404_97440
data-id=query-language-type-constants
Query language type constants
AND, OR, and NOT, as described in the Acrobat Search plug-in’s online help file.data-id=50532404_78200
data-id=word-option-bit-flag-constants
Word option bit-flag constants
AND operator to look for more than one word in a document. Without this option, AND terms can be anywhere in a document. Searching for “red” and “blue,” for example, finds a document where “red” is the first word on the first page and where “blue” is the last word on the last page. With this option, however, AND terms must be within two or three pages of each other to be found. Also, the closer AND terms appear together, the higher the relevance ranking of the document that contains them.To create and populate this structure correctly, the client must know the sum of the lengths of each sort field (sls), the length of the query (lq), and the size of the QueryData structure. The client then allocates memory as follows:
nSize = sizeof(QueryData) + sls + lq;
qd = (QueryData *)malloc(nSize);
For example, if the query was “Adobe” and the sort spec was “Title” ascending and “Score” descending then the structure would be packed as follows:
memset(qd, 0, nSize);
qd->nQueryOffset = 0;
strcpy(&cData[0], "Adobe");
qd->nNumSort = 2;
qd->nSortOffset[0] = strlen("Adobe") + 1;
qd->bSortWays[0] = TRUE;
strcpy(&cData[qd->nSortOffset[0]], "Title");
qd->bSortWays[1] = FALSE;
qd->nSortOffset[1] = qd->nSortOffset[0] + strlen("Title") + 1;
strcpy(&cData[qd->nSortOffset[1]], "Score");
data-id=manipulating-indexes-through-dde
Manipulating indexes through DDE
After a connection has been made, a single poke transaction can add, delete, add, or remove indexes. The item name to use is “Index".
hszItemName = DdeCreateStringHandle(id, "Index", 0);
DdeClientTransaction(qd, nLen, hConv, hszItemName, CF_TEXT, XTYP_POKE,
1000, &dwResult);
DdeDisconnect(hConv);
The global data handle (gd) passed to the server must be in the following format:
typedef struct _IndexData {
IndexActionType eAction;
int16 nIndexOffset;
int16 nTempNameOffset;
unsigned char cData[1];
} IndexData;
data-id=options
Options
cData chunk that points to a NULL -terminated string containing the PDX file representing the index.cData. It points to a temporary name that is displayed by the Search plug-in when the index is unavailable. This field must specify an offset either to an empty string (0) or to a non-empty C string.data-id=50532404_25513
data-id=index-operation-selectors
Index operation selectors
To create and populate this structure correctly, the client must know the sum of the lengths of the Index (li) and Temp names (lt) (including NULL -terminating characters), and the size of the IndexData structure.
The client then allocates memory as follows:
nSize = sizeof(IndexData) + li + lt;
id = (IndexData *)malloc(nSize);
For example, to add the index C:FOO.PDX to the Search plug-in’s shelf:
memset(id, 0, nSize);
id->eAction = IndexAction_Add;
id->nIndexOffset = 0;
strcpy(&id->cData[0], "C:FOO.PDX");
id->nTempNameOffset = strlen("C:FOO.PDX") + 1;
strcpy(&id->cData[id->nTempNameOffset],
"My Favorite Index");
data-id=50532404_72280
data-id=search-plug-in-using-apple-events
Search plug-in using Apple events
The Search plug-in supports the Apple events described in this section.
data-id=50532404_63056
data-id=searchaddindex
SearchAddIndex
Adds a specified index to the shelf.
Apple event ID
kSearchAddIndex ('addx')
Parameters
void* representing the shelf, obtained from SearchGetIndexList.MyDisk:TopFolder:BottomFolder:Strange.pdxkIndexAvailable flag should always be set.Returns
kIndexTag ('SixP'), typeLongInteger
An opaque void* representing an index. Returns NULL if failure.
Returns
#define kIndexExists ((SearchIndexPtr)-1)
if the index already exists in the index list. If the index already exists, you can retrieve it using SearchGetIndexByPath.
data-id=searchcountindexlist
SearchCountIndexList
Gets the number of indexes currently on the shelf.
Apple event ID
kSearchCountIndexList ('cidx')
Parameters
void* representing the shelf, obtained from SearchGetIndexList.Returns
kIndexListTag ('SilP'), typeLongInteger
Number of indexes on the shelf (kIndexListTag here is not semantically correct, but works).
data-id=searchdoquery
SearchDoQuery
Executes a specified query, using the set of indexes currently on the shelf. The search results are displayed in the Acrobat Search plug-in’s Results window.
Apple event ID
kSearchDoQuery ('kwry')
Parameters
NULL -terminated block of text. Its format is the same as what a user would type into the search Query window, and depends on the search language specified by kParserTag.kParserSimple 0: Allows only simple phrase searches; does not allow Boolean searching. kParserCQL 1: Allows Boolean searches using AND, OR, and NOT, as described in the Acrobat Search plug-in’s online help file. kParserBPlus 2: The Verity BooleanPlus query language. Contact Verity for further information on this language.Score (which sorts results by relevance ranking). Some common fields are Title, ModificationDate, CreationDate, and Keywords.kOptionsOverrideTag.OR'ed with the search options set in the user interface, or used instead of them. If 0, the word options are OR'ed with the user interface search options, and the resulting value is used. If non-zero, the word options are used instead of the user interface search options.maxDocs are displayed. maxDocs cannot be greater than 999.data-id=50532404_40152
data-id=word-options-for-apple-events
Word options for Apple events
AND operator to look for more than one word in a document. Without kWordOptionProximity, AND terms can be anywhere in a document. Searching for “red” and “blue,” for example, finds a document where “red” is the first word on the first page and where “blue” is the last word on the last page. With kWordOptionProximity, however, AND terms must be within two or three pages of each other to be found. Also, with kWordOptionProximity, the closer AND terms appear together, the higher the relevance ranking of the document that contains them.data-id=50532404_56157
data-id=searchgetindexbypath
SearchGetIndexByPath
Gets the index that has the specified path. The index must already be on the shelf. The index can be passed to other Search Apple events to remove it from the shelf, obtain its title, and so forth.
Apple event ID
kSearchGetIndexByPath ('fpdx')
Parameters
void* representing the shelf, obtained from SearchGetIndexList.MyDisk:TopFolder:BottomFolder:Strange.pdxReturns
kIndexTag ('SixP'), typeLongInteger
An opaque void* representing an index. Returns NULL if the specified index is gone.
data-id=50532404_73191
data-id=searchgetindexflags
SearchGetIndexFlags
Get the flags for an index.
Apple event ID
kSearchGetIndexFlags ('gfdx')
Parameters
void* representing an index.Returns
kFlagTag ('Flag'), typeLongInteger
A logical OR of the following:
kIndexAvailableFlag (1L << 0): Set if the index is available for searching.kIndexSelectedFlag (1L << 1): Set if the index appears with a check mark in the Search plug-in’s user interface.kIndexPtrInvalidFlag (1L << 31): Set if the index is not valid or is no longer valid.
data-id=50532404_64605
data-id=searchgetindexlist
SearchGetIndexList
Gets a list of the indexes currently on the shelf.
Apple event ID
kSearchGetIndexList ('gidx')
Returns
kIndexListTag ('SilP'), typeLongInteger
An opaque void* representing the list of indexes currently on the shelf. This value can subsequently be used by other search Apple events to obtain information about a specific index, the number of indexes on the shelf, and so forth.
data-id=searchgetindexpath
SearchGetIndexPath
Gets the full path to an index.
Apple event ID
kSearchGetIndexPath ('gpdx')
Parameters
void* representing the index whose path is to be obtained. The index may be obtained using SearchGetIndexByPath, SearchGetNthIndex, or SearchAddIndex.Returns
kPathTag ('Path'), typeChar
A NULL -terminated character string representing the full path of the index. Returns an empty string if the requested index is not valid.
data-id=searchgetindextitle
SearchGetIndexTitle
Gets the title of an index.
Apple event ID
kSearchGetIndexTitle ('gtdx')
Parameters
void* representing the index whose title is to be obtained. The index may be obtained using SearchGetIndexByPath, SearchGetNthIndex, or SearchAddIndex.Returns
kTitleTag ('Title'), typeChar
A NULL -terminated character string representing the title of the index. If there is no title, it returns the index’s path. Returns an empty string if the requested index is not valid.
data-id=50532404_62682
data-id=searchgetnthindex
SearchGetNthIndex
Gets the n th index on the shelf. The index can be passed to other Search Apple events to remove it from the shelf, obtain its title, and so forth.
Apple event ID
kSearchGetNthIndex ('fndx')
Parameters
void* representing the shelf, obtained from SearchGetIndexList.Returns
kIndexTag ('SixP'), typeLongInteger
An opaque void* representing an index. Returns NULL if the n th index is gone.
data-id=searchremoveindex
SearchRemoveIndex
Removes the specified index from the shelf.
Apple event ID
kSearchRemoveIndex ('rmdx')
Parameters
void* representing the shelf, obtained from SearchGetIndexList.void* representing the index to be removed. The index may be obtained using SearchGetIndexByPath, SearchGetNthIndex, or SearchAddIndex.data-id=searchsetindexflags
SearchSetIndexFlags
Sets the flags for an index.
Apple event ID
kSearchSetIndexFlags ('sfdx')
Parameters
void* representing an index.kIndexAvailableFlag should always be set.Returns
kFlagTag ('Flag'), typeLongInteger
Index flags. See the description in SearchGetIndexFlags. This value is returned because it is possible for a request to set a flag to fail.
data-id=50532404_69263
data-id=search-lists
Search lists
The Search plug-in adds a new menu, menu items, and toolbar buttons to the Acrobat application.
data-id=50532404_32193
Menu names
The Search plug-in adds the following menu to Acrobat.
data-id=menu-item-names
Menu item names
The Search plug-in adds the following menu items to Acrobat.
data-id=toolbar-button-names
Toolbar button names
The Search plug-in adds the following buttons to the Acrobat toolbar.