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

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