enum NVQ_ReturnCode
{
NVQ_RC_CreateFailed = (1 | ModId_Nvq),
NVQ_RC_OpenFailed = (2 | ModId_Nvq),
NVQ_RC_WriteError = (3 | ModId_Nvq),
NVQ_RC_ReadError = (4 | ModId_Nvq),
NVQ_RC_Overflow = (5 | ModId_Nvq),
NVQ_RC_NonExistantElement = (6 | ModId_Nvq),
NVQ_RC_DataSizeTooLarge = (7 | ModId_Nvq),
};
typedef int NVQ_Element;
#define NVQ_NO_ELEMENTS ((NVQ_Element) -1)
ReturnCode
NVQ_create(char * pQueueName,
OS_Uint16 maxNumElements,
OS_Uint32 maxElementSize,
void ** phQueue);
Create a Non-Volatile Queue.
Parameters:
pQueueName --
Identifier, or name for this queue.
maxNumElements --
Maximum number of elements that may be on this queue (ever).
maxElementSize --
Maximum number of octets of data in any one element.
phQueue --
Pointer to a location in which a handle to this queue is placed, upon
successful completion of this function.
ReturnCode
NVQ_open(char * pQueueName,
OS_Uint16 * pMaxNumElements,
OS_Uint32 * pMaxElementSize,
void ** phQueue);
Open an already-existant Non-Volatile Queue.
Parameters:
pQueueName --
Identifier, or name for this queue.
pMaxNumElements --
Pointer to a location in which, upon successful completion of this
function, the maximum number of queue elements will be placed.
pMaxElementSize --
Pointer to a location in which, upon successful completion of this
function, the maximum number of octets in any element's data will be
placed.
phQueue --
Pointer to a location in which a handle to this queue is placed, upon
successful completion of this function.
void NVQ_close(void * hQueue);
Close a previously opened or created Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_create() or NVQ_open(), to the queue
to be closed.
ReturnCode NVQ_delete(charpQueueName);
Delete a Non-Volatile Queue.
Parameters:
pQueueName --
Identifier, or name of the queue to be deleted.
#define NVQ_VIEW_HEAD(hQueue, ppData, pDataSize) \
nvq_viewData(hQueue, ppData, pDataSize, NVQ_Location_Head)
Retrieve a pointer to the data in the element at the head of the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
ppData --
Pointer, of type unsigned char **, to a location in which to put a
pointer to the data.
pDataSize --
Pointer, of type OS_Uint32 *, to a location in which to put Number of
octets of data pointed to by *ppData.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
WARNING:
DO NOT MODIFY THE DATA POINTED TO BY THE RETURNED DATA POINTER!
#define NVQ_VIEW_TAIL(hQueue, ppData, pDataSize) \
nvq_viewData(hQueue, ppData, pDataSize, NVQ_Location_Tail)
Retrieve a pointer to the data in the element at the tail of the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
ppData --
Pointer, of type unsigned char **, to a location in which to put a
pointer to the data.
pDataSize --
Pointer, of type OS_Uint32 *, to a location in which to put Number of
octets of data pointed to by *ppData.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
WARNING:
DO NOT MODIFY THE DATA POINTED TO BY THE RETURNED DATA POINTER!
#define NVQ_VIEW_ELEM(hQueue, ppData, pDataSize, elem) \
nvq_viewData(hQueue, ppData, pDataSize, \
NVQ_Location_Element, (NVQ_Element) (elem))
Retrieve a pointer to the data in the element at the specified location in the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
ppData --
Pointer, of type unsigned char **, to a location in which to put a
pointer to the data.
pDataSize --
Pointer, of type OS_Uint32 *, to a location in which to put Number of
octets of data pointed to by *ppData.
elem --
Identifier, of type NVQ_Element, specifying for which element a pointer
to the data is to be returned.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
WARNING:
DO NOT MODIFY THE DATA POINTED TO BY THE RETURNED DATA POINTER!
#define NVQ_INSERT_AT_HEAD(hQueue, pData, dataSize) \
nvq_insert(hQueue, \
(unsigned char *) (pData), \
dataSize, \
NVQ_Location_Head)
Insert an element at the head of a Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
pData --
Pointer to the start of the data to be inserted in this queue element.
dataSize --
Number of octets of data pointed to by pData.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
#define NVQ_INSERT_AT_TAIL(hQueue, pData, dataSize) \
nvq_insert(hQueue, \
(unsigned char *) (pData), \
dataSize, \
NVQ_Location_Tail)
Insert an element at the tail of a Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
pData --
Pointer to the start of the data to be inserted in this queue element.
dataSize --
Number of octets of data pointed to by pData.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
#define NVQ_INSERT_BEFORE(hQueue, pData, dataSize, beforeMe) \
nvq_insert(hQueue, \
(unsigned char *) (pData), \
dataSize, \
NVQ_Location_Before, \
beforeMe)
Insert an element before the specified element of a Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
pData --
Pointer to the start of the data to be inserted in this queue element.
dataSize --
Number of octets of data pointed to by pData.
beforeMe --
Identifier, of type NVQ_Element, of the element before which this new
element should be inserted into the queue.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
#define NVQ_INSERT_AFTER(hQueue, pData, dataSize, afterMe) \
nvq_insert(hQueue, \
(unsigned char *) (pData), \
dataSize, \
NVQ_Location_After, \
afterMe)
Insert an element after the specified element of a Non-Volatile Queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
on which an element is to be inserted.
pData --
Pointer to the start of the data to be inserted in this queue element.
dataSize --
Number of octets of data pointed to by pData.
aftere --
Identifier, of type NVQ_Element, of the element after which this new
element should be inserted into the queue.
Returns:
Success upon success insertion; a non-success ReturnCode otherwise.
#define NVQ_REMOVE_HEAD(hQueue) \
nvq_remove(hQueue, NVQ_Location_Head)
Remove the element from the Non-Volatile Queue, which is at the queue's head.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
from which the element is to be removed.
Returns:
Success upon success removal; a non-success ReturnCode otherwise.
#define NVQ_REMOVE_TAIL(hQueue) \
nvq_remove(hQueue, NVQ_Location_Tail)
Remove the element from the Non-Volatile Queue, which is at the queue's tail.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
from which the element is to be removed.
Returns:
Success upon success removal; a non-success ReturnCode otherwise.
#define NVQ_REMOVE_ELEM(hQueue, elem) \
nvq_remove(hQueue, NVQ_Location_Element, (NVQ_Element) elem)
Remove a specified element from the Non-Volatile Queue
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
from which the element is to be removed.
elem --
Identifier, of type NVQ_Element, of the element which is to be removed
from the queue.
Returns:
Success upon success removal; a non-success ReturnCode otherwise.
#define NVQ_FIRST(hQueue) \
(nvq_getTail(hQueue) >= 0 ? 0 : NVQ_NO_ELEMENTS)
Obtain a handle to the first element of the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handle is desired.
Returns:
A handle, of type NVQ_Element, to the first element on the queue.
#define NVQ_LAST(hQueue) \
(nvq_getTail(hQueue))
Obtain a handle to the last element of the queue.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handle is desired.
Returns:
A handle, of type NVQ_Element, to the last element on the queue.
#define NVQ_NEXT(hQueue, elem) \
(++elem, elem > nvq_getTail(hQueue) ? \
NVQ_NO_ELEMENTS : elem)
Obtain a handle to the next element in the queue, given the current element.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handle is desired.
elem --
Identifier, of type NVQ_Element, of the element to which the successor
element is desired.
Returns:
A handle, of type NVQ_Element, to the next element in the queue.
#define NVQ_PREV(hQueue, elem) \
(--elem)
Obtain a handle to the previous element in the queue, given the current element.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handle is desired.
elem --
Identifier, of type NVQ_Element, of the element to which the
predecessor element is desired.
Returns:
A handle, of type NVQ_Element, to the previous element in the queue.
#define NVQ_EQUAL(hQueue, elem1, elem2) \
(elem1 == elem2)
Compare two NVQ_Element handles for equivilency.
Parameters:
hQueue --
Handle, previously returned by NVQ_open() or NVQ_create(), to the queue
for which the element handles are being compared
elem1, elem2 --
Identifiers, of type NVQ_Element, of the elements to be compared for
equality.
Returns:
TRUE if the identifiers reference the same queue element; FALSE
otherwise.
/*
* THE REMAINDER IS NOT PART OF THE USER INTERFACE. DO NOT REFERENCE THESE
* DIRECTLY IN USER PROGRAMS. OTHER PORTATIONS OF THIS MODULE MAY NOT CONTAIN
* THEM.
*/
typedef enum NVQ_Location
{
NVQ_Location_Head,
NVQ_Location_Tail,
NVQ_Location_Element,
NVQ_Location_Before,
NVQ_Location_After
} NVQ_Location;
ReturnCode
nvq_insert(void * hQueue,
unsigned char * pUserData,
OS_Uint32 userDataSize,
NVQ_Location location,
...);
ReturnCode
nvq_viewData(void * hQueue,
unsigned char ** ppData,
OS_Uint32 * pDataSize,
NVQ_Location location,
...);
ReturnCode
nvq_remove(void * hQueue,
NVQ_Location location,
...);
NVQ_Element
nvq_getTail(void * hQueue);