Bristol Wearable Computing

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


The Note Server Direct API


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

/*
 *  This is the Note Server direct API. It provides functions to create and
 *  destroy note servers, add and remove notes from a note server and to add
 *  and remove attributes from a note.
 *  In addition, there are two search functions which which can do specific and
 *  wildcard searches for certain note attributes or combinations. These return
 *  the ids of matching notes. Finally, there are two functions which
 *  respectively return the note contents filename and the list of note
 *  attributes (given the id of a note).
 */



#include "Attribute.h"
#include "AttributeList.h"



/* External type declarations. */

struct NS_Struct;
typedef  struct NS_Struct  NoteServer;



/* External function prototypes. */


int  NS_New(NoteServer **new);

/*
 *  Description:      This function allocates memory for a new Note Server.
 *                    This new Note Server does not contain any notes, but
 *                    these can be added using NS_AddNote().
 *
 *  Pre-conditions:   None.
 *
 *  Post-conditions:  Memory is allocated for a new note server containing
 *                    no notes. *new is set to point to this memory.
 *
 *  Return values:     0    Success.
 *                    -3    Error: Out of memory.
 */



int  NS_Load(const char *nsfile, NoteServer **ns);

/*
 *  Description:      This function loads in a complete note server database
 *                    from a file (created using NS_Save). Any notes whose
 *                    content files have been moved or deleted since the save
 *                    will not be added to the new database.
 *
 *  Pre-conditions:   `nsfile' is a note server save file.
 *
 *  Post-conditions:  New memory is allocated and a new note server built up
 *                    from the information in `nsfile'. *ns is set to point to
 *                    this new memory.
 *
 *  Return values:     0    Success.
 *                    -2    Error: Incorrect filetype.
 *                    -3    Error: Out of memory.
 */



int  NS_Save(NoteServer *ns, const char *nsfile);

/*
 *  Description:      This function creates a note server save file called
 *                    `nsfile' which contains the entire contents of the given
 *                    note server (ns). The note server which exists at this
 *                    moment can then be recreated by calling NS_Load() with
 *                    the name of the save file.
 *
 *  Pre-conditions:   ns is a valid note server.
 *
 *  Post-conditions:  A note server save file is created called `nsfile'
 *                    (any existing file called `nsfile' will be overwritten)
 *                    which contains the entire state of the note server `ns'
 *                    at this moment in time.
 *
 *  Return values:     0    Success.
 *                    -1    Error: ns is NULL.
 *                    -2    Error: File handling failed.
 */



long NS_AddNote(NoteServer *ns, const char *filename);

/*
 *  Description:      This function adds a new note to the Note Server. The
 *                    contents of this note are in the file `filename' (this
 *                    can be any type of file). The new note is given a
 *                    unique identifier, which is the long value returned.
 *                    This can then be used to add attributes to the note
 *                    (after this call, the note has no attributes).
 *
 *  Pre-conditions:   ns is a valid Note Server (not NULL). 
 *
 *  Post-conditions:  A new note is added to the note server with content in
 *                    the file `filename'. A unique id is given to the new note
 *                    and this is returned.
 *
 *  Return values:    >0    Unique id for the note.
 *                    -1    Error: ns is NULL.
 *                    -3    Error: Out of memory.
 */



int  NS_RemoveNote(NoteServer *ns, long id);

/*
 *  Description:      This function removes the note whose id number is given
 *                    from the Note Server. The note content file is also
 *                    deleted (unlinked).
 *
 *  Pre-conditions:   `ns' is a valid Note Server. `id' is the identifier
 *                    of an existing note in the Note Server.
 *
 *  Post-conditions:  The note with identifier `id' is removed from the Note
 *                    Server and its content file is deleted.
 *
 *  Return values:     0    Success.
 *                    -1    Error: ns is NULL.
 */



int  NS_AddAttribute(NoteServer *ns, Attribute *fixed);

