next up previous contents
Next: Pointer Manipulation Up: Functions Previous: Initialization

Status and State

NAME
    
DLL_Version, DLL_IsListEmpty, DLL_IsListFull,
DLL_GetNumberOfRecords, DLL_SetSearchModes,
DLL_GetSearchModes, DLL_GetCurrentIndex
-- Status and State Functions.

SYNOPSIS
#include <linklist.h>

char *DLL_Version(void);
DLL_Boolean DLL_IsListEmpty(List *list);
DLL_Boolean DLL_IsListFull(List *list);
unsigned long DLL_GetNumberOfRecords(List *list);
DLL_Return DLL_SetSearchModes(List *list, DLL_SrchOrigin origin,
            DLL_SrchDir dir);
DLL_SearchModes *DLL_GetSearchModes(List *list,
                 DLL_SearchModes *ssp);
unsigned long DLL_GetCurrentIndex(List *list);

DESCRIPTION
    
All the functions below except DLL_Version take as their first argument list the pointer returned by DLL_CreateList. These functions either return or set the status or state of some aspect of the link list.

DLL_Version
    
This function has no arguments and returns a string in the following format:
Ver: 1.1.0  May 17 1999
-------------------------------
 Developed by: Carl J. Nobile
Contributions: Charlie Buckheit
               Graham Inchley

DLL_IsListEmpty
    
This function determines if the link list has any nodes defined by testing if the head and tail pointers are NULL. It returns DLL_TRUE if the list is empty and DLL_FALSE if the list has valid nodes.

DLL_IsListFull
    
This function determines if there is enough memory to create new Node and Info structures by creating and then deleting them. It returns DLL_TRUE if either of the two structures could not be allocated and DLL_FALSE if the memory allocations were successful.

DLL_GetNumberOfRecords
    
This function returns the number of records currently in the link list by retrieving a counter value. It returns the number of nodes allocated where a return value of zero is an empty list.

DLL_SetSearchModes
    
This function sets the search mode state table which is used by various function in the API. Its second and third arguments are origin and dir. The origin argument can take one of four values:

DLL_HEAD
The origin of the search starts from the node which is at the head of the list. This is the default value if none have been set beforehand.
DLL_CURRENT
The origin of the search starts from the currently selected node.
DLL_TAIL
The origin of the search starts from the node which is at the tail of the list.
DLL_ORIGIN_DEFAULT
The origin of the search defaults to the last set value.

The dir argument can take one of three values:

DLL_DOWN
The direction of the search is from the head to the tail nodes. This is the default value if none have been set beforehand.
DLL_UP
The direction of the search is from the tail to the head nodes.
DLL_DIRECTION_DEFAULT
The direction of the search defaults to the last set value.

It returns DLL_NOT_MODIFIED if an invalid value was passed in either origin or dir. DLL_NORMAL is returned if the state table was set.

DLL_GetSearchModes
    
This function gets the state of the search criteria, which can either be the default values or those set by DLL_SetSearchModes. Its second argument is ssp, a pointer to the structure below. It returns a pointer to this same instance of the structure.

   typedef struct search_modes
      {
      DLL_SrchOrigin search_origin;
      DLL_SrchDir    search_dir;
      } DLL_SearchModes;

NOTE: This function has a different argument list starting with release linlkist-1.1.0. The original function allocated the structure internally to the function, which was not thread safe. This WILL break old code that used this function.

DLL_GetCurrentIndex
    
This function returns the index of the current record by retrieving a counter value. A return value of zero is an empty list.

EXAMPLE
    
Examples of most of these functions can be seen in the source file dll_test.c used in the testing of the link list API.


next up previous contents
Next: Pointer Manipulation Up: Functions Previous: Initialization
Carl John Nobile
1999-07-07