Bristol Wearable Computing

[ Home | Plans | Meetings | Members | Search | Papers | Links | CyberWear | LocoSoft]


The Attribute API


/*
 *      Edward Beale
 *      Cyberjacket Project
 *      20/8/1998
 *
 *      Attribute.h
 */



/*
 *  The Attribute ADT hides the internal structure of an Attribute.
 *  Functions are provided for creating and destroying attributes, getting
 *  the various data parts of an attribute, and matching two attributes
 *  against one another.
 */



/* External type declarations. */

struct Attribute_Struct;
typedef  struct Attribute_Struct  Attribute;



/* External function prototypes. */


int Attribute_New(long noteid, const char *prefix, const char *action,
                 const char *expression, Attribute **new);

/*
 *  Description:      This function creates a new attribute from the given
 *                    noteid, prefix, action and expression. New memory is
 *                    allocated and filled and *new is set to point to it.
 *
 *  Pre-conditions:   prefix, action and expression are null-terminated strings.
 *
 *  Post-conditions:  Memory for a new Attribute is allocated and filled with
 *                    the given noteid, prefix, action and expression.
 *                    *new is set to point to this new attribute.
 *
 *  Return values:     0    Success.
 *                    -3    Error: Out of memory.
 */



int Attribute_GetNoteId(Attribute *attr, long *noteid);

/*
 *  Description:      This function gets the noteid part of the given attribute.
 *
 *  Pre-conditions:   attr is a valid attribute (created using New() and not
 *                    subsequently destroyed).
 *
 *  Post-conditions:  *noteid is set to the noteid part of attribute `attr'.
 *
 *  Return values:     0    Success.
 *                    -1    Error: attr is NULL.
 */



int Attribute_GetPrefix(Attribute *attr, char **prefix);

/*
 *  Description:      This function gets the prefix part of the given attribute.
 *                    No new memory is allocated - the pointer returned
 *                    points to the prefix of the attribute itself.
 *
 *  Pre-conditions:   attr is a valid attribute.
 *
 *  Post-conditions:  *prefix is set to point to the prefix of attribute `attr'
 *                    (not to a copy - no new memory is allocated).
 *
 *  Return values:     0    Success.
 *                    -1    Error: attr NULL.
 */



int Attribute_GetAction(Attribute *attr, char **action);

/*
 *  Description:      This function gets the action part of the given attribute.
 *                    No new memory is allocated.
 *
 *  Pre-conditions:   attr is a valid attribute.
 *
 *  Post-conditions:  *action is set to point to the action of attribute `attr'
 *                    (to the stored original, not a copy).
 *
 *  Return values:     0    Success.
 *                    -1    Error: attr NULL.
 */



int Attribute_GetExpression(Attribute *attr, char **expression);

/*
 *  Description:      This function gets the expression part of the given
 *                    attribute. The pointer returned points to the original
 *                    stored expression, rather than to a copy.
 *
 *  Pre-conditions:   attr is a valid attribute.
 *
 *  Post-conditions:  *expression is set to point to the expression part of
 *                    attribute `attr'.
 *
 *  Return values:     0    Success.
 *                    -1    Error: attr NULL.
 */



int Attribute_Match(const Attribute *attr1, const Attribute *attr2);

/*
 *  Description:      This function checks the two given attributes to see
 *                    whether they match, returning true (1) if they do or
 *                    false (0) if not. Either of the two given attributes
 *                    may contain wildcards (see below).
 *
 *  Matching:         Two attributes are said to match if each of the
 *                    constituent parts of the first is exactly equal to
 *                    the corresponding part of the second. The exception
 *                    to this is the wildcard. Any part of either attribute
 *                    can be replaced by a wildcard, which will match with
 *                    any value in the corresponding part of the other
 *                    attribute.
 *
 *  Wildcards:        The wildcard value for noteid is 0.
 *                    The wildcard value for prefix, action or expression is "*"
 *
 *  Pre-conditions:   attr1 and attr2 are both valid attributes.
 *
 *  Post-conditions:  attr1 and attr2 are tested for matching, including a
 *                    wildcard test. If they match, the return value is
 *                    true (1), otherwise false (0).
 *
 *  Return values:     1    True
 *                     0    False
 *                    -1    Error: One or both of the given attributes is NULL.
 */



int Attribute_Destroy(Attribute **attr);

/*
 *  Description:      This function frees up all the memory used by the given
 *                    attribute, including that used by the prefix, action and
 *                    expression strings. It sets the pointer to NULL so that
 *                    the memory cannot be accidently accessed after it has
 *                    been deallocated.
 *
 *  Pre-conditions:   *attr is a valid attribute.
 *
 *  Post-conditions:  All the memory used by *attr is deallocated. *attr is set
 *                    to NULL.
 *
 *  Return values:     0    Success.
 *                    -1    Error: *attr already NULL.
 */



unicrest.gif (4191 bytes)

The material displayed is provided 'as is' and is subject to use restrictions.
For problems or questions regarding this web contact Cliff Randell.
Last updated: January 14, 2000.
logoep.gif (1404 bytes)
ęCopyright Hewlett-Packard 1997-2000.