Search Structure

A Search has a schema-name and it associates a URL with a collection of attribute- value pairs. The schema-name identifies how to interpret the attribute-value pairs. Search supports text and binary data, and attributes can have multiple values.

Example for Search:

@DOCUMENT { http://www.siroe.com/
    title{17}:   Welcome to Siroe!
    author{13}:  Dot Punchcard
}

A Search object has URL and schema-name fields to store its URL and schema_name:

char *url;

/* The URL */

char *schema_name;

/* The Schema-Name, such as @document or @RDMHeader*/

A Search object contains a collection of SearchAVPair objects, which each contain an attribute and one or more values. To access attribute values in a Search, use Search_find() to retrieve the AVPair for the given attribute, or use Search_findval() to retrieve the value string for a given attribute. You must use all lowercase for attribute names for find*(), since only exact attribute name lookups are supported.

You can create Search objects by using the Search_create() function. You can also read Search objects from a Search stream.

Search_Create

NSAPI_PUBLIC Search *Search_Create
(char *schema_name, char *url)

Creates a Search structure with the given schema name and URL.

Search_Free

NSAPI_PUBLIC void Search_Free(Search *)

Frees the given Search structure.

Search_GetTotalSize

NSAPI_PUBLIC int Search_GetTotalSize(Search *s)

Gets the estimated total size of the Search in bytes.

Search_GetAttributeCount

NSAPI_PUBLIC int Search_GetAttributeCount(Search *s)

Gets the number of attributes in the Search.

Search_GetAttributeSize

NSAPI_PUBLIC int Search_GetAttributeSize(Search *s)

Gets the size of the attributes only.

Search_GetValueSize

NSAPI_PUBLIC int Search_GetValueSize(Search *s)

Gets the size of the values only.

Search_GetValueCount

NSAPI_PUBLIC int Search_GetValueCount(Search *s)

Gets the number of values only.

Search_Merge

NSAPI_PUBLIC int Search_Merge(Search *dst, Search *src);

Use this function to merge two Search objects (perform a Union of their attribute-values). It returns non-zero on error; otherwise, returns zero and the ”dst’ Search object contains all the attribute-value pairs from the ”src’ Search object.

If the ”dst’ object contains the same attribute as ”src’, then the attribute becomes a multi-valued attribute and all of the values are copied over to ”dst’. Only multi-valued attributes are copied over. For single-value attributes, discard the value in ”dst’. Currently only “classification” is a multi-valued attribute.

Search_Find

#define Search_Find(search, attribute-name)

Retrieves the AVPair for the given attribute in the given search. For example, the following statement gets the AVPair for the title attribute in the search s:

SearchAVpair avp=Search_Find(s, "title");

Search_Findval

#define Search_Findval(search, attribute-name)

Retrieves the value string for the given attribute in the given search. For example, the following statement prints the value of the title attribute of the search s:

printf("Title = %s\\n", Search_Findval(s, "title"));

Search_Remove

#define Search_Remove(search, attribute-name)

Removes the given attribute from the given search.

Search_Insert

#define Search_Insert(search, attribute-name,
value, value-size)

Inserts the given attribute and the value of the given size as an AVPair into the search.

Search_InsertAVP

#define Search_InsertAVP(search, avpair)

Inserts the given AVPair into the given search.

Search_Apply

#define Search_Apply(search, function, user-date)

Applies the given function with the given argument (user-data) to each AVPair in the given search. For example:

void print_av(Search *s, SearchAVPair *avp, void *unused) {printf("%s = %s\\n", avp->attribute, avp->value);} /* print every attribute and value in the search s */ Search_Apply(s, print_av, NULL);