MyAPI



Table of Contents

Generated: Sat Sep 26 13:59:22 1998

Sections

MultiCast

MCSControl Class Initialize and do message dispatching for user applications.
MCSAddress Data Type A structure containing a transport protocol and an address.
MCSInitialize C++ Method This method is used to initialize a remote user application.

LinkList

List Module Generic linked list data type.
Ls_Pool Data Type Handle to a list memory pool.
Ls_List Data Type Handle to a list.
Ls_Gen Data Type Generator
Ls_Elem Data Type Handle to a list element.
Ls_Status Data Type Return codes
Ls_MakePool Function Create a list pool within a given memory pool.
Ls_Create... Function Create a new list
Ls_Destroy Function Destroy a list.
Ls_Copy... Function copy a list
Ls_FirstElem... Function get first/last item from a list
Ls_NewBegin... Function add a new item to the beginning/end of a list
Ls_DelBegin... Function Delete the first/last item of a list
Ls_Length Function get length of a list
Ls_Start... Function Create a list element generator
Ls_ElemGen Function create a list element generator near an element
Ls_Next... Function generate the next element in a sequence
Ls_InBefore... Function insert an item before/after the most recently generated
Ls_DelBefore... Function Delete an item relative to a generator.
Ls_Finish Function Release a generator.
Ls_Foreach... Function Iterate through a list.
Ls_ElemList Function Get list associated with element
Ls_ElemData Function Get user data of element.
Ls_SetElemData Function Set user data of element.
Ls_RemoveElem Function Remove an element from its list
Ls_Sort... Function Sort a list
Ls_Uniq... Function Remove duplicates from a sorted list
To Go Note functions that still need individual comments




MCSControl worktemp.c:2 Class

Names:

    MCSControl

Overview:

    Initialize and do message dispatching for user applications.

Prototype In:

    mds.h
    

Description:

    An MCSControl object furnishes initialization, message queuing, and message dispatching, for both repeater applications and user applications. The MCSControl object creates a message queue for its applications and dispatches messages to the application callback function, if one is specified.

See Also:




MCSAddress worktemp.c:20 Data Type

Names:

    MCSAddress

Overview:

    A structure containing a transport protocol and an address.

Syntax:

    typedef struct
    {
      unsigned short        transport_identifier;
        MCSTransportAddress   transport_address;
    } MCSAddress;
    

Defined In:

    mds.h
    

Description:

    The data type MCSAddress is a structure that is used to specify a transport stack protocol and a network address for a network repeater.

Fields:

    transport_identifier identifies the transport stack protocol. The valid values are:

    • MCS_TRANSPORT_TCP -transport control protocol, for both user and repeater communications
    • MCS_TRANSPORT_RMTP - reliable multicast transport protocol, for user communication
    • MCS_TRANSPORT_RMP - reliable multicast protocol, for repeater communication transport_address is a NULL terminated string specifying a network address in the form hostname:port.

See Also:

    MCSTransportAddress




MCSInitialize worktemp.c:54 C++ Method

Names:

    MCSInitialize

Overview:

    This method is used to initialize a remote user application.

Prototype:

    MCSError MCSInitialize
    (
        MCSVersion       mcs_version_requested,         // INPUT
        MCSVersion       *mcs_high_version,             // OUTPUT
        MCSVersion       *mcs_version,                  // OUTPUT
    );
    

Prototype In:

    mds.h
    

Description:

Parameters:

    mcs_version_requested - the version of the MDS API which the application requires mcs_high_version - a pointer to a structure containing the highest version of MDS which the repeater supports mcs_version - a pointer to a structure containing the version that will be used; the smaller of the mcs_version_requested and the mcs_high_version;

Return Value:

    • If successful, this method returns the value MCSERROR_NO_ERROR. A non-zero return indicates the specific failure condition.
    • MCSERROR_ADDRESS_IN_USE - Attempting to use an address that is already in use.
    • MCSERROR_ALLOCATION_FAILURE - The MDS system encountered a memory allocation failure while initializing the application.
    • MCSERROR_ALREADY_REGISTERED - The application has already been initialized by the MDS system.
    • MCSERROR_GLOBAL_MANAGER_NOT_RESPONDING - The global manager is not responding to requests.
    • MCSERROR_INVALID_PARAMETER - One of the parameters to the request is invalid.
    • MCSERROR_NO_ERROR - The function call was successful.
    • MCSERROR_NO_REPEATER_PROFILE - The repeater profile is not available.
    • MCSERROR_TRANSPORT_NOT_INITIALIZED - The transport process has not been initialized
    • MCSERROR_VERSION_NOT_SUPPORTED - The version of MDS requested is not supported.

