00001 /*************************************************************************** 00002 l1394_qarray.h - description 00003 ------------------- 00004 begin : Mon Jun 26 2000 00005 copyright : (C) 2000-2004 by Michael Repplinger 00006 email : repplix@studcs.uni-sb.de 00007 ***************************************************************************/ 00008 00009 /*************************************************************************** 00010 * * 00011 * This program is free software; you can redistribute it and/or modify * 00012 * it under the terms of the GNU General Public License as published by * 00013 * the Free Software Foundation; either version 2 of the License, or * 00014 * (at your option) any later version. * 00015 * * 00016 ***************************************************************************/ 00017 00018 #ifndef _L1394_QARRAY_H 00019 #define _L1394_QARRAY_H 00020 00021 #include <iostream> 00022 #include "l1394_quadlet.h" 00023 namespace L1394{ 00024 00025 00026 /*! \class QArray 00027 * \brief A QArray represents an dynamic array of Quadlets. 00028 * 00029 * Like Quadlets, QArrays are one of the basic data types in this library 00030 * to communicate with FireWire nodes. If you send more than 4 bytes 00031 * to a FireWire node you should use an QArray.<BR> 00032 * The QArray stores also information about the size of the array. It provides 00033 * most of the functionality like a Quadlet (without the compute operators). 00034 * 00035 * This class also provides functions to convert a QArray to an integer array 00036 * or a char array. 00037 * 00038 * @author Michael Repplinger 00039 */ 00040 00041 class QArray 00042 { 00043 00044 public: 00045 /** \name Constructors 00046 * These are the different constructors to create a QArray. 00047 */ 00048 00049 //@{ 00050 /*! \fn QArray(int size) 00051 * \brief Create a Qarray with a certain size. 00052 * \param size : Set the size of a QArray. 00053 */ 00054 QArray(int size); 00055 00056 00057 /*! \fn QArray(const QArray&) 00058 * \brief Copy constructor 00059 * \param qarray : reference to the QArray 00060 */ 00061 QArray(const QArray& qarray); 00062 00063 00064 /*! \fn ~QArray() 00065 * \brief Destructor 00066 */ 00067 ~QArray(); 00068 00069 //@} 00070 00071 /** \name Manipulate a QArray 00072 * These functions manipulate the values stored in a QArray. 00073 */ 00074 //@{ 00075 /*! \fn append(const QArray& qarray) 00076 * \brief This method appends an QArray to the end of a QArray. 00077 * \param qarray : array to append. 00078 */ 00079 void append(const QArray& qarray); 00080 00081 /*! \fn insert(const Quadlet value, unsigned int position) 00082 * \brief This method inserts a quadlet at a specific position in the array and 00083 * overwrites the old value. 00084 * 00085 * If you try to insert a value to an invalid position, the value will not be set. 00086 * \param value : Quadlet to insert 00087 * \param position : unsigned integer value for the position 00088 */ 00089 void insert(const Quadlet value, const unsigned int position); 00090 00091 00092 /*! \fn insert(const u_int32_t value, const unsigned int position) 00093 * \brief This method inserts am u_int32_t value at a specific position in the array and overwrites the old value. 00094 * 00095 * If you try to insert a value to an invalid position, the value will not be insert. 00096 * \param value : u_int32_t Integer to insert 00097 * \param position : unsigned integer value for the position. 00098 */ 00099 void insert(const u_int32_t value, const unsigned int position); 00100 00101 00102 /*! \fn getQuadlet(unsigned int i) const 00103 * \brief This method returns the i'th Quadlet in an array. 00104 * 00105 * Valid values are from 0 to length-1. If you try to get a Quadlet from position >= length, 00106 * a Quadlet with value 0 is returned 00107 * \param i : integer value for the position 00108 * \return Quadlet : the i'th Quadlet. If i>= size a empty Quadlet is returned 00109 */ 00110 Quadlet getQuadlet(const unsigned int i) const {if (i<size) return qarray[i]; return Quadlet();} 00111 00112 00113 /*! \fn getByte(const unsigned int i) const 00114 * \brief This method returns the i'th byte of the array. 00115 * 00116 * The range of i depends on the size of your QArray and is between 0<= i < size*4. 00117 * Byte 0 are the 8 most significant bits of the array 00118 * \return int : integer value of the i'th byte of the array. 00119 */ 00120 int getByte(const unsigned int i) const { return qarray[i/4].getByte(i%4);} 00121 00122 00123 /*! \fn setByte(const unsigned int i, const unsigned int value) 00124 * \brief This method sets byte i of the QArray to a specific value. 00125 * 00126 * The range of i depends on the size of your QArray and is between 0<= i < size*4. 00127 * \param i : unsigned integer for the position 00128 * \param value : unsigned integer for the value 00129 */ 00130 void setByte(const unsigned int i, const unsigned int value); 00131 //@} 00132 00133 /** \name Convert a QArray 00134 * These functions convert a QArray to another basic type. 00135 */ 00136 00137 //@{ 00138 /*! \fn toIntArray(u_int32_t*) const 00139 * \brief This method converts a QArray to an integer array (for compatibility use only) 00140 * 00141 * The integer array has the same size like the QArray. The programmer is responsible to delete this array. 00142 * \return u_int32_t* : pointer to the integer array. 00143 */ 00144 void toIntArray(u_int32_t* ) const; 00145 00146 00147 /*! \fn toCharArray(u_char*) const 00148 * \brief This method converts the value of a QArray to an u_char array. 00149 * 00150 * The size of the u_char array is size of the QArray * 4. Note, that the programmer 00151 * are responsible to delete this array. 00152 * \return u_char* : pointer to the u_char array. 00153 */ 00154 void toCharArray(u_char* ) const; 00155 00156 00157 /*! \fn getSize() const 00158 * \brief This method returns the size of a QArray. 00159 * \return int : the size of the QArray 00160 */ 00161 int getSize() const { return size;} 00162 //@} 00163 00164 00165 /*! \fn operator<<(ostream& output, const QArray& qarray) 00166 * \brief This method prints the QArray to ostream 00167 * \param output : reference to the output stream. 00168 * \param qarray : reference to the QArray. 00169 * \return ostream& : reference to the output ostream. 00170 */ 00171 friend ostream& operator<<(ostream& output, const QArray& array); 00172 00173 /** \name Some operators 00174 * 00175 */ 00176 //@{ 00177 00178 /*! \fn operator= (const QArray& qarray) 00179 * \brief This method sets the value of this QArray to the value of qarray. 00180 * 00181 * If this QArray is bigger than qarray, the last Quadlets are unchanged. 00182 * If this QArray is smaller, this QArray will be resized to the size of qarray. 00183 */ 00184 QArray& operator= (const QArray&); 00185 00186 00187 /*! \fn operator== (const QArray& qarray) 00188 * \brief This method compare two QArrays. 00189 * 00190 * Two QArrays with equal size are equal, if all their Quadlets are equal. Two 00191 * QArrays with different size are equal, if all Quadlets of the smaller QArray 00192 * are equal to the bigger one. 00193 * \return bool : return true if two QArrays are equal, false if not. 00194 */ 00195 bool operator== (const QArray&) ; 00196 00197 //@} 00198 private: 00199 00200 /*! \fn resize(const u_int factor) 00201 * \brief This method resizes the QArray 00202 */ 00203 void resize(const u_int factor); 00204 00205 unsigned int size, internal_size; 00206 Quadlet *qarray; 00207 00208 }; 00209 } 00210 #endif