rvobjlist.h

基于h323协议的软phone

/***********************************************************************
Filename   : objlist.h
Description: objlist header file
************************************************************************
      Copyright (c) 2001,2002 RADVISION Inc. and RADVISION Ltd.
************************************************************************
NOTICE:
This document contains information that is confidential and proprietary
to RADVISION Inc. and RADVISION Ltd.. No part of this document may be
reproduced in any form whatsoever without written prior approval by
RADVISION Inc. or RADVISION Ltd..

RADVISION Inc. and RADVISION Ltd. reserve the right to revise this
publication and make changes without obligation to notify any person of
such revisions or changes.
***********************************************************************/
/*$
{package:
	{name: ObjList}
	{superpackage: CUtils}
	{include: rvobjlist.h}
	{description:	
		{p: This module provides functions for creating and manipulating
			structure lists.}
		{p:	To make a structure usable in a list, an element of type
			RvObjListElement must be declared in that structure.}
	}
}
$*/
#ifndef RV_OBJLIST_H
#define RV_OBJLIST_H

#include "rvtypes.h"

/*$
{type:
	{name: RvObjListElement}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:	
		{p: An element of this data type must be declared in the
			structure to be put into a list.}
		{p: The information stored in this element is only used while a
			particular object is actually in the list. The information
			stored in that element does not need to be maintained when
			the object is not in the list, even if it is to be returned
			to a list..}
		{p: A structure can be put into multiple lists by simply declaring
			multiple elements of this type in thrie structure.}
	}
	{notes:
		{note:  This module does no locking at all. The locking of the
				object list is the responsibility of the user.}
	}
}
$*/
typedef struct RvObjListElement_s RvObjListElement;
struct RvObjListElement_s {
	RvObjListElement *prev, *next;
	void *obj;
};

/*$
{type:
	{name: RvObjList}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:	
		{p: An object list object.}
	}
}
$*/
typedef struct {
	RvObjListElement anchor;
	RvSize_t count;
	RvPtrdiff_t offset;
} RvObjList;

/* Constants for indicating if items should be removed from the list. */
#define RV_OBJLIST_REMOVE RV_TRUE
#define RV_OBJLIST_LEAVE RV_FALSE

