Bristol Wearable Computing

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


The Attribute List API


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


/*
 *  The AttributeList ADT is used for storing lists of attributes with a note
 *  in the Note Server.
 *  Functions are provided for creating and destroying Attribute Lists and for
 *  adding and removing attributes from a list.
 *  Also, an AttributeList can be turned into an iterator using AList_Iterator,
 *  after which the attributes in the list can be accessed one at a time
 *  using AList_Next.
 */



#include "Attribute.h"



/* External type declarations. */

struct AList_Struct;
typedef  struct AList_Struct  AttributeList;

typedef  ALI_Struct  AListIterator;



/* External function prototypes. */


int AList_New(AttributeList **new);

/*
 *  Description:      This function creates a new (empty) attribute list and
 *                    returns a pointer to the newly allocated memory.
 *
 *  Pre-conditions:   None.
 *
 *  Post-conditions:  Memory is allocated for a new (empty) attribute list.
 *                    *new is set to point to this new attribute list.
 *
 *  Return values:     0    Success.
 *                    -3    Error: Out of memory.
 */



int AList_Add(AttributeList *alist, Attribute *attr);

/*
 *  Description:      This function adds a new attribute to an existing
 *                    attribute list.
 *
 *  Pre-conditions:   alist is a valid attribute list (created using AList_New
 *                    and not subsequently deallocated using AList_Destroy).
 *                    attr is a valid attribute.
 *
 *  Post-conditions:  `attr' is added to the end of `alist'.
 *
 *  Return values:     0    Success.
 *                    -1    Error: Either alist or attr is NULL.
 *                    -3    Error: Out of memory.
 */



int AList_Remove(AttributeList *alist, Attribute *attr);

/*
 *  Description:      This function can be used either to remove an exact known
 *                    attribute, `attr', or it can be used to remove one or
 *                    more attributes matching the pattern `attr' (if `attr'
 *                    contains wildcards - see below). The value returned by
 *                    this function is the number of attributes removed from
 *                    the list `alist'.
 *
 *  Wildcards:        Wildcards used in attributes are 0 for the noteid part,
 *                    and "*" for any of the string parts.
 *
 *  Pre-conditions:   alist is a valid attribute list and attr is a valid
 *                    attribute or attribute pattern (if it contains wildcards).
 *
 *  Post-conditions:  Any attributes in `alist' which match the pattern (or
 *                    exact attribute) `attr' are removed from the list and
 *                    the number of attributes removed is returned.
 *
 *  Return values:    >0    The number of attributes removed from alist.
 *                     0    No attributes matched the pattern given.
 *                    -1    Error: Either list or attr is NULL.
 */



int AList_Iterator(AttributeList *alist, AListIterator **aliter);

/*
 *  Description:      This function turns the given attribute list into an
 *                    iterator so that its elements can be accessed one at
 *                    a time by subsequent calls to AList_Next().
 *
 *  Pre-conditions:   alist is a valid attribute list.
 *
 *  Post-conditions:  Memory is allocated for a new AListIterator which
 *                    contains all the attributes in alist. *aliter is set
 *                    to point to this new iterator.
 *
 *  Return values:     0    Success.
 *                    -1    Error: alist is NULL.
 *                    -3    Error: Out of memory.
 */



int AList_Next(AListIterator **aliter, Attribute **attr);

/*
 *  Description:      After a call to AList_Iterator() to set up the iterator,
 *                    this function can be used repeatedly to get the attributes
 *                    in the list one at a time. Each call returns the next 
 *                    item in the list. 
 *
 *  Pre-conditions:   *aliter is a valid iterator (not NULL).
 *
 *  Post-conditions:  *attr is set to point to the next attribute in the
 *                    iterator. If there are no more items, then the pointer
 *                    will be set to null and the iterator itself will be
 *                    deallocated. It should not be used again.
 *
 *  Return values:     0    Success.
 *                     1    There are no more tokens. Do not use *aliter again.
 *                    -1    Error: *aliter is NULL.
 */



int AList_Destroy(AttributeList **alist);

/*
 *  Description:      This function frees up all the memory used by the given
 *                    attribute list, including the memory used by each
 *                    attribute within the list.
 *
 *  Pre-conditions:   *alist is not NULL.
 *
 *  Post-conditions:  All memory used by *alist and the attributes within it
 *                    is deallocated. *alist is set to NULL.
 *
 *  Return values:     0    Success.
 *                    -1    Error: *alist is 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.