SOIF Structure

A SOIF 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. SOIF supports text and binary data, and attributes can have multiple values.

An example SOIF is the following:

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

A SOIF 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 SOIF object contains a collection of SOIFAVPair objects, which each contain an attribute and one or more values. To access attribute values in a SOIF, use SOIF_find() to retrieve the AVPair for the given attribute, or use SOIF_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 SOIF objects by using the SOIF_create() function. You can also read SOIF objects from a SOIF stream.

SOIF_Create

NSAPI_PUBLIC SOIF *SOIF_Create(char *schema_name, char *url)

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

SOIF_Free

NSAPI_PUBLIC void SOIF_Free(SOIF *)

Frees the given SOIF structure.

SOIF_GetTotalSize

NSAPI_PUBLIC int SOIF_GetTotalSize(SOIF *s)

Gets the estimated total size of the SOIF in bytes.

SOIF_GetAttributeCount

NSAPI_PUBLIC int SOIF_GetAttributeCount(SOIF *s)

Gets the number of attributes in the SOIF.

SOIF_GetAttributeSize

NSAPI_PUBLIC int SOIF_GetAttributeSize(SOIF *s)

Gets the size of the attributes only.

SOIF_GetValueSize

NSAPI_PUBLIC int SOIF_GetValueSize(SOIF *s)

Gets the size of the values only.

SOIF_GetValueCount

NSAPI_PUBLIC int SOIF_GetValueCount(SOIF *s)

Gets the number of values only.

SOIF_Merge

NSAPI_PUBLIC int SOIF_Merge(SOIF *dst, SOIF *src);

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

SOIF_Find

#define SOIF_Find(soif, attribute-name)

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

SOIFAVpair avp=SOIF_Find(s, "title");

SOIF_Findval

#define SOIF_Findval(soif, attribute-name)

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

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

SOIF_Remove

#define SOIF_Remove(soif, attribute-name)

Removes the given attribute from the given soif.

SOIF_Insert

#define SOIF_Insert(soif, attribute-name, value, value-size)

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

SOIF_InsertAVP

#define SOIF_InsertAVP(soif, avpair)

Inserts the given AVPair into the given soif.

SOIF_Apply

#define SOIF_Apply(soif, function, user-date)

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

void print_av(SOIF *s, SOIFAVPair *avp, void *unused) {printf("%s = %s\\n", avp->attribute, avp->value);} /* print every attribute and value in the soif s */ SOIF_Apply(s, print_av, NULL);