Version
menu_open
Wwise SDK 2023.1.4
IBytes.h
Go to the documentation of this file.
1 /*******************************************************************************
2 The content of this file includes portions of the AUDIOKINETIC Wwise Technology
3 released in source code form as part of the SDK installer package.
4 
5 Commercial License Usage
6 
7 Licensees holding valid commercial licenses to the AUDIOKINETIC Wwise Technology
8 may use this file in accordance with the end user license agreement provided
9 with the software or, alternatively, in accordance with the terms contained in a
10 written agreement between you and Audiokinetic Inc.
11 
12 Apache License Usage
13 
14 Alternatively, this file may be used under the Apache License, Version 2.0 (the
15 "Apache License"); you may not use this file except in compliance with the
16 Apache License. You may obtain a copy of the Apache License at
17 http://www.apache.org/licenses/LICENSE-2.0.
18 
19 Unless required by applicable law or agreed to in writing, software distributed
20 under the Apache License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES
21 OR CONDITIONS OF ANY KIND, either express or implied. See the Apache License for
22 the specific language governing permissions and limitations under the License.
23 
24  Copyright (c) 2024 Audiokinetic Inc.
25 *******************************************************************************/
26 
27 /// \file
28 /// AK::IReadBytes, AK::IWriteBytes simple serialization interfaces.
29 
30 #ifndef _AK_IBYTES_H
31 #define _AK_IBYTES_H
32 
33 #include <wchar.h>
35 
36 namespace AK
37 {
38  /// Generic binary input interface.
39  /// \akwarning
40  /// The functions in this interface are not thread-safe, unless stated otherwise.
41  /// \endakwarning
42  class IReadBytes
43  {
44  public:
45  ////////////////////////////////////////////////////////////////////////
46  /// @name Interface
47  //@{
48 
49  /// Reads some bytes into a buffer.
50  /// \return True if the operation was successful, False otherwise
51  virtual bool ReadBytes(
52  void * in_pData, ///< Pointer to a buffer
53  AkInt32 in_cBytes, ///< Size of the buffer (in bytes)
54  AkInt32 & out_cRead ///< Returned number of read bytes
55  ) = 0;
56 
57  //@}
58 
59  ////////////////////////////////////////////////////////////////////////
60  /// @name Helpers
61  //@{
62 
63  /// Reads a simple type or structure.
64  /// \akwarning
65  /// Not for object serialization.
66  /// \endakwarning
67  /// \return True if the operation was successful, False otherwise.
68  template<class T>
69  bool Read(
70  T & out_data) ///< Data to be read
71  {
72  AkInt32 cRead;
73  return ReadBytes(&out_data, sizeof(T), cRead);
74  }
75 
76  /// Reads a simple type or structure.
77  /// \warning This method does not allow for error checking. Use other methods when error cases need to be handled.
78  /// \warning Not for object serialization.
79  /// \return Read data
80  template<class T>
81  T Read()
82  {
83  T value;
84 
85  AkInt32 cRead;
86  ReadBytes(&value, sizeof(T), cRead);
87 
88  return value;
89  }
90 
91  /// Reads a string into a fixed-size buffer.
92  /// \return True if the operation was successful, False otherwise. An insufficient buffer size does not cause failure.
93  template<class CHAR_T>
94  bool ReadString(
95  CHAR_T * out_pszString, ///< Pointer to a fixed-size buffer
96  AkInt32 in_nMax) ///< Maximum number of characters to be read in out_pszString, including the terminating NULL character
97  {
98  AkInt32 cChars;
99  if (!Read<AkInt32>(cChars))
100  return false;
101 
102  bool bRet = true;
103 
104  if (cChars > 0)
105  {
106  AkInt32 cRead;
107 
108  if (cChars < in_nMax)
109  {
110  ReadBytes(out_pszString, cChars * sizeof(CHAR_T), cRead);
111  out_pszString[cChars] = 0;
112 
113  bRet = cRead == (AkInt32)(cChars * sizeof(CHAR_T));
114  }
115  else
116  {
117  ReadBytes(out_pszString, in_nMax * sizeof(CHAR_T), cRead);
118  out_pszString[in_nMax - 1] = 0;
119 
120  bRet = cRead == (AkInt32)(in_nMax * sizeof(CHAR_T));
121 
122  if (bRet)
123  {
124  // Read extra characters in temp buffer.
125  AkInt32 cRemaining = cChars - in_nMax;
126 
127  CHAR_T * pTemp = new CHAR_T[cRemaining];
128 
129  ReadBytes(pTemp, cRemaining * sizeof(CHAR_T), cRead);
130 
131  bRet = cRead == (AkInt32)(cRemaining * sizeof(CHAR_T));
132 
133  delete[] pTemp;
134  }
135  }
136  }
137  else
138  {
139  out_pszString[0] = 0;
140  }
141 
142  return bRet;
143  }
144  //@}
145  };
146 
147  /// Generic binary output interface.
148  /// \akwarning
149  /// The functions in this interface are not thread-safe, unless stated otherwise.
150  /// \endakwarning
152  {
153  public:
154  ////////////////////////////////////////////////////////////////////////
155  /// @name Interface
156  //@{
157 
158  /// Writes some bytes from a buffer.
159  /// \return True if the operation was successful, False otherwise
160  virtual bool WriteBytes(
161  const void * in_pData, ///< Pointer to a buffer
162  AkInt32 in_cBytes, ///< Size of the buffer (in bytes)
163  AkInt32 & out_cWritten ///< Returned number of written bytes
164  ) = 0;
165 
166  //@}
167 
168  ////////////////////////////////////////////////////////////////////////
169  /// @name Helpers
170  //@{
171 
172  /// Writes a simple type or struct.
173  /// \warning Not for object serialization.
174  /// \return True if the operation was successful, False otherwise
175  template<class T>
176  bool Write(
177  const T & in_data) ///< Data to be written
178  {
179  AkInt32 cWritten;
180  return WriteBytes(&in_data, sizeof(T), cWritten);
181  }
182 
183  /// Writes a unicode string.
184  /// \return True if the operation was successful, False otherwise
186  const wchar_t * in_pszString) ///< String to be written
187  {
188  if (in_pszString != NULL)
189  {
190  size_t cChars = wcslen(in_pszString);
191  if (!Write<AkUInt32>((AkUInt32)cChars))
192  return false;
193 
194  AkInt32 cWritten = 0;
195  AkInt32 cToWrite = (AkInt32)(cChars * sizeof(wchar_t));
196 
197  if (cChars > 0)
198  {
199  WriteBytes(in_pszString, cToWrite, cWritten);
200  }
201 
202  return cWritten == cToWrite;
203  }
204  return Write<AkUInt32>(0);
205  }
206 
207  /// Writes an ansi string.
208  /// \return True if the operation was successful, False otherwise
210  const char * in_pszString) ///< String to be written
211  {
212  if (in_pszString != NULL)
213  {
214  size_t cChars = strlen(in_pszString);
215  if (!Write<AkUInt32>((AkUInt32)cChars))
216  return false;
217 
218  AkInt32 cWritten = 0;
219 
220  if (cChars > 0)
221  {
222  WriteBytes(in_pszString, (AkInt32)cChars, cWritten);
223  }
224 
225  return cWritten == (AkInt32)cChars;
226  }
227  return Write<AkUInt32>(0);
228  }
229  //@}
230  };
231 
232  /// Generic memory buffer interface.
233  /// \akwarning
234  /// The functions in this interface are not thread-safe, unless stated otherwise.
235  /// \endakwarning
236  class IWriteBuffer : public IWriteBytes
237  {
238  public:
239  ////////////////////////////////////////////////////////////////////////
240  /// @name Interface
241  //@{
242 
243  /// Get the number of bytes written to the buffer.
244  /// \return number of bytes written.
245  virtual AkInt32 Count() const = 0;
246 
247  /// Get pointer to buffer.
248  /// \return pointer to buffer.
249  virtual AkUInt8 * Bytes() const = 0;
250 
251  /// Set number of bytes written.
252  virtual void SetCount(AkInt32 in_cBytes) = 0;
253 
254  /// Allocate memory.
255  /// \return true if allocation was successful.
256  virtual bool Reserve(AkInt32 in_cBytes) = 0;
257 
258  /// Clear the buffer contents.
259  virtual void Clear() = 0;
260 
261  /// Return pointer to buffer and clear internal pointer.
262  virtual AkUInt8 * Detach() = 0;
263 
264  //@}
265  };
266 }
267 
268 #endif // _AK_IBYTES_H
virtual AkUInt8 * Detach()=0
Return pointer to buffer and clear internal pointer.
bool ReadString(CHAR_T *out_pszString, AkInt32 in_nMax)
Definition: IBytes.h:94
Audiokinetic namespace.
bool WriteString(const char *in_pszString)
Definition: IBytes.h:209
bool Read(T &out_data)
Definition: IBytes.h:69
uint8_t AkUInt8
Unsigned 8-bit integer.
virtual bool Reserve(AkInt32 in_cBytes)=0
virtual void SetCount(AkInt32 in_cBytes)=0
Set number of bytes written.
#define NULL
Definition: AkTypes.h:46
int32_t AkInt32
Signed 32-bit integer.
virtual bool WriteBytes(const void *in_pData, AkInt32 in_cBytes, AkInt32 &out_cWritten)=0
bool Write(const T &in_data)
Definition: IBytes.h:176
virtual bool ReadBytes(void *in_pData, AkInt32 in_cBytes, AkInt32 &out_cRead)=0
bool WriteString(const wchar_t *in_pszString)
Definition: IBytes.h:185
virtual AkInt32 Count() const =0
uint32_t AkUInt32
Unsigned 32-bit integer.
virtual AkUInt8 * Bytes() const =0
virtual void Clear()=0
Clear the buffer contents.

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Register your project and we'll help you get started with no strings attached!

Get started with Wwise