Example:

    - REQUIRED - The following example shows the method code in use....

See Also:




List list.h:7 Module

Names:

    List

Overview:

    Generic linked list data type.

Prefix:

    LS

Description:

    This module implements a simple generic linked list data type. It uses a doubly linked list structure and provides some standard operations for storing and retrieving data from the list.

    The (client) data objects stored in a list are void* pointers.

Data Types:

Functions:

    List creation, deletion and copying:

    Accessing or manipulating elements at list ends:

    Generating and iterating:

    • Ls_Start - create generator before list head
    • Ls_End - create generator after list tail
    • Ls_ElemGen - create generator before/after given element
    • Ls_Next - generate next element
    • Ls_Prev - generate previous element
    • Ls_Foreach - apply a function to each element (first to last)
    • Ls_Backeach - apply a function to each element (last to first)

    Element membership, counting and locating:

    Miscellaneous:

    • Ls_PoolStats - print some statistics about a list pool

Remarks:

    This module is based on the List Management Package (a.k.a. lsList module) written by David Harrison of UC Berkeley.

See Also:

    <memory pool module>




Ls_Pool list.h:88 Data Type

Names:

    Ls_Pool

Overview:

    Handle to a list memory pool.

Syntax:

    typedef struct Ls_PoolDesc *Ls_Pool;
    

Defined In:

    list.h
    

Description:

Remarks:

    The Ls_Pool handle type is implemented as a pointer to a undefined structure type. This permits proper type checking without exposing its implementation details.

Example:

    Vm_MemId memoryPool;
    Ls_Pool listPool;
    Ls_List list1, list2;
    
    /*
     * make a memory pool and an associated list pool
     */
    memoryPool = Vm_GetMemPoolId( 4000, 24 );
    listPool = Ls_MakePool( memoryPool );
    
    list1 = Ls_CreateLP( listPool );  /* create an empty list */
    
    ... do some list operations ...
    
    list2 = Ls_Copy( list1, NULL );   /* copy it */
    
    ... more operations ...
    
    Vm_FreeMemPool( memoryPool );
    

See Also:

    List <memory manager overview> Vm_CreateMemPoolID Vm_FreeMemPool Vm_ReburbishMemPool Ls_MakePool <functions that take a Ls_Pool>




Ls_List list.h:164 Data Type

Names:

    Ls_List

Overview:

    Handle to a list.

Syntax:

    typedef struct Ls_ListDesc *Ls_List;
    

Defined In:

    list.h
    

Description:

Remarks:

    The Ls_List handle type is implemented as a pointer to a undefined structure type. This permits proper type checking without exposing its implementation details.

See Also:




Ls_Gen list.h:197 Data Type

Names:

    Ls_Gen

Overview:

    Generator

Syntax:

    typedef struct Ls_GenDesc *Ls_Gen;
    

Defined In:

    list.h
    

Description:

Remarks:

    The Ls_Gen handle type is implemented as a pointer to a undefined structure type. This permits proper type checking without exposing its implementation details.

See Also:




Ls_Elem list.h:239 Data Type

Names:

    Ls_Elem

Overview:

    Handle to a list element.

Syntax:

    typedef struct Ls_ElemDesc *Ls_Elem;
    

Defined In:

    list.h
    

Description:

    Routines which return items of a list optionally return a list element handle of type Ls_Elem. This handle can be stored in user data structures and later used to quickly access the item without searching through the list. If you do not wish to use handles, you can pass the zero handle, (Ls_Elem *)0, to the routine. For brevity, the LS_NH macro may be used to specify no handle to routines which return a handle.

Remarks:

    The Ls_Elem handle type is implemented as a pointer to a undefined structure type. This permits proper type checking without exposing its implementation details.

See Also:

    List, functions that return element handles




Ls_Status list.h:275 Data Type

Names:

    Ls_Status

Overview:

    Return codes

Syntax:

    typedef int Ls_Status;
    

Defined In:

    list.h
    

Description:

See Also:




Ls_MakePool list.h:342 Function

Names:

    Ls_MakePool

Overview:

    Create a list pool within a given memory pool.

Prototype:

    Ls_Pool Ls_MakePool( Vm_MemID memPool );
    

