first commit

Minecraft.Client/Xbox/Sentient/Include/SenClientXML.h

@@ -0,0 +1,85 @@
+/********************************************************
+*                                                       *
+* Copyright (C) Microsoft. All rights reserved.         *
+*                                                       *
+********************************************************/
+
+// Sentient Client XML API
+//
+// Include this to get access to all XML Sentient features.
+
+#pragma once
+
+#include "SenClientTypes.h"
+
+
+namespace Sentient
+{
+	//======================//
+	//                      //
+	//    XML Data Types    //
+	//                      //
+	//======================//
+
+	/// @brief           An easy-to-access pre-parsed XML.
+	///
+	/// @details         This holds some easily-traversible, easily-searchible representations
+	///                  of the content of a raw UTF-8 XML buffer.
+	///
+	/// @related         SenXMLParse()
+	/// @related         SenXMLDestroy()
+	///
+	struct SenXML
+	{
+		void *reserved;
+	};
+
+
+	//=====================//
+	//                     //
+	//    XML Functions    //
+	//                     //
+	//=====================//
+
+	/// @brief           Parse a raw UTF-8 XML buffer into a more useful format.
+	///
+	/// @param[in]       source
+	///                  The raw UTF-8 XML buffer to be parsed.
+	///
+	/// @param[out]      out_senXML
+	///                  The (private) object to hold the parsed data.
+	///
+	/// @return          Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.  Specific values include:
+	///                  E_POINTER: Bad pointer to the raw XML buffer.
+	///                  E_OUTOFMEMORY: Couldn't parse due to lack of memory.
+	///                  E_FAIL: Failed to parse for unspecified reason.
+	///                  S_OK: Parsed successfully.
+	///
+	/// @details         It is expensive to parse an XML file directly for each attribute fetch.
+	///                  Thus, we pre-parse the whole thing once after (down)loading it and then
+	///                  pass the parsed data to the fetch routines.
+	///
+	/// @related         SenXMLDestroy()
+	///
+	HRESULT SenXMLParse( 
+		const char *source, 
+		SenXML *out_senXML );
+
+	/// @brief           Free the resources/memory associated with a parsed XML file.
+	///
+	/// @param[in]       senXML
+	///                  The (private) object holding the parsed data to be freed.
+	///
+	/// @return          Check SUCCEEDED( hresult ) or FAILED( hresult ) to determine success.  Specific values include:
+	///                  E_INVALIDARG: senXML is not a parsed XML.
+	///                  S_OK: Destroyed/freed successfully.
+	///
+	/// @details         A parsed XML takes up some extra memory.  Once done with its contents,
+	///                  you should call this routine to free it up.
+	///
+	/// @related         SenXMLParse()
+	///
+	HRESULT SenXMLDestroy( 
+		SenXML &senXML );
+
+} // namespace Sentient