#if defined(__cplusplus)
extern "C" {
#endif 

/* Prototypes and macros: See documentation blocks below for details. */
RvObjList *RvObjListConstruct(RvObjList *objlist, void *itemtemp, RvObjListElement *elementptr);
RvSize_t RvObjListSize(RvObjList *objlist);
void *RvObjListInsertAfter(RvObjList *objlist, void *curitem, void *newitem);
void *RvObjListInsertBefore(RvObjList *objlist, void *curitem, void *newitem);
void *RvObjListGetNext(RvObjList *objlist, void *curitem, RvBool removeitem);
void *RvObjListGetPrevious(RvObjList *objlist, void *curitem, RvBool removeitem);
void *RvObjListRemoveItem(RvObjList *objlist, void *item);
#define RvObjListDestruct(_objlist) /* Doesn't need to do anything. */

#if defined(RV_TEST_CODE)
void RvObjListTest(void);
#endif /* RV_TEST_CODE */

#if defined(__cplusplus)
}
#endif 
/*$
{function:
	{name: RvObjListConstruct}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:
		{p: Constructs an object list.}
	}
	{proto: RvObjList RvObjListConstruct(RvObjList *objlist, void *itemtmp, RvObjListElement *elementptr);}
	{params:
		{param: {n: objlist} {d: Pointer to object list object to construct.}}
		{param: {n: itemtmp} {d: Pointer to an object of the type to be stored in the list.}}
		{param: {n: elementptr} {d: Pointer to the element within itemtmp to use for this list.}}
	}
	{returns: A pointer to the object list object or, if there is an error, NULL.}
	{notes:
		{note:  The itemtmp and elementptr pointers are simply used to find the offset
				within the structure where the RvObjListElement element is located.
				Anything the itemtmp pointer may point is is never touched.}
		{note:  For a more complicated structure, the RvObjListElement element can
				be placed outside the actual structure that will be in the list.
				It can even be before the structure itself, resulting in a negative
				offset. As long as the offset between the pointer passed in for an
				item and the location of the RvObjListElement data is constant, it
				will work.}
	}
}
$*/
/*$
{function:
	{name: RvObjListDestruct}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:
		{p: Destructs an object list.}
	}
	{proto: void RvObjListDestruct(RvObjList *_objlist);}
	{params:
		{param: {n: _objlist} {d: Pointer to object list object to be destructed.}}
	}
	{notes:
		{note:  Any items still in the list are left untouched.}
	}
}
$*/
/*$
{function:
	{name: RvObjListSize}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:
		{p: Get the current size of an object list.}
	}
	{proto: RvSize_t RvObjListSize(RvObjList *objlist);}
	{params:
		{param: {n: objlist} {d: Pointer to object list to get size of.}}
	}
	{returns: The size of the object list.}
}
$*/
/*$
{function:
	{name: RvObjListInsertAfter}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:
		{p: Inserts a new object into the list after a specified item.}
	}
	{proto: void *RvObjListInsertAfter(RvObjList *objlist, void *curitem, void *newitem);}
	{params:
		{param: {n: objlist} {d: Pointer to object list to insert new item into.}}
		{param: {n: curitem} {d: Pointer to item to insert new item after (NULL puts new item at beginning of list.}}
		{param: {n: newitem} {d: Pointer to new item to be inserted into the list.}}
	}
	{returns: A pointer to newitem or NULL if the item could not be inserted.}
	{notes:
		{note:  The curitem item must be in the list because that
				condition will not be detected and will cause major problems.}
	}
}
$*/
/*$
{function:
	{name: RvObjListInsertBefore}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:
		{p: Inserts a new object into the list before a specified item.}
	}
	{proto: void *RvObjListInsertBefore(RvObjList *objlist, void *curitem, void *newitem);}
	{params:
		{param: {n: objlist} {d: Pointer to object list to insert new item into.}}
		{param: {n: curitem} {d: Pointer to item to insert new item before (NULL puts new item at end of list.}}
		{param: {n: newitem} {d: Pointer to new item to be inserted into the list.}}
	}
	{returns: A pointer to newitem or NULL if the item could not be inserted.}
	{notes:
		{note:  The curitem item must be in the list because that
				condition will not be detected and will cause major problems.}
	}
}
$*/
/*$
{function:
	{name: RvObjListGetNext}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:
		{p: Gets the next item after a particular item in a list.}
	}
	{proto: void *RvObjListGetNext(RvObjList *objlist, void *curitem, RvBool removeitem);}
	{params:
		{param: {n: objlist} {d: Pointer to object list to get item from.}}
		{param: {n: curitem} {d: Pointer to item to get next item after (NULL gets the first item in the list.}}
		{param: {n: removeitem} {d: Set to RV_OBJLIST_REMOVE to remove the item from the list or set it
									to RV_OBJ_LIST_LEAVE to leave the item in the list.}}
	}
	{returns: A pointer to the next item or NULL if curitem was the last item in the list.}
	{notes:
		{note:  The curitem item must be in the list because that
				condition will not be detected and will cause major problems.}
	}
}
$*/
/*$
{function:
	{name: RvObjListGetPrevious}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:
		{p: Gets the previous item before a particular item in a list.}
	}
	{proto: void *RvObjListGetPrevious(RvObjList *objlist, void *curitem, RvBool removeitem);}
	{params:
		{param: {n: objlist} {d: Pointer to object list to previous item from.}}
		{param: {n: curitem} {d: Pointer to item to get previous item before (NULL gets the last item in the list.}}
		{param: {n: removeitem} {d: Set to RV_OBJLIST_REMOVE to remove the item from the list or set it
									to RV_OBJ_LIST_LEAVE to leave the item in the list.}}
	}
	{returns: A pointer to the previous item or NULL if curitem was the first item in the list.}
	{notes:
		{note:  The curitem item must be in the specified list because that
				condition will not be detected and will cause major problems.}
	}
}
$*/
/*$
{function:
	{name: RvObjListRemoveItem}
	{superpackage: ObjList}
	{include: rvobjlist.h}
	{description:
		{p: Removes an items from a list.}
	}
	{proto: void *RvObjListRemoveItem(RvObjList *objlist, void *item);}
	{params:
		{param: {n: objlist} {d: Pointer to object list to remove item from.}}
		{param: {n: item} {d: Pointer to item to remove from the list.}}
	}
	{returns: A pointer to the previous item that was removed or NULL if it could not be removed.}
	{notes:
		{note:  Do not remove an item from a list that it is not in because that
				condition will not be detected and will cause major problems.}
	}
}
$*/

#endif /* RV_OBJLIST_H */