NAME

XrmQGetSearchList − return a list of database levels. 

Synopsis

Bool XrmQGetSearchList(database, names, classes,

list_return, list_length)
     XrmDatabase database;
     XrmClassList classes;
     XrmSearchList list_return;
     int list_length;

Arguments

databaseSpecifies the database to be searched. 

namesSpecifies a list of resource names. 

classesSpecifies a list of resource classes. 

list_return
Returns a search list for further use. The caller must allocate sufficient space for the list before calling XrmQGetSearchList(). 

list_length
Specifies the number of entries (not the byte size) allocated for list_return. 

Description

XrmQGetSearchList() is a tool for searching the database more efficiently.  It is used in combination with XrmQGetSearchResource().  Often, one searches the database for many similar resources which differ only in their final component (e.g., xmh.toc.foreground, xmh.toc.background, etc).  Rather than looking for each resource in its entirety, XrmGetSearchList searches the database for the common part of the resource name, returning a whole list of items in the database that match it.  This list is called the search list.  This search list is then used by XrmQGetSearchList(), which searches for the last components one at a time.   In this way, the common work of searching for similar resources is done only once, and the specific part of the search is done on the much shorter search list.  XrmQGetSearchList() takes a list of names and classes and returns a list of database levels where a match might occur.  The returned list is in best-to-worst order and uses the same algorithm as XrmGetResource() for determining precedence.  If list_return was large enough for the search list, XrmQGetSearchList() returns True.  Otherwise, it returns False.  The size of the search list that must be allocated by the caller is dependent upon the number of levels and wildcards in the resource specifiers that are stored in the database.  The worst case length is , where n is the number of name or class components in names or classes.  Only the common prefix of a resource name should be specified in the name and class list to XrmQGetSearchList().  In the example above, the common prefix would be xmh.toc.  However, note that XrmQGetSearchResource() requires that name represent a single component only.  Therefore, the common prefix must be all but the last component of the name and class.  For more information, see Volume One, Chapter 11, Managing User Preferences. 

Structures

XrmDatabase is a pointer to an opaque data type.
 
typedef XrmQuarkList XrmClassList;
typedef XrmQuark     XrmRepresentation;
 
XrmSearchList is a pointer to an opaque data type.

See Also

XrmDestroyDatabase(), XrmGetFileDatabase(), XrmGetResource(), XrmGetStringDatabase(), XrmInitialize(), XrmMergeDatabases(), XrmParseCommand(), XrmPutFileDatabase(), XrmPutLineResource(), XrmPutResource(), XrmPutStringResource(), XrmQGetResource(), XrmQGetSearchResource(), XrmQPutResource(), XrmQPutStringResource(), XrmQuarkToString(), XrmStringToBindingQuarkList(), XrmStringToQuarkList(), XrmStringToQuark(), XrmUniqueQuark(). 

Copyright O’Reilly & Assoc.  —