00001 /*******************************************************************************
00002 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
00003 released in source code form as part of the SDK installer package.
00004 
00005 Commercial License Usage
00006 
00007 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
00008 may use this file in accordance with the end user license agreement provided 
00009 with the software or, alternatively, in accordance with the terms contained in a
00010 written agreement between you and Audiokinetic Inc.
00011 
00012 Apache License Usage
00013 
00014 Alternatively, this file may be used under the Apache License, Version 2.0 (the 
00015 "Apache License"); you may not use this file except in compliance with the 
00016 Apache License. You may obtain a copy of the Apache License at 
00017 http://www.apache.org/licenses/LICENSE-2.0.
00018 
00019 Unless required by applicable law or agreed to in writing, software distributed
00020 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
00021 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
00022 the specific language governing permissions and limitations under the License.
00023 
00024   Version: <VERSION>  Build: <BUILDNUMBER>
00025   Copyright (c) <COPYRIGHTYEAR> Audiokinetic Inc.
00026 *******************************************************************************/
00027 
00028 /// \file
00029 /// AK::IReadBytes, AK::IWriteBytes simple serialization interfaces.
00030 
00031 #ifndef _AK_IBYTES_H
00032 #define _AK_IBYTES_H
00033 
00034 #include <wchar.h>
00035 #include <AK/Tools/Common/AkPlatformFuncs.h> 
00036 
00037 namespace AK
00038 {
00039     /// Generic binary input interface.
00040     /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
00041     class IReadBytes
00042     {
00043     public:
00044         ////////////////////////////////////////////////////////////////////////
00045         /// @name Interface
00046         //@{
00047 
00048         /// Reads some bytes into a buffer.
00049         /// \return True if the operation was successful, False otherwise
00050         virtual bool ReadBytes( 
00051             void * in_pData,        ///< Pointer to a buffer
00052             AkInt32 in_cBytes,          ///< Size of the buffer (in bytes)
00053             AkInt32 & out_cRead         ///< Returned number of read bytes
00054             ) = 0;
00055 
00056         //@}
00057 
00058         ////////////////////////////////////////////////////////////////////////
00059         /// @name Helpers
00060         //@{
00061 
00062         /// Reads a simple type or structure.
00063         /// \warning Not for object serialization.
00064         /// \return True if the operation was successful, False otherwise.
00065         template<class T>
00066         bool Read( 
00067             T & out_data )  ///< Data to be read
00068         {
00069             AkInt32 cRead;
00070             return ReadBytes( &out_data, sizeof( T ), cRead );
00071         }
00072 
00073         /// Reads a simple type or structure.
00074         /// \warning This method does not allow for error checking. Use other methods when error cases need to be handled.
00075         /// \warning Not for object serialization.
00076         /// \return Read data
00077         template<class T>
00078         T Read()
00079         {
00080             T value;
00081 
00082             AkInt32 cRead;
00083             ReadBytes( &value, sizeof( T ), cRead );
00084 
00085             return value;
00086         }
00087 
00088         /// Reads a unicode string into a fixed-size buffer. 
00089         /// \return True if the operation was successful, False otherwise. An insufficient buffer size does not cause failure.
00090         bool ReadString( 
00091             wchar_t * out_pszString,    ///< Pointer to a fixed-size buffer
00092             AkInt32 in_nMax )           ///< Maximum number of characters to be read in out_pszString, including the terminating NULL character
00093         {
00094             AkInt32 cChars;
00095             if ( !Read<AkInt32>( cChars ) ) 
00096                 return false;
00097 
00098             bool bRet = true;
00099 
00100             if ( cChars > 0 )
00101             {
00102                 AkInt32 cRead;
00103 
00104                 if ( cChars < in_nMax )
00105                 {
00106                     ReadBytes( out_pszString, cChars * sizeof( wchar_t ), cRead );
00107                     out_pszString[ cChars ] = 0;
00108 
00109                     bRet = cRead == (AkInt32)( cChars * sizeof( wchar_t ) );
00110                 }
00111                 else
00112                 {
00113                     ReadBytes( out_pszString, in_nMax * sizeof( wchar_t ), cRead );
00114                     out_pszString[ in_nMax - 1 ] = 0;
00115 
00116                     bRet = cRead == (AkInt32)( in_nMax * sizeof(wchar_t));
00117 
00118                     if ( bRet )
00119                     {
00120                         // Read extra characters in temp buffer.
00121                         AkInt32 cRemaining = cChars - in_nMax;
00122 
00123                         wchar_t * pTemp = new wchar_t[ cRemaining ];
00124 
00125                         ReadBytes( pTemp, cRemaining * sizeof( wchar_t ), cRead );
00126 
00127                         bRet = cRead == (AkInt32)(cRemaining * sizeof(wchar_t));
00128 
00129                         delete [] pTemp;
00130                     }
00131                 }
00132             }
00133             else
00134             {
00135                 out_pszString[ 0 ] = 0;
00136             }
00137 
00138             return bRet;
00139         }
00140         //@}
00141     };
00142 
00143     /// Generic binary output interface.
00144     /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
00145     class IWriteBytes
00146     {
00147     public:
00148         ////////////////////////////////////////////////////////////////////////
00149         /// @name Interface
00150         //@{
00151 
00152         /// Writes some bytes from a buffer.
00153         /// \return True if the operation was successful, False otherwise
00154         virtual bool WriteBytes( 
00155             const void * in_pData,  ///< Pointer to a buffer
00156             AkInt32 in_cBytes,      ///< Size of the buffer (in bytes)
00157             AkInt32 & out_cWritten      ///< Returned number of written bytes
00158             ) = 0;
00159 
00160         //@}
00161 
00162         ////////////////////////////////////////////////////////////////////////
00163         /// @name Helpers
00164         //@{
00165 
00166         /// Writes a simple type or struct.
00167         /// \warning Not for object serialization.
00168         /// \return True if the operation was successful, False otherwise
00169         template<class T>
00170         bool Write( 
00171             const T & in_data )     ///< Data to be written
00172         {
00173             AkInt32 cWritten;
00174             return WriteBytes( &in_data, sizeof( T ), cWritten );
00175         }
00176 
00177         /// Writes a unicode string. 
00178         /// \return True if the operation was successful, False otherwise
00179         bool WriteString( 
00180             const wchar_t * in_pszString )  ///< String to be written
00181         {
00182             if ( in_pszString != NULL )
00183             {
00184                 size_t cChars = wcslen( in_pszString );
00185                 if ( !Write<AkUInt32>( (AkUInt32) cChars ) )
00186                     return false;
00187 
00188                 AkInt32 cWritten = 0;
00189                 AkInt32 cToWrite = (AkInt32)( cChars * sizeof( wchar_t ) );
00190 
00191                 if ( cChars > 0 )
00192                 {
00193                     WriteBytes( in_pszString, cToWrite, cWritten );
00194                 }
00195 
00196                 return cWritten == cToWrite;
00197             }
00198             return Write<AkUInt32>( 0 );
00199         }
00200 
00201         /// Writes an ansi string. 
00202         /// \return True if the operation was successful, False otherwise
00203         bool WriteString( 
00204             const char * in_pszString ) ///< String to be written
00205         {
00206             if ( in_pszString != NULL )
00207             {
00208                 size_t cChars = strlen( in_pszString );
00209                 if ( !Write<AkUInt32>( (AkUInt32) cChars ) )
00210                     return false;
00211 
00212                 AkInt32 cWritten = 0;
00213 
00214                 if ( cChars > 0 )
00215                 {
00216                     WriteBytes( in_pszString, (AkInt32) cChars, cWritten );
00217                 }
00218 
00219                 return cWritten == (AkInt32) cChars;
00220             }
00221             return Write<AkUInt32>( 0 );
00222         }
00223         //@}
00224     };
00225 
00226     /// Generic memory buffer interface.
00227     /// \warning The functions in this interface are not thread-safe, unless stated otherwise.
00228     class IWriteBuffer : public IWriteBytes
00229     {
00230     public:
00231         ////////////////////////////////////////////////////////////////////////
00232         /// @name Interface
00233         //@{
00234 
00235         /// Get the number of bytes written to the buffer.
00236         /// \return number of bytes written.
00237         virtual AkInt32 Count() const = 0;
00238 
00239         /// Get pointer to buffer.
00240         /// \return pointer to buffer.
00241         virtual AkUInt8 * Bytes() const = 0;
00242 
00243         /// Set number of bytes written.
00244         virtual void SetCount( AkInt32 in_cBytes ) = 0;
00245 
00246         /// Allocate memory.
00247         /// \return true if allocation was successful.
00248         virtual bool Reserve( AkInt32 in_cBytes ) = 0;
00249 
00250         /// Clear the buffer contents.
00251         virtual void Clear() = 0;
00252 
00253         /// Return pointer to buffer and clear internal pointer.
00254         virtual AkUInt8 * Detach() = 0;
00255 
00256         //@}
00257     };
00258 }
00259 
00260 #endif // _AK_IBYTES_H