/*
 *  Description:      This function adds the given attribute to the note
 *                    identified by the `id' part of the attribute itself.
 *                    Typically, this will be used after NS_AddNote() - which
 *                    creates a new note with no attributes.
 *
 *  Pre-conditions:   `ns' is a valid Note Server. `fixed' is an attribute
 *                    containing no wildcards whose `id' part is the identifier
 *                    of an existing note in the Note Server.
 *
 *  Post-conditions:  The given attribute is added to the end of the attribute
 *                    list of the appropriate note.
 *
 *  Return values:     0    Success.
 *                    -1    Error: ns NULL.
 *                    -2    Error: note id unknown in note server.
 *                    -3    Error: Out of memory.
 */



int  NS_RemoveAttribute(NoteServer *ns, Attribute *wild);

/*
 *  Description:      This function removes one or more attributes from a
 *                    specified note. The note is given by the id part of
 *                    `wild'. The other parts of `wild' can be definite values
 *                    to match or alternatively the wildcard `*'. Any
 *                    attributes of the note which match this pattern will
 *                    be removed and the number removed is returned.
 *
 *  Pre-conditions:   `ns' is a valid note server. `wild' has a fixed id which
 *                    is the identifier of the note from which to remove
 *                    attributes.
 *
 *  Post-conditions:  All matching attributes of the note are removed.
 *                    On success, the number of attributes removed is returned.
 *
 *  Return values:    >0    The number of attributes removed.
 *                     0    No matching attributes were found.
 *                    -1    Error: ns NULL.
 *                    -2    Error: note id unknown in note server.
 */



int  NS_GetFile(NoteServer *ns, long id, char **filename);

/*
 *  Description:      This function gets the filename of the note identified
 *                    by `id'. New memory is not allocated for the filename.
 *
 *  Pre-conditions:   `ns' is a valid note server and `id' identifies a note
 *                    within it.
 *
 *  Post-conditions:  *filename points to the filename string for the given
 *                    note. No new memory is allocated.
 *
 *  Return values:     0    Success.
 *                    -1    Error: ns is NULL.
 *                    -2    Error: note id unknown in note server.
 */



int  NS_GetAttributes(NoteServer *ns, long id, AttributeList **attrs);

/*
 *  Description:      This function gets the attribute list of the note
 *                    identified by `id'. *attrs is set to point to the
 *                    existing attribute list, not a copy (no new memory
 *                    is allocated).
 *
 *  Pre-conditions:   `ns' is a valid note server and `id' identifies a note
 *                    within it.
 *
 *  Post-conditions:  *attrs points to the attribute list for the given note.
 *                    No new memory is allocated.
 *
 *  Return values:     0    Success.
 *                    -1    Error: ns is NULL.
 *                    -2    Error: note id unknown in note server.
 */



int  NS_Search(NoteServer *ns, Attribute *wilduser, const char *sensed,
       long **idlist);

/*
 *  Description:      This function searches all the notes in the given Note
 *                    Server, returning the identifiers of any which match
 *                    the search parameters.
 *
 *  Pre-conditions:
 *
 *  Post-conditions:
 *
 *  Return values:
 */

/* Number of ids in list is returned. Expression in attribute is the user
   context, outside is the sensed context (domains only). */       



int  NS_SearchAttribute(NoteServer *ns, Attribute *wilduser,
       const char *sensed, AttributeList **alist);

/*
 *  Description:
 *
 *  Pre-conditions:
 *
 *  Post-conditions:
 *
 *  Return values:
 */

/* Number of attributes is returned. Each attribute contains its note id. */



int  NS_Destroy(NoteServer **ns);

/*
 *  Description:      This function destroys the given Note Server and all the
 *                    notes that it contains. Specifically, it deallocates all
 *                    memory used to store the note attributes and the note
 *                    server itself, and it deletes all the note content files.
 *
 *  Pre-conditions:   *ns points to an existing Note Server (created with
 *                    NS_New() and not subsequently destroyed).
 *
 *  Post-conditions:  All the memory which has been allocated to the note
 *                    server and its notes is deallocated. The note content
 *                    files for all the stored notes are removed (unlinked).
 *                    The pointer (*ns) is set to NULL.
 *
 *  Return values:     0    Success.
 *                    -1    Error: *ns 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.