Wwise Version
Wwise SDK 2021.1.5
HostXml.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  Version: v2021.1.5 Build: 7749
25  Copyright (c) 2006-2021 Audiokinetic Inc.
26 *******************************************************************************/
27 
28 /**
29  * \brief Wwise Authoring Plug-ins - API for XML-based persistence, as used in CustomData.
30  * \file AK/Wwise/Plugin/HostXml.h
31  */
32 
33 #pragma once
34 
35 #include "PluginInfoGenerator.h"
36 
37 namespace AK
38 {
39  namespace Wwise
40  {
41  namespace Plugin
42  {
43  ///
44  namespace XmlWhiteSpaceHandling
45  {
46  /// See MSDN documentation
48  {
49  All,
52  };
53  }
54 
55  /// Types of possible XML elements. See MSDN documentation topics for XmlNodeType.
56  namespace XmlNodeType
57  {
58  /// See MSDN documentation topics for XmlNodeType.
59  /// MUST match XmlLite node types
60  enum NodeType
61  {
62  Attribute = 2,
63  CDATA = 4,
64  Comment = 8,
65  Document = 9,
68  Element = 1,
69  EndElement = 15,
70  EndEntity = 16,
71  Entity = 6,
73  None = 0,
74  Notation = 12,
77  Text = 3,
78  Whitespace = 13,
79  XmlDeclaration = 17
80  };
81  }
82  namespace XmlWriteState
83  {
84  /// WriteState
85  enum WriteState
86  {
87  Attribute, ///< Attribute
88  Closed, ///< Closed
89  Content, ///< Content
90  Element, ///< Element
91  Prolog, ///< Prolog
92  Start ///< Start
93  };
94  }
95 
96  /// Possible error codes when writing XML
97  namespace XmlWriteReady
98  {
99  /// Possible error codes when writing XML
101  {
102  Ready, ///< No error
103  ErrorPathTooLong, ///< Path exceeds max length
104  ErrorAccessDenied, ///< Cannot open file due to access permissions
105  ErrorUnknown ///< Unknown error
106  };
107  }
108 
109  namespace XmlElementType
110  {
111  /// These element types have an impact when outputting in alternate formats such as JSON.
113  {
114  Map, // Associative (Unique Keys)
115  Array, // Enumerative
116  MultiMap // Associative (Shared Keys)
117  };
118  };
119  }
120  }
121 }
122 
123 /**
124  * \brief API interface for XML-based plug-in persistence.
125  *
126  * The XML plug-in persistence is useful when a plug-in provides custom data handling. Normally, plug-in data
127  * is stored through the property sets (see \ref wwiseplugin_propertyset "PropertySet" and \ref wwiseplugin_objectstore "ObjectStore").
128  * However, a plug-in might provide its own custom handling. For complex interfaces, it might be worthwhile to use the
129  * \ref wwiseplugin_complexproperty "CustomData" interface. Loading and saving can then be done through this XML interface.
130  *
131  * The XML interface represents a cursor pointing to a node (element), alongside methods to navigate through
132  * the hierarchy.
133  *
134  * \aknote
135  * One unique XML interface is provided for both reading and writing XML. Depending on the instance being
136  * provided, it will allow reading or writing through this interface.
137  *
138  * It can either be a \ref ak_wwise_plugin_host_xml_reader_instance_v1 or a
139  * \ref ak_wwise_plugin_host_xml_writer_instance_v1.
140  * \endaknote
141  */
143 #ifdef __cplusplus
145 #endif
146 {
147 #ifndef __cplusplus
148  ak_wwise_plugin_base_interface m_baseInterface;
149 #endif
150 
151 #ifdef __cplusplus
154  {}
157 #endif
158 
159  /**
160  * \brief Returns the name of the current node being read.
161  *
162  * \aknote
163  * The string is available until the next Host operation. If storing is required, a copy should be made
164  * at the earliest convenience.
165  * \endaknote
166  *
167  * \param[in] in_this Current reader instance of this interface.
168  * \return The name of the current node. The buffer is owned by Authoring and is
169  * valid until the next API call.
170  */
171  const char *(*GetName)(const struct ak_wwise_plugin_host_xml_reader_instance_v1* in_this);
172 
173  /**
174  * \brief Returns the type of the current node being read.
175  *
176  * The type is equivalent to Microsoft Windows \c XmlNodeType. See MSDN documentation on
177  * \c XmlNodeType for further information.
178  *
179  * \param[in] in_this Current reader instance of this interface.
180  * \return The type of the current node.
181  */
183 
184  /**
185  * \brief Tests whether the current node being read is empty.
186  *
187  * \param[in] in_this Current reader instance of this interface.
188  * \return true if the current node is empty.
189  */
191 
192  /**
193  * \brief Returns the value of the current node being read.
194  *
195  * This returns the textual representation of the current node's value. What the XML parser considers
196  * to be a value might not be what is expected, as the final text could be comprised of multiple
197  * values.
198  *
199  * For example, this \c Item node has three content elements: <tt>&lt;Item&gt;1&amp;number;3&lt;/Item&gt;</tt>
200  *
201  * For normal string retrieval, the \ref ReadElementString will actually return the value of an XML with
202  * proper parsing applied.
203  *
204  * \aknote
205  * The string is available until the next Host operation. If storing is required, a copy should be made
206  * at the earliest convenience.
207  * \endaknote
208  *
209  * \param[in] in_this Current reader instance of this interface.
210  * \return The value of the current node, an empty string if the value is empty.
211  * The buffer is owned by Authoring and is valid until the next API call.
212  */
213  const char *(*GetValue)(const struct ak_wwise_plugin_host_xml_reader_instance_v1* in_this);
214 
215  /**
216  * \brief Tests whether the end of file is reached while reading the XML.
217  *
218  * The last valid node of the file is consdiered the end-of-file point. It can be
219  * \c SignificantWhitespace if the file ends with supplemental lines.
220  *
221  * \param[in] in_this Current reader instance of this interface.
222  * \return true if the end of file is reached.
223  */
224  bool(*IsEOF)(const struct ak_wwise_plugin_host_xml_reader_instance_v1* in_this);
225 
226  /**
227  * \brief Retrieves the line number that contains the start of the current node being read.
228  *
229  * This is useful in some cases, where an error message might be written, or for debugging purposes.
230  *
231  * \param[in] in_this Current reader instance of this interface.
232  * \return Current line number in the file.
233  */
235 
236  /**
237  * \brief Retrieves the column in the line that contains the start of the current node being read.
238  *
239  * This is useful in some cases, where an error message might be written, or for debugging purposes.
240  *
241  * \param[in] in_this Current reader instance of this interface.
242  * \return Current column number in the line.
243  */
245 
246  /**
247  * \brief Makes sure the cursor points to a content-type entity while reading XML.
248  *
249  * If the node is not a content node, the reader skips ahead to the next content entity until the
250  * end of file. More specifically, it will skip over the following usual node types:
251  * - \c ProcessingInstruction
252  * - \c DocumentType
253  * - \c Comment
254  * - \c Whitespace
255  * - \c SignificantWhitespace
256  *
257  * Content entities are specifically:
258  * - \c Text (Non-whitespace text)
259  * - \c CDATA
260  * - \c Element
261  * - \c EndElement
262  * - \c EndEntity
263  * - \c EntityReference
264  *
265  * This method will also move to the element part of an \c Attribute.
266  *
267  * \aknote
268  * This method is mostly a convenience and could be easily coded by a simple loop.
269  *
270  * Once the current node hierarchy information is determined by proper use of
271  * \ref Read, MoveToContent will make sure to provide the actual content of the entity. If no
272  * content is available, it will return \ref AK::Wwise::Plugin::XmlNodeType::EndElement "EndElement"
273  * or \ref AK::Wwise::Plugin::XmlNodeType::EndEntity "EndEntity".
274  * \endaknote
275  *
276  * \param[in] in_this Current reader instance of this interface.
277  * \return The new node type. \c None if the reader has reached the end of file.
278  */
280 
281  /**
282  * \brief Sets the reading pointer to the next node, recursively.
283  *
284  * The node can be any entity type except \c SignificantWhitespace.
285  *
286  * \param[in] in_this Current reader instance of this interface.
287  * \return false if the end of file is reached.
288  */
290 
291  /**
292  * \brief Reads simple text-only elements, and increments the pointer.
293  *
294  * Since strings can span multiple content elements, this method will read all the sequential string-like
295  * elements and append them, returning one simple string. This function also works with empty nodes and
296  * multiple lines.
297  *
298  * If no processing or incrementing is warranted, \ref Read, \ref MoveToContent and \ref GetValue
299  * should be used instead.
300  *
301  * This method goes past the ending element node, or the equivalent of calling Read once more.
302  *
303  * \aknote
304  * The string is available until the next Host operation. If storing is required, a copy should be made
305  * at the earliest convenience.
306  * \endaknote
307  *
308  * \param[in] in_this Current reader instance of this interface.
309  * \return The string of the current nodes, an empty string if the value is empty.
310  * The buffer is owned by Authoring and is valid until the next API call.
311  */
312  const char *(*ReadElementString)(struct ak_wwise_plugin_host_xml_reader_instance_v1* in_this);
313 
314  /**
315  * \brief Reads all the contents of an Element or Attribute as a string, including markup. Increments the pointer.
316  *
317  * This returns the raw contents of the file except the enclosing elements. It can be considered the
318  * equivalent of \ref ReadElementString , but will also return raw XML tags.
319  *
320  * An empty string will be returned if no content is available.
321  *
322  * \aknote
323  * The string is available until the next Host operation. If storing is required, a copy should be made
324  * at the earliest convenience.
325  * \endaknote
326  *
327  * \param[in] in_this Current reader instance of this interface.
328  * \param[out] out_csXml All the XML content, including markup, in the current node.
329  * The buffer is owned by Authoring and is valid until the next API call.
330  */
331  void(*ReadInnerXml)(struct ak_wwise_plugin_host_xml_reader_instance_v1* in_this, const char ** out_csXml);
332 
333  /**
334  * \brief Reads the Element or Attribute as a string, including markup. Increments the pointer.
335  *
336  * This returns the raw contents of the file including the enclosing elements. It can be considered the
337  * equivalent of \ref ReadElementString , but will also return raw XML tags.
338  *
339  * An empty string will be returned if no content is available.
340  *
341  * \aknote
342  * The string is available until the next Host operation. If storing is required, a copy should be made
343  * at the earliest convenience.
344  * \endaknote
345  *
346  * \param[in] in_this Current reader instance of this interface.
347  * \param[out] out_csXml All the XML content, including markup and enclosing tags, of the current node.
348  * The buffer is owned by Authoring and is valid until the next API call.
349  */
350  void(*ReadOuterXml)(struct ak_wwise_plugin_host_xml_reader_instance_v1* in_this, const char ** out_csXml);
351 
352  /**
353  * \brief Sets the reading pointer past the current node, skipping any inner content.
354  *
355  * \param[in] in_this Current reader instance of this interface.
356  * \return false if the end of file is reached.
357  */
359 
360  /**
361  * \brief Reads the value of a particular attribute under the current node.
362  *
363  * \param[in] in_this Current reader instance of this interface.
364  * \param[in] in_rcsAttributeName The attribute name
365  * \param[out] out_rcsValue The attribute value.
366  * The buffer is owned by Authoring and is valid until the next API call.
367  * \return true if the value exists.
368  */
369  bool(*GetAttribute)(
371  const char * in_rcsAttributeName,
372  const char ** out_rcsValue
373  );
374 
375 
376  /**
377  * \brief Determines if the writer is ready to be used.
378  * \internal
379  *
380  * For plug-ins, the XML writer is always ready.
381  *
382  * \param[in] in_this Current writer instance of this interface.
383  * \return true if ready.
384  */
386 
387  /**
388  * \brief Determines the state of readiness of the writer.
389  * \internal
390  *
391  * For plug-ins, the XML writer is always ready.
392  *
393  * \param[in] in_this Current writer instance of this interface.
394  * \return \c Ready if ready.
395  */
397 
398  /**
399  * \brief Appending a first XML writer to a second XML writer.
400  * \internal
401  *
402  * For plug-ins, there aren't multiple writer instances.
403  *
404  * \param[in] in_this Current writer instance of this interface.
405  * \param[in] in_pWriterToAppend Second writer instance to append to our current instance.
406  * \return true if successful
407  */
409 
410  /**
411  * \brief Retrieves the state of the node the writer is currently populating.
412  * \internal
413  *
414  * For plug-ins, the states are very simple.
415  *
416  * \param[in] in_this Current writer instance of this interface.
417  * \return The current write state.
418  */
420 
421  /**
422  * \brief Starts a new XML document.
423  * \internal
424  *
425  * For plug-ins, the XML document is already created.
426  *
427  * \param[in] in_this Current writer instance of this interface.
428  */
430 
431  /**
432  * \brief Ends a completed XML document.
433  * \internal
434  *
435  * For plug-ins, the XML document will be closed for you.
436  *
437  * \param[in] in_this Current writer instance of this interface.
438  */
440 
441  /**
442  * \brief Creates a new inner node.
443  *
444  * You should close this element with \ref WriteEndElement.
445  *
446  * \param[in] in_this Current writer instance of this interface.
447  * \param[in] in_rcsElementName Node name, as retrieved on the reader with \ref GetName.
448  * \param[in] in_eType Ignored.
449  */
452  const char * in_rcsElementName,
454  );
455 
456  /**
457  * \brief Closes the previous node.
458  *
459  * \param[in] in_this Current writer instance of this interface.
460  */
462 
463  /**
464  * \brief Adds an attribute to the current node.
465  *
466  * \param[in] in_this Current writer instance of this interface.
467  * \param[in] in_rcsAttribute Attribute name.
468  * \param[in] in_rcsValue Attribute value.
469  */
472  const char * in_rcsAttribute,
473  const char * in_rcsValue
474  );
475 
476  /**
477  * \brief Appends a string as value to the current node.
478  *
479  * \param[in] in_this Current writer instance of this interface.
480  * \param[in] in_rcsValue Node value.
481  */
482  void(*WriteString)(
484  const char * in_rcsValue
485  );
486 
487  /**
488  * \brief Appends a raw CDATA string as value to the current node.
489  *
490  * No processing of the CDATA is done.
491  *
492  * \param[in] in_this Current writer instance of this interface.
493  * \param[in] in_rcsValue Node's raw value to be inserted insde a `<![CDATA[...]]>`
494  */
495  void(*WriteCData)(
497  const char * in_rcsValue
498  );
499 
500  /**
501  * \brief Appends a raw string at this precise point of the XML file.
502  *
503  * No processing of the data is done.
504  *
505  * \param[in] in_this Current writer instance of this interface.
506  * \param[in] in_rcsValue Node's raw value to be inserted.
507  */
508  void(*WriteRaw)(
510  const char * in_rcsValue
511  );
512 
513 };
514 #define AK_WWISE_PLUGIN_HOST_XML_V1_ID() \
515  AK_WWISE_PLUGIN_BASE_INTERFACE_FROM_ID(AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST_XML, 1)
516 #define AK_WWISE_PLUGIN_HOST_XML_V1_CTOR() \
517 { \
518  .m_baseInterface = AK_WWISE_PLUGIN_HOST_XML_V1_ID() \
519 }
520 
521 
522 #ifdef __cplusplus
523 namespace AK::Wwise::Plugin
524 {
525  namespace V1
526  {
528 
529  /// \copydoc ak_wwise_plugin_host_xml_v1
530  class XmlReader : public CBaseInstanceGlue<CHostXml, CHostXml::ReaderInstance>
531  {
532  public:
534 
535  /**
536  * \brief The interface type, as requested by this plug-in.
537  */
538  enum : InterfaceTypeValue
539  {
540  /**
541  * \brief The interface type, as requested by this plug-in.
542  */
544  };
545  /**
546  * \brief The interface version, as requested by this plug-in.
547  */
548  enum : InterfaceVersion
549  {
550  /**
551  * \brief The interface version, as requested by this plug-in.
552  */
554  };
555 
556  /**
557  * \brief Returns the name of the current node being read.
558  *
559  * \aknote
560  * The string is available until the next Host operation. If storing is required, a copy should be made
561  * at the earliest convenience.
562  * \endaknote
563  *
564  * \return The name of the current node.
565  * The buffer is owned by Authoring and is valid until the next API call.
566  */
567  inline const char * GetName() const { return g_cinterface->GetName(this); }
568 
569  /**
570  * \brief Returns the type of the current node being read.
571  *
572  * The type is equivalent to Microsoft Windows \c XmlNodeType. See MSDN documentation on
573  * \c XmlNodeType for further information.
574  *
575  * \return The type of the current node.
576  */
578 
579  /**
580  * \brief Tests whether the current node being read is empty.
581  *
582  * \return true if the current node is empty.
583  */
584  inline bool IsEmptyElement() const { return MKBOOL(g_cinterface->IsEmptyElement(this)); }
585 
586  /**
587  * \brief Returns the value of the current node being read.
588  *
589  * This returns the textual representation of the current node's value. What the XML parser considers
590  * to be a value might not be what is expected, as the final text could be comprised of multiple
591  * values.
592  *
593  * For example, this \c Item node has three content elements: <tt>&lt;Item&gt;1&amp;number;3&lt;/Item&gt;</tt>
594  *
595  * For normal string retrieval, the \ref ReadElementString will actually return the value of an XML with
596  * proper parsing applied.
597  *
598  * \aknote
599  * The string is available until the next Host operation. If storing is required, a copy should be made
600  * at the earliest convenience.
601  * \endaknote
602  *
603  * \return The value of the current node, an empty string if the value is empty.
604  * The buffer is owned by Authoring and is valid until the next API call.
605  */
606  inline const char * GetValue() const { return g_cinterface->GetValue(this); }
607 
608  /**
609  * \brief Tests whether the end of file is reached while reading the XML.
610  *
611  * The last valid node of the file is consdiered the end-of-file point. It can be
612  * \c SignificantWhitespace if the file ends with supplemental lines.
613  *
614  * \return true if the end of file is reached.
615  */
616  inline bool IsEOF() const { return MKBOOL(g_cinterface->IsEOF(this)); }
617 
618  /**
619  * \brief Retrieves the line number that contains the start of the current node being read.
620  *
621  * This is useful in some cases, where an error message might be written, or for debugging purposes.
622  *
623  * \return Current line number in the file.
624  */
625  inline int GetLineNumber() const { return g_cinterface->GetLineNumber(this); }
626 
627  /**
628  * \brief Retrieves the column in the line that contains the start of the current node being read.
629  *
630  * This is useful in some cases, where an error message might be written, or for debugging purposes.
631  *
632  * \return Current column number in the line.
633  */
634  inline int GetLinePosition() const { return g_cinterface->GetLinePosition(this); }
635 
636  /**
637  * \brief Makes sure the cursor points to a content-type entity while reading XML.
638  *
639  * If the node is not a content node, the reader skips ahead to the next content entity until the
640  * end of file. More specifically, it will skip over the following usual node types:
641  * - \c ProcessingInstruction
642  * - \c DocumentType
643  * - \c Comment
644  * - \c Whitespace
645  * - \c SignificantWhitespace
646  *
647  * Content entities are specifically:
648  * - \c Text (Non-whitespace text)
649  * - \c CDATA
650  * - \c Element
651  * - \c EndElement
652  * - \c EndEntity
653  * - \c EntityReference
654  *
655  * This method will also move to the element part of an \c Attribute.
656  *
657  * \aknote
658  * This method is mostly a convenience and could be easily coded by a simple loop.
659  *
660  * Once the current node hierarchy information is determined by proper use of
661  * \ref Read, MoveToContent will make sure to provide the actual content of the entity. If no
662  * content is available, it will return \ref AK::Wwise::Plugin::XmlNodeType::EndElement "EndElement"
663  * or \ref AK::Wwise::Plugin::XmlNodeType::EndEntity "EndEntity".
664  * \endaknote
665  *
666  * \return The new node type. \c None if the reader has reached the end of file.
667  */
669 
670  /**
671  * \brief Sets the reading pointer to the next node, recursively.
672  *
673  * The node can be any entity type except \c SignificantWhitespace.
674  *
675  * \return false if the end of file is reached.
676  */
677  inline bool Read() { return MKBOOL(g_cinterface->Read(this)); }
678 
679  /**
680  * \brief Reads simple text-only elements, and increments the pointer.
681  *
682  * Since strings can span multiple content elements, this method will read all the sequential string-like
683  * elements and append them, returning one simple string. This function also works with empty nodes and
684  * multiple lines.
685  *
686  * If no processing or incrementing is warranted, \ref Read, \ref MoveToContent and \ref GetValue
687  * should be used instead.
688  *
689  * This method goes past the ending element node, or the equivalent of calling Read once more.
690  *
691  * \aknote
692  * The string is available until the next Host operation. If storing is required, a copy should be made
693  * at the earliest convenience.
694  * \endaknote
695  *
696  * \return The string of the current nodes, an empty string if the value is empty.
697  * The buffer is owned by Authoring and is valid until the next API call.
698  */
699  inline const char * ReadElementString() { return g_cinterface->ReadElementString(this); }
700 
701  /**
702  * \brief Reads all the contents of an Element or Attribute as a string, including markup. Increments the pointer.
703  *
704  * This returns the raw contents of the file except the enclosing elements. It can be considered the
705  * equivalent of \ref ReadElementString , but will also return raw XML tags.
706  *
707  * An empty string will be returned if no content is available.
708  *
709  * \aknote
710  * The string is available until the next Host operation. If storing is required, a copy should be made
711  * at the earliest convenience.
712  * \endaknote
713  *
714  * \param[out] out_csXml All the XML content, including markup, in the current node.
715  * The buffer is owned by Authoring and is valid until the next API call.
716  */
717  inline void ReadInnerXml(const char *& out_csXml) { g_cinterface->ReadInnerXml(this, &out_csXml); }
718 
719  /**
720  * \brief Reads the Element or Attribute as a string, including markup. Increments the pointer.
721  *
722  * This returns the raw contents of the file including the enclosing elements. It can be considered the
723  * equivalent of \ref ReadElementString , but will also return raw XML tags.
724  *
725  * An empty string will be returned if no content is available.
726  *
727  * \aknote
728  * The string is available until the next Host operation. If storing is required, a copy should be made
729  * at the earliest convenience.
730  * \endaknote
731  *
732  * \param[out] out_csXml All the XML content, including markup and enclosing tags, of the current node.
733  * The buffer is owned by Authoring and is valid until the next API call.
734  */
735  inline void ReadOuterXml(const char *& out_csXml) { g_cinterface->ReadOuterXml(this, &out_csXml); }
736 
737  /**
738  * \brief Sets the reading pointer past the current node, skipping any inner content.
739  *
740  * \return false if the end of file is reached.
741  */
742  inline void Skip() { g_cinterface->Skip(this); }
743 
744  /**
745  * \brief Reads the value of a particular attribute under the current node.
746  *
747  * \param[in] in_rcsAttributeName The attribute name
748  * \param[out] out_rcsValue The attribute value.
749  * The buffer is owned by Authoring and is valid until the next API call.
750  * \return true if the value exists.
751  */
752  inline bool GetAttribute(const char * in_rcsAttributeName, const char *& out_rcsValue) { return MKBOOL(g_cinterface->GetAttribute(this, in_rcsAttributeName, &out_rcsValue)); }
753  };
754 
755  /// \copydoc ak_wwise_plugin_host_xml_v1
756  class XmlWriter : public CBaseInstanceGlue<CHostXml, CHostXml::WriterInstance>
757  {
758  public:
760 
761  /**
762  * \brief The interface type, as requested by this plug-in.
763  */
764  enum : InterfaceTypeValue
765  {
766  /**
767  * \brief The interface type, as requested by this plug-in.
768  */
770  };
771  /**
772  * \brief The interface version, as requested by this plug-in.
773  */
774  enum : InterfaceVersion
775  {
776  /**
777  * \brief The interface version, as requested by this plug-in.
778  */
780  };
781 
782  /**
783  * \brief Determines if the writer is ready to be used.
784  * \internal
785  *
786  * For plug-ins, the XML writer is always ready.
787  *
788  * \return true if ready.
789  */
790  inline bool IsReady() const { return MKBOOL(g_cinterface->IsReady(this)); }
791 
792  /**
793  * \brief Determines the state of readiness of the writer.
794  * \internal
795  *
796  * For plug-ins, the XML writer is always ready.
797  *
798  * \return \c Ready if ready.
799  */
801 
802  /**
803  * \brief Appending a first XML writer to a second XML writer.
804  * \internal
805  *
806  * For plug-ins, there aren't multiple writer instances.
807  *
808  * \param[in] in_writerToAppend Second writer instance to append to our current instance.
809  * \return true if successful
810  */
811  inline bool Append(XmlWriter& in_writerToAppend) { return MKBOOL(g_cinterface->Append(this, &in_writerToAppend)); }
812 
813  /**
814  * \brief Retrieves the state of the node the writer is currently populating.
815  * \internal
816  *
817  * For plug-ins, the states are very simple.
818  *
819  * \param[in] in_this Current writer instance of this interface.
820  * \return The current write state.
821  */
823 
824  /**
825  * \brief Starts a new XML document.
826  * \internal
827  *
828  * For plug-ins, the XML document is already created.
829  */
831 
832  /**
833  * \brief Ends a completed XML document.
834  * \internal
835  *
836  * For plug-ins, the XML document will be closed for you.
837  */
839 
840  /**
841  * \brief Creates a new inner node.
842  *
843  * You should close this element with \ref WriteEndElement.
844  *
845  * \param[in] in_rcsElementName Node name, as retrieved on the reader with \ref AK::Wwise::Plugin::XmlReader::GetName "GetName".
846  * \param[in] in_eType Ignored.
847  */
848  inline void WriteStartElement(const char * in_rcsElementName, AK::Wwise::Plugin::XmlElementType::ElementType in_eType) { g_cinterface->WriteStartElement(this, in_rcsElementName, in_eType); }
849 
850  /**
851  * \brief Closes the previous node.
852  */
853  inline void WriteEndElement() { g_cinterface->WriteEndElement(this); }
854 
855  /**
856  * \brief Adds an attribute to the current node.
857  *
858  * \param[in] in_rcsAttribute Attribute name.
859  * \param[in] in_rcsValue Attribute value.
860  */
861  inline void WriteAttributeString(const char * in_rcsAttribute, const char * in_rcsValue) { g_cinterface->WriteAttributeString(this, in_rcsAttribute, in_rcsValue); }
862 
863  /**
864  * \brief Appends a string as value to the current node.
865  *
866  * \param[in] in_rcsValue Node value.
867  */
868  inline void WriteString(const char * in_rcsValue) { g_cinterface->WriteString(this, in_rcsValue); }
869 
870  /**
871  * \brief Appends a raw CDATA string as value to the current node.
872  *
873  * No processing of the CDATA is done.
874  *
875  * \param[in] in_rcsValue Node's raw value to be inserted inside a `<![CDATA[...]]>`
876  */
877  inline void WriteCData(const char * in_rcsValue) { g_cinterface->WriteCData(this, in_rcsValue); }
878 
879  /**
880  * \brief Appends a raw string at this precise point of the XML file.
881  *
882  * No processing of the data is done.
883  *
884  * \param[in] in_rcsValue Node's raw value to be inserted.
885  */
886  inline void WriteRaw(const char * in_rcsValue) { g_cinterface->WriteRaw(this, in_rcsValue); }
887 
888  /// Use this class to handle the WriteStartElement/WriteEndElement pair automatically in a C++ scope.
890  {
891  public:
892 
893  /// Calls WriteStartElement automatically
895  : m_pWriter( in_pWriter )
896  {
897  m_pWriter->WriteStartElement( in_rcsElementName, in_eType );
898  }
899 
901  : m_pWriter( &in_pWriter )
902  {
903  m_pWriter->WriteStartElement( in_rcsElementName, in_eType );
904  }
905 
906  /// Calls WriteEndElement automatically
908  {
909  m_pWriter->WriteEndElement();
910  }
911 
912  private:
913  XmlWriter* m_pWriter;
914  };
915  };
916 
917  /**
918  * \brief Requests the XML processing interface.
919  *
920  * Deriving your plug-in class from RequestXml will automatically request
921  * XmlReader and XmlWriter interfaces. This is useful for
922  * CustomData loading and saving. You must derive from this interface
923  * in order to use the provided functions.
924  *
925  * \aknote The RequestXml class is automatically derived when providing
926  * AK::Wwise::Plugin::CustomData in C++. \endaknote
927  */
929 
930  } // of namespace V1
931 
932  /// Latest version of the C XML interface.
934  /// Latest version of the C++ XmlReader interface.
936  /// Latest version of the C++ XmlWriter interface.
938  /// Latest version of the requested C++ XML interface.
940 
945 
946  // This uses the same interface than XmlReader so no need to specialize it twice.
947  // AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(XmlWriter);
948  // AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(XmlWriter);
949 
950 } // of namespace AK::Wwise::Plugin
951 #endif
void(* WriteStartElement)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this, const char *in_rcsElementName, AK::Wwise::Plugin::XmlElementType::ElementType in_eType)
Creates a new inner node.
Definition: HostXml.h:450
RequestedHostInterface< XmlReader > RequestXml
Requests the XML processing interface.
Definition: HostXml.h:928
void(* ReadInnerXml)(struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this, const char **out_csXml)
Reads all the contents of an Element or Attribute as a string, including markup. Increments the point...
Definition: HostXml.h:331
void WriteEndDocument()
Ends a completed XML document.
Definition: HostXml.h:838
void WriteRaw(const char *in_rcsValue)
Appends a raw string at this precise point of the XML file.
Definition: HostXml.h:886
int(* GetLinePosition)(const struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Retrieves the column in the line that contains the start of the current node being read.
Definition: HostXml.h:244
Audiokinetic namespace.
AK::Wwise::Plugin::XmlWriteState::WriteState(* GetWriteState)(const struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this)
Retrieves the state of the node the writer is currently populating.
Definition: HostXml.h:419
bool(* Read)(struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Sets the reading pointer to the next node, recursively.
Definition: HostXml.h:289
static GluedInterface * g_cinterface
The unique instance of the CInterface interface. Defined at nullptr first, overridden by the Host onc...
void ReadInnerXml(const char *&out_csXml)
Reads all the contents of an Element or Attribute as a string, including markup. Increments the point...
Definition: HostXml.h:717
bool GetAttribute(const char *in_rcsAttributeName, const char *&out_rcsValue)
Reads the value of a particular attribute under the current node.
Definition: HostXml.h:752
AK::Wwise::Plugin::XmlNodeType::NodeType MoveToContent()
Makes sure the cursor points to a content-type entity while reading XML.
Definition: HostXml.h:668
decltype(BaseInterface::m_version) InterfaceVersion
PluginInfoGenerator: Type for the m_version value in BaseInterface.
AK::Wwise::Plugin::XmlWriteReady::WriteReady(* GetReadyState)(const struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this)
Determines the state of readiness of the writer.
Definition: HostXml.h:396
bool(* IsReady)(const struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this)
Determines if the writer is ready to be used.
Definition: HostXml.h:385
AK::Wwise::Plugin::XmlWriteState::WriteState GetWriteState() const
Retrieves the state of the node the writer is currently populating.
Definition: HostXml.h:822
const char * GetName() const
Returns the name of the current node being read.
Definition: HostXml.h:567
int GetLineNumber() const
Retrieves the line number that contains the start of the current node being read.
Definition: HostXml.h:625
@ k_interfaceVersion
The interface version, as requested by this plug-in.
Definition: HostXml.h:553
void(* WriteCData)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this, const char *in_rcsValue)
Appends a raw CDATA string as value to the current node.
Definition: HostXml.h:495
const char * GetValue() const
Returns the value of the current node being read.
Definition: HostXml.h:606
AutoStartEndElement(const char *in_rcsElementName, XmlWriter *in_pWriter, AK::Wwise::Plugin::XmlElementType::ElementType in_eType=AK::Wwise::Plugin::XmlElementType::Map)
Calls WriteStartElement automatically.
Definition: HostXml.h:894
void WriteStartDocument()
Starts a new XML document.
Definition: HostXml.h:830
@ ErrorAccessDenied
Cannot open file due to access permissions.
Definition: HostXml.h:104
bool(* IsEOF)(const struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Tests whether the end of file is reached while reading the XML.
Definition: HostXml.h:224
void WriteAttributeString(const char *in_rcsAttribute, const char *in_rcsValue)
Adds an attribute to the current node.
Definition: HostXml.h:861
@ AK_WWISE_PLUGIN_INTERFACE_TYPE_HOST_XML
2021.1 XML reading and writing host services. ak_wwise_plugin_host_xml_v1
AK::Wwise::Plugin::XmlNodeType::NodeType(* MoveToContent)(struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Makes sure the cursor points to a content-type entity while reading XML.
Definition: HostXml.h:279
AK::Wwise::Plugin::XmlWriteReady::WriteReady GetReadyState() const
Determines the state of readiness of the writer.
Definition: HostXml.h:800
void(* WriteAttributeString)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this, const char *in_rcsAttribute, const char *in_rcsValue)
Adds an attribute to the current node.
Definition: HostXml.h:470
AK::Wwise::Plugin::XmlNodeType::NodeType GetNodeType() const
Returns the type of the current node being read.
Definition: HostXml.h:577
@ k_interfaceVersion
The interface version, as requested by this plug-in.
Definition: HostXml.h:779
void ReadOuterXml(const char *&out_csXml)
Reads the Element or Attribute as a string, including markup. Increments the pointer.
Definition: HostXml.h:735
API interface for XML-based plug-in persistence.
Definition: HostXml.h:146
bool Read()
Sets the reading pointer to the next node, recursively.
Definition: HostXml.h:677
@ ErrorUnknown
Unknown error.
Definition: HostXml.h:105
void(* WriteString)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this, const char *in_rcsValue)
Appends a string as value to the current node.
Definition: HostXml.h:482
V1::XmlWriter XmlWriter
Latest version of the C++ XmlWriter interface.
Definition: HostXml.h:937
Wwise Authoring Plug-ins - C++ class helper to automatically determine the plug-in interfaces used in...
@ k_interfaceType
The interface type, as requested by this plug-in.
Definition: HostXml.h:543
V1::XmlReader XmlReader
Latest version of the C++ XmlReader interface.
Definition: HostXml.h:935
bool IsEOF() const
Tests whether the end of file is reached while reading the XML.
Definition: HostXml.h:616
int GetLinePosition() const
Retrieves the column in the line that contains the start of the current node being read.
Definition: HostXml.h:634
PluginInfoGenerator: Associates an existing C Interface with a variable that can be used....
void(* WriteEndElement)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this)
Closes the previous node.
Definition: HostXml.h:461
@ Attribute
Attribute.
Definition: HostXml.h:87
bool IsEmptyElement() const
Tests whether the current node being read is empty.
Definition: HostXml.h:584
void(* ReadOuterXml)(struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this, const char **out_csXml)
Reads the Element or Attribute as a string, including markup. Increments the pointer.
Definition: HostXml.h:350
bool(* IsEmptyElement)(const struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Tests whether the current node being read is empty.
Definition: HostXml.h:190
API interface for XML-based plug-in persistence.
Definition: HostXml.h:531
WriteReady
Possible error codes when writing XML.
Definition: HostXml.h:101
std::underlying_type< InterfaceType >::type InterfaceTypeValue
PluginInfoGenerator: Underlying storage type for the m_interface value in BaseInterface.
void WriteCData(const char *in_rcsValue)
Appends a raw CDATA string as value to the current node.
Definition: HostXml.h:877
int(* GetLineNumber)(const struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Retrieves the line number that contains the start of the current node being read.
Definition: HostXml.h:234
void(* WriteRaw)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this, const char *in_rcsValue)
Appends a raw string at this precise point of the XML file.
Definition: HostXml.h:508
@ k_interfaceType
The interface type, as requested by this plug-in.
Definition: HostXml.h:769
const char *(* GetName)(const struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Returns the name of the current node being read.
Definition: HostXml.h:171
void WriteString(const char *in_rcsValue)
Appends a string as value to the current node.
Definition: HostXml.h:868
void(* WriteStartDocument)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this)
Starts a new XML document.
Definition: HostXml.h:429
void WriteStartElement(const char *in_rcsElementName, AK::Wwise::Plugin::XmlElementType::ElementType in_eType)
Creates a new inner node.
Definition: HostXml.h:848
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_VERSION(AudioPlugin)
#define AK_WWISE_PLUGIN_SPECIALIZE_HOST_INTERFACE_NO_BASE_INSTANCE(in_name, in_varname)
PluginInfoGenerator: Creates a C++ host specialization for interface class specified in in_name.
Use this class to handle the WriteStartElement/WriteEndElement pair automatically in a C++ scope.
Definition: HostXml.h:890
ElementType
These element types have an impact when outputting in alternate formats such as JSON.
Definition: HostXml.h:113
void(* WriteEndDocument)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this)
Ends a completed XML document.
Definition: HostXml.h:439
Interface description and base class for every Wwise Authoring plug-in interface.
Base host-provided instance type for reading XML files through ak_wwise_plugin_host_xml_v1.
Definition: PluginDef.h:662
bool(* GetAttribute)(struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this, const char *in_rcsAttributeName, const char **out_rcsValue)
Reads the value of a particular attribute under the current node.
Definition: HostXml.h:369
AutoStartEndElement(const char *in_rcsElementName, XmlWriter &in_pWriter, AK::Wwise::Plugin::XmlElementType::ElementType in_eType=AK::Wwise::Plugin::XmlElementType::Map)
Definition: HostXml.h:900
const char * ReadElementString()
Reads simple text-only elements, and increments the pointer.
Definition: HostXml.h:699
ak_wwise_plugin_host_xml_v1 CHostXml
Definition: HostXml.h:527
void WriteEndElement()
Closes the previous node.
Definition: HostXml.h:853
void Skip()
Sets the reading pointer past the current node, skipping any inner content.
Definition: HostXml.h:742
const char *(* ReadElementString)(struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Reads simple text-only elements, and increments the pointer.
Definition: HostXml.h:312
const char *(* GetValue)(const struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Returns the value of the current node being read.
Definition: HostXml.h:213
@ ErrorPathTooLong
Path exceeds max length.
Definition: HostXml.h:103
bool(* Append)(struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_this, struct ak_wwise_plugin_host_xml_writer_instance_v1 *in_pWriterToAppend)
Appending a first XML writer to a second XML writer.
Definition: HostXml.h:408
#define MKBOOL(cond)
Definition: PluginHelpers.h:75
void(* Skip)(struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Sets the reading pointer past the current node, skipping any inner content.
Definition: HostXml.h:358
API interface for XML-based plug-in persistence.
Definition: HostXml.h:757
Base host-provided instance type for writing XML files through ak_wwise_plugin_host_xml_v1.
Definition: PluginDef.h:671
WhiteSpaceHandling
See MSDN documentation.
Definition: HostXml.h:48
AK::Wwise::Plugin::XmlNodeType::NodeType(* GetNodeType)(const struct ak_wwise_plugin_host_xml_reader_instance_v1 *in_this)
Returns the type of the current node being read.
Definition: HostXml.h:182
bool IsReady() const
Determines if the writer is ready to be used.
Definition: HostXml.h:790
bool Append(XmlWriter &in_writerToAppend)
Appending a first XML writer to a second XML writer.
Definition: HostXml.h:811
~AutoStartEndElement()
Calls WriteEndElement automatically.
Definition: HostXml.h:907
AK_WWISE_PLUGIN_SPECIALIZE_INTERFACE_CLASS(AudioPlugin)
WriteState
WriteState.
Definition: HostXml.h:86