Prototype In:

    list.h
    

Description:

    Most list creation functions come in two flavors: one that uses memory internal to the list module, and one that uses memory within a user defined memory pool. If a memory pool is used, the list with allocate and release its memory within that pool. When the memory pool is freed or refurbished, all list storage associated with the pool (both in use and free) will become invalid.

    In order to use a memory pool, the list module needs to keep some internal state (free lists, statistics, etc.). The Ls_MakePool function initializes this state and returns a handle to it.

Remarks:

    It is possible to define more than one list pool within a given memory pool. In some cases this may be desirable from a software organization point of view. However, sharing list objects within the same pool leads to a more efficient use of resources.

Return Value:

Example:

    Vm_MemId memoryPool;
    Ls_Pool listPool;
    Ls_List list1, list2;
    
    /*
     * make a memory pool and an associated list pool
     */
    memoryPool = Vm_GetMemPoolId( 4000, 24 );
    listPool = Ls_MakePool( memoryPool );
    
    list1 = Ls_CreateLP( listPool );  /* create an empty list */
    
    ... do some list operations ...
    
    list2 = Ls_Copy( list1, NULL );   /* copy it */
    
    ... more operations ...
    
    Vm_FreeMemPool( memoryPool );
    

See Also:

    List <memory manager overview> Vm_CreateMemPoolID Vm_FreeMemPool Vm_ReburbishMemPool <functions that take a Ls_Pool>




Ls_Create list.h:413 Function

Names:

    Ls_Create
    Ls_CreateLP

Overview:

    Create a new list

Prototype:

    Ls_List Ls_Create( void );
    Ls_List Ls_CreateLP( Ls_Pool pool );
    

Prototype In:

    list.h
    

Description:

    Each of these functions creates a new list and returns it to the client. Ls_Create allocates memory internally while Ls_CreateLP allocates memory from a client supplied list pool.

Return Value:

    A newly created empty list.

See Also:




Ls_Destroy list.h:443 Function

Names:

    Ls_Destroy

Overview:

    Destroy a list.

Prototype:

    Ls_Destroy( Ls_List list, void (* delFunc)() );
    

Prototype In:

    list.h
    

Description:

    Ls_Destroy releases the resources associated with list. User data is released by calling delFunc on each of the elements with the user data as an argument. Accessing a list after its destruction is a no-no.

Return Value:

    none

See Also:




Ls_Copy list.h:475 Function

Names:

    Ls_Copy
    Ls_CopyLP

Overview:

    copy a list

Prototype:

    Ls_List Ls_Copy( Ls_List list, void *(*copyFunc)() );
    Ls_List Ls_CopyLP( Ls_Pool listPool, Ls_List list, void *(*copyFunc)());
    

Prototype In:

    list.h
    

