queue.h

Go to the documentation of this file.
00001 /*
00002  * SpanDSP - a series of DSP components for telephony
00003  *
00004  * queue.h - simple in process message queuing
00005  *
00006  * Written by Steve Underwood <steveu@coppice.org>
00007  *
00008  * Copyright (C) 2004 Steve Underwood
00009  *
00010  * All rights reserved.
00011  *
00012  * This program is free software; you can redistribute it and/or modify
00013  * it under the terms of the GNU General Public License as published by
00014  * the Free Software Foundation; either version 2 of the License, or
00015  * (at your option) any later version.
00016  *
00017  * This program is distributed in the hope that it will be useful,
00018  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00019  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00020  * GNU General Public License for more details.
00021  *
00022  * You should have received a copy of the GNU General Public License
00023  * along with this program; if not, write to the Free Software
00024  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
00025  *
00026  * $Id: queue.h,v 1.2 2005/11/23 17:09:47 steveu Exp $
00027  */
00028 
00029 /*! \file */
00030 
00031 /*! \page queue_page Queuing
00032 \section queue_page_sec_1 What does it do?
00033 ???.
00034 
00035 \section queue_page_sec_2 How does it work?
00036 ???.
00037 */
00038 
00039 #if !defined(_QUEUE_H_)
00040 #define _QUEUE_H_
00041 
00042 #define QUEUE_READ_ATOMIC   0x0001
00043 #define QUEUE_WRITE_ATOMIC  0x0002
00044 
00045 typedef struct
00046 {
00047     int len;
00048     int iptr;
00049     int optr;
00050     int flags;
00051     uint8_t *data;
00052 } queue_t;
00053 
00054 #ifdef __cplusplus
00055 extern "C" {
00056 #endif
00057 
00058 /*! Check if a queue is empty.
00059     \brief Check if a queue is empty.
00060     \param p The queue context.
00061     \return TRUE if empty, else FALSE. */
00062 int queue_empty(queue_t *p);
00063 
00064 /*! Check the available free space in a queue's buffer.
00065     \brief Check available free space.
00066     \param p The queue context.
00067     \return The number of bytes of free space. */
00068 int queue_free_space(queue_t *p);
00069 
00070 /*! Check the contents of a queue.
00071     \brief Check the contents of a queue.
00072     \param p The queue context.
00073     \return The number of bytes in the queue. */
00074 int queue_contents(queue_t *p);
00075 
00076 /*! Flush the contents of a queue.
00077     \brief Flush the contents of a queue.
00078     \param p The queue context. */
00079 void queue_flush(queue_t *p);
00080 
00081 /*! Copy bytes from a queue. This is similar to queue_read, but
00082     the data remains in the queue.
00083     \brief Copy bytes from a queue.
00084     \param p The queue context.
00085     \param buf The buffer into which the bytes will be read.
00086     \param len The length of the buffer.
00087     \return the number of bytes returned. */
00088 int queue_view(queue_t *p, uint8_t *buf, int len);
00089 
00090 /*! Read bytes from a queue.
00091     \brief Read bytes from a queue.
00092     \param p The queue context.
00093     \param buf The buffer into which the bytes will be read.
00094     \param len The length of the buffer.
00095     \return the number of bytes returned. */
00096 int queue_read(queue_t *p, uint8_t *buf, int len);
00097 
00098 /*! Write bytes to a queue.
00099     \brief Write bytes to a queue.
00100     \param p The queue context.
00101     \param buf The buffer containing the bytes to be written.
00102     \param len The length of the buffer.
00103     \return the number of bytes actually written. */
00104 int queue_write(queue_t *p, const uint8_t *buf, int len);
00105 
00106 /*! Test the length of the message at the head of a queue.
00107     \brief Test message length.
00108     \param p The queue context.
00109     \return The length of the next message, in byte. If there are
00110             no messages in the queue, -1 is returned. */
00111 int queue_test_msg(queue_t *p);
00112 
00113 /*! Read a message from a queue. If the message is longer than the buffer
00114     provided, only the first len bytes of the message will be returned. The
00115     remainder of the message will be discarded.
00116     \brief Read a message from a queue.
00117     \param p The queue context.
00118     \param buf The buffer into which the message will be read.
00119     \param len The length of the buffer.
00120     \return The number of bytes returned. If there are
00121             no messages in the queue, -1 is returned. */
00122 int queue_read_msg(queue_t *p, uint8_t *buf, int len);
00123 
00124 /*! Write a message to a queue.
00125     \brief Write a message to a queue.
00126     \param p The queue context.
00127     \param buf The buffer from which the message will be written.
00128     \param len The length of the message.
00129     \return The number of bytes actually written. */
00130 int queue_write_msg(queue_t *p, const uint8_t *buf, int len);
00131 
00132 /*! Create a queue.
00133     \brief Create a queue.
00134     \param p The queue context.
00135     \param len The length of the queue's buffer.
00136     \param flags Flags controlling the operation of the queue.
00137            Valid flags are QUEUE_READ_ATOMIC and QUEUE_WRITE_ATOMIC.
00138     \return 0 if created OK, else -1. */
00139 int queue_create(queue_t *p, int len, int flags);
00140 
00141 /*! Delete a queue.
00142     \brief Delete a queue.
00143     \param p The queue context.
00144     \return 0 if deleted OK, else -1. */
00145 int queue_delete(queue_t *p);
00146 
00147 #ifdef __cplusplus
00148 }
00149 #endif
00150 
00151 #endif
00152 /*- End of file ------------------------------------------------------------*/

Generated on Fri Nov 10 09:40:24 2006 for libspandsp by  doxygen 1.5.1