Description:

    These functions return a copy of the specified list. Ls_Copy allocates the list using internal list module storage, while Ls_CopyLP uses a user-supplied memory pool.

    If `copyFunc' is defined (non-null), it will be called for each item in list and the pointer it returns will be used in place of the original user data for the item in the newly created list. The form of copyFunc should be:

    void *copyFunc( lsGeneric data );
    

    This is normally used to make copies of the user data in the new list. If no copyFunc is provided, an identity function is used.

Return Value:

    A copy of list.

See Also:




Ls_FirstElem list.h:517 Function

Names:

    Ls_FirstElem
    Ls_LastElem

Overview:

    get first/last item from a list

Prototype:

    Ls_Status Ls_FirstElem( Ls_List list, void *dataLoc, Ls_Elem *handleLoc );
    Ls_Status Ls_LastElem( Ls_List list, void *dataLoc, Ls_Elem *handleLoc );
    

Prototype In:

    list.h
    

Description:

    The functions Ls_FirstElem and Ls_LastElem return the first and last items, respectively, from a list. The item is stored in the location whose address is given by dataLoc. If handleLoc is non-zero, it will be filled with an item handle.

Return Value:

    • LS_OK - success
    • LS_NOMORE - list is empty

See Also:




Ls_NewBegin list.h:552 Function

Names:

    Ls_NewBegin
    Ls_NewEnd

Overview:

    add a new item to the beginning/end of a list

Prototype:

    void Ls_NewBegin( Ls_List list, void *data, Ls_Elem *handleLoc );
    void Ls_NewEnd( Ls_List list, void *data, Ls_Elem *handleLoc );
    

Prototype In:

    list.h
    

Description:

    The functions Ls_NewBegin and Ls_NewEnd add a new element containing data to the beginning or end of a list. If handleLoc is non-zero, it will be filled with an element handle.

Return Value:

    none

See Also:




Ls_DelBegin list.h:585 Function

Names:

    Ls_DelBegin
    Ls_DelEnd

Overview:

    Delete the first/last item of a list

Prototype:

    Ls_Status Ls_DelBegin( Ls_List list, void *dataLoc );
    Ls_Status Ls_DelEnd( Ls_List list, void *dataLoc );
    

Prototype In:

    list.h
    

Description:

    The functions Ls_DelBegin and Ls_DelEnd delete the first and last items, respectively, from a list. The deleted item is stored in the location whose address is given by dataLoc.

Return Value:

    • LS_OK - success
    • LS_NOMORE - list is empty

See Also:




Ls_Length list.h:618 Function

Names:

    Ls_Length

Overview:

    get length of a list

Prototype:

    int Ls_Length( Ls_List list );
    

Prototype In:

    list.h
    

Description:

    Return the number of items in the given list.

Return Value:

    length

See Also:




Ls_Start list.h:646 Function

Names:

    Ls_Start
    Ls_End

Overview:

    Create a list element generator

Prototype:

    Ls_Gen Ls_Start( Ls_list list );
    Ls_Gen Ls_End( Ls_list list );
    

Prototype In:

    list.h
    

Description:

    These functions create a generator that can be used to iterate through the elements of a list. Ls_Start generates from the beginning of the list, while Ls_End begins generation at the end of the list.

Return Value:

    A generator.

Example:

        /*
         * process each element of a Foo list from front to back
         */
    
        Foo *fooPtr;
        Ls_Gen gen;
    
        gen = Ls_Start( list );
        while( Ls_Next( gen, &fooPtr, LS_NH ) == LS_OK ) {
            ...
            /* do something exciting with fooPtr */
            ...
        }
        Ls_Finish( gen );
    

See Also:




Ls_ElemGen list.h:699 Function

Names:

    Ls_ElemGen

Overview:

    create a list element generator near an element

Prototype:

    Ls_Gen Ls_ElemGen( Ls_Elem elem, void *dataLoc, int pos );
    

Prototype In:

    list.h
    

Description:

    This function creates a generator positioned either before of after a given element in a list. The position is controlled by the pos paramter:

    • LS_BEFORE - before the element
    • LS_AFTER - after the element The elements user data will be placed at the address given by dataLoc.

Return Value:

    A generator.

Example:

    Ls_Elem  e;
    Ls_Gen   gen;
    Item    *item;
    
    e = ...   /* some element handle */
    
    /* process all items after element e */
    gen = Ls_ElemGen( e, NULL, LS_AFTER );
    while( lsNext( gen, &item, LS_NH ) == LS_OK ) {
        ProcessItem( item );
    }
    Ls_Finish( gen );
    

See Also:




Ls_Next list.h:747 Function

Names:

    Ls_Next
    Ls_Prev

Overview:

    generate the next element in a sequence

Prototype:

    Ls_Status Ls_Next( Ls_Gen gen, void *dataLoc, Ls_Elem *handleLoc );
    Ls_Status Ls_Prev( Ls_Gen gen, void *dataLoc, Ls_Elem *handleLoc );
    

Prototype In:

    list.h
    

Description:

    The functions Ls_Next and Ls_Prev generate the list element after or before the current generator location. The data from the generated element will be placed at dataLoc. If handleLoc is non-zero, it will be used to return a handle to the generated element.

Return Value:

    • LS_OK - successful
    • LS_NOMORE - no item generated (at end of list)

Example:

    /*
     * process each element of a Foo list from front to back
     */
    
    Foo *fooPtr;
    Ls_Gen gen;
    
    gen = Ls_Start( list );
    while( Ls_Next( gen, &fooPtr, LS_NH ) == LS_OK ) {
        ...
        /* do something exciting with fooPtr */
        ...
    }
    Ls_Finish( gen );
    

See Also:




Ls_InBefore list.h:800 Function

Names:

    Ls_InBefore
    Ls_InAfter

Overview:

    insert an item before/after the most recently generated

Prototype:

    void Ls_InBefore( Ls_Gen gen, void *data, Ls_Elem *handleLoc );
    void Ls_InAfter( Ls_Gen gen, void *data, Ls_Elem *handleLoc );
    

Prototype In:

    list.h
    

Description:

    The functions Ls_InBefore and Ls_InAfter insert a new element into a list before or after a specified generator.

Return Value:

    none

See Also:




Ls_DelBefore list.h:829 Function

Names:

    Ls_DelBefore
    Ls_DelAfter

Overview:

    Delete an item relative to a generator.

Prototype:

    Ls_Status Ls_DelBefore( Ls_Gen gen, void *dataLoc );
    Ls_Status Ls_DelAfter( Ls_Gen gen, void *dataLoc );
    

Prototype In:

    list.h
    

Description:

    The functions Ls_DelBefore and Ls_DelAfter delete the list element before or after a specified generator. If dataLoc is non-zero, it is used to return the data associated with the deleted item.

Return Value:

    • LS_OK - successful
    • LS_NOMORE - no item to delete

See Also:




Ls_Finish list.h:861 Function

Names:

    Ls_Finish

Overview:

    Release a generator.

Prototype:

    void Ls_Finish( Ls_Gen gen );
    

Prototype In:

    list.h
    

Description:

    Once a generator is no longer of use, pass it to Ls_Finish to release the resources associated with it.

See Also:




Ls_Foreach list.h:888 Function

Names:

    Ls_Foreach
    Ls_Backeach

Overview:

    Iterate through a list.

Prototype:

    Ls_Status Ls_Foreach( Ls_List list, Ls_Status (*userFunc)(), void *itrData );
    Ls_Status Ls_Backeach( Ls_List list, Ls_Status (*userFunc)(), void *itrData );
    

Prototype In:

    list.h
    

Description:

    These two functions iterate over the elements of a list, calling a user-specified function on each element. Ls_Foreach iterates from first to last, while Ls_Backeach iterates last to first.

    The function userFunc should have the following form:

    Ls_Status userFunc( void *data, void *itrData )
    

    where data is a data object stored at an element, and itrData is the data passed into the iterator. The user function is expected to return one of three values:

    • LS_OK - keep iterating
    • LS_STOP - stop iterating
    • LS_DELETE - delete current element and keep iterating

Return Value:

    • LS_OK - successfully iterated entire list
    • LS_STOP - iteration stopped prematurely by client function
    • LS_BADPARAM - unexpected return code from client function

See Also:




Ls_ElemList list.h:931 Function

Names:

    Ls_ElemList

Overview:

    Get list associated with element

Prototype:

    Ls_List Ls_ElemList( Ls_Elem elem );
    

Prototype In:

    list.h
    

Description:

    Given an element handle, this function returns the list that contains the element.

See Also:




Ls_ElemData list.h:954 Function

Names:

    Ls_ElemData

Overview:

    Get user data of element.

Prototype:

    void *Ls_ElemData( Ls_Elem elem );
    

Prototype In:

    list.h
    

Description:

    Ls_ElemData returns the user data stored at list element elem.

See Also:




Ls_SetElemData list.h:977 Function

Names:

    Ls_SetElemData

Overview:

    Set user data of element.

Prototype:

    void *Ls_SetElemData( Ls_Elem elem, void *newData );
    

Prototype In:

    list.h
    

Description:

    Ls_SetElemData sets the user data of elem to newData and returns the previously stored data.

See Also:




Ls_RemoveElem list.h:1001 Function

Names:

    Ls_RemoveElem

Overview:

    Remove an element from its list

Prototype:

    Ls_Status Ls_RemoveElem( Ls_Elem elem, void *dataLoc );
    

Prototype In:

    list.h
    

Description:

    Ls_RemoveElem removes the element elem from its list. If dataLoc is non-NULL, it is used to return the user data stored at elem.

See Also:




Ls_Sort list.h:1025 Function

Names:

    Ls_Sort
    Ls_SortCD

Overview:

    Sort a list

Prototype:

    void Ls_Sort( Ls_List list, int (*compare)() );
    void Ls_SortCD( Ls_List list, int (*compare)(), void *compData );
    

Prototype In:

    list.h
    

Description:

    These routines sort an input list, in place, according to a user-specified comparison function. The comparison function for Ls_Sort should be of the following form:

    int compare( void *item1, void *item2 );
    

    The routine should return -1, if item1 is less than item2, 0 if they are equal, and 1 if item1 is greater than item2.

    In addition to two items, the comparision function for Ls_SortCD gets an additional piece of user provided data. Its prototype should be:

    int compare( void *item1, void *item2, void *compData );
    

Remarks:

    These sorting routines use a generic merge sort written by Rick Rudell that runs in O(n log n) time.

See Also:




Ls_Uniq list.h:1065 Function

Names:

    Ls_Uniq
    Ls_UniqCD

Overview:

    Remove duplicates from a sorted list

Prototype:

    void Ls_Uniq( Ls_List list, int (*compare)(), void (*delFunc)());
    void Ls_UniqCD( Ls_List list, int (*compare)(), void (*delFunc)(), void *compData);
    

Prototype In:

    list.h
    

Description:

    These functions each take a sorted list and remove all duplicate elements. The comparison functions for Ls_Uniq and Ls_UniqCD have the following prototypes respectively.

    int compare( void *item1, void *item2 );
    int compare( void *item1, void *item2, void *compData );
    

    The routine should return -1, if item1 is less than item2, 0 if they are equal, and 1 if item1 is greater than item2.

    The function delFunc will be called with the user data of each duplicate element to be destroyed. If no clean up is required, delFunc can be NULL.

See Also:




To Go list.h:1102 Note

Names:

    To Go

Overview:

    functions that still need individual comments

Description:

    /*
     * return allocation stats
     */
    void Ls_ReportPoolStats( Ls_Pool pool )
    
    
    /* append source to target, copy items */
    void Ls_AppendCopy( Ls_List target, Ls_List source, void *(*copyFunc)())
    void Ls_PrependCopy( Ls_List target, Ls_List source, void *(*copyFunc)())
    
    /* append source to target, move items */
    void Ls_AppendMove( Ls_List target, Ls_List source )
    void Ls_PrependMove( Ls_List target, Ls_List source )
    
    
    /* concatenate two lists, copy items */
    Ls_List Ls_ConcatCopy( Ls_List list1, Ls_List list2, void *(*copyFunc)() )
    Ls_List Ls_ConcatCopyLP( Ls_Pool pool, Ls_List list1, Ls_List list2, void *(*copyFunc)() )
    
    /* concatenate two lists, move items */
    Ls_List Ls_ConcatMove( Ls_List list1, Ls_List list2 )
    
    
    /* filter specific items from list, copy items */
    Ls_List Ls_FilterCopy( Ls_List list, int (*compFunc)(), void *data,
          void *(*copyFunc)() )
    Ls_List Ls_FilterCopyLP( Ls_List list, int (*compFunc)(), void *data,
          void *(*copyFunc)() )
    
    /* filter specific items from list, move items */
    Ls_List Ls_FilterMove( Ls_List list, int (*compFunc)(), void *data )
    
    
    /* count specific members of a list */
    int Ls_CountMember( Ls_List list, void *object, int (*compFunc)() )
    int Ls_CountMemberCD( Ls_List list, void *object, int (*compFunc)(),
                   void *clientData)
    
    
    /* test list for specific item membership */
    int Ls_IsMember( Ls_List list, void *object, int (*compFunc)() )
    int Ls_IsMemberCD( Ls_List list, void *object, int (*compFunc)(),
                void *clientData )
    
    /* locate specific item in a list */
    Ls_Status Ls_LocateElem( Ls_List list, void *object, int (*compFunc)(),
                void *dataLoc, Ls_Elem *itemHandle)
    Ls_Status Ls_LocateElemCD( Ls_List list, void *object, int (*compFunc)(),
                  void *dataLoc, Ls_Elem *itemHandle,
                  void *clientData )
    
    
    /* delete specific items from a list */
    Ls_Status Ls_DeleteElem( Ls_List list, void *object, int (*compFunc)() )
    Ls_Status Ls_DeleteElemCD( Ls_List list, void *object, int (*compFunc)(),
                  void *clientData )
    
    
    /* get next/previous of specific item */
    Ls_Status Ls_NextElem( Ls_Elem item, void *dataLoc, Ls_Elem *nextLoc )
    Ls_Status Ls_PrevElem( Ls_Elem item, void *dataLoc, Ls_Elem *prevLoc )
    
    
    /* reverse a list in place */
    Ls_Status Ls_Reverse( Ls_List list )
    
    /* randomize list order in place */
    Ls_Status Ls_Scramble( Ls_List list )  /* uses default seed */
    Ls_Status Ls_ScrambleSeed( Ls_List list, long seed )