1/*
2* Copyright 2006 Sony Computer Entertainment Inc.
3*
4* Licensed under the MIT Open Source License, for details please see license.txt or the website
5* http://www.opensource.org/licenses/mit-license.php
6*
7*/
8
9#ifndef __DAE_IOPLUGIN__
10#define __DAE_IOPLUGIN__
11
12#include <string>
13#include <vector>
14#include <dae/daeTypes.h>
15class daeDatabase;
16class daeMetaElement;
17class daeURI;
18class daeDocument;
19
20/**
21* The @c daeIOPlugin class provides the input/output plugin interface, which is
22* the interface between the COLLADA runtime and the backend storage. A native
23* COLLADA XML plugin implementation is provided along with this interface.
24*/
25class DLLSPEC daeIOPlugin
26{
27public:
28	/**
29	* Destructor
30	*/
31	virtual ~daeIOPlugin() {}
32	/**
33	* Sets the top meta object.
34	* Called by @c dae::setIOPlugin() when the IO plugin changes. It passes to this function the
35	* top meta object, which is the root of a
36    * hierarchy of @c daeMetaElement objects. This top meta object is capable of creating
37	* any of the root objects in the DOM tree.
38	* @param topMeta Top meta object to use to create objects to fill the database.
39	* @return Returns DAE_OK if successful, otherwise returns a negative value defined in daeError.h.
40	*/
41	virtual daeInt setMeta(daeMetaElement *topMeta) = 0;
42
43	/** @name Database setup	 */
44	//@{
45	/**
46	* Sets the database to use.
47	* All @c daeIOPlugins use the same interface to the @c daeDatabase,
48	* @c setDatabase() tells the @c daeIOPlugin which @c daeDatabase object it should use
49	* for storage and queries.
50	* @param database Database to set.
51	*/
52	virtual void setDatabase(daeDatabase* database) = 0;
53	//@}
54
55
56	/** @name Operations	 */
57	//@{
58	/**
59	* Imports content into the database from an input.
60	* The input can be a file, a database or another runtime.
61	* @param uri the URI of the COLLADA document to load, not all plugins accept all types of URIs,
62	* check the documentation for the IO plugin you are using.
63	* @param docBuffer A string containing the text of the document to load. This is an optional attribute
64	* and should only be used if the document has already been loaded into memory.
65	* @return Returns DAE_OK if successfully loaded, otherwise returns a negative value defined in daeError.h.
66	* @see @c DAE::load().
67	*/
68	virtual daeInt read(const daeURI& uri, daeString docBuffer) = 0;
69
70	/** @name Operations	 */
71	//@{
72	/**
73	* Writes a specific document to an output.
74	* @param name URI to write the document to, not all IO plugins support all types of URIs
75	* check the documentation for the IO plugin you are using.
76	* @param document Pointer to the document that we're going to write out.
77	* @param replace True if write should overwrite an existing file. False otherwise.
78	* @return Returns DAE_OK if success, a negative value defined in daeError.h otherwise.
79	* @see @c DAE::saveAs()
80	*/
81	virtual daeInt write(const daeURI& name, daeDocument *document, daeBool replace) = 0;
82	//@}
83
84	/**
85	 * Returns a list of the URI protocols that this plugin supports.
86	 * @return Returns a daeArray containing the supported protocols.
87	 */
88	virtual const std::vector<std::string>& getSupportedProtocols() {
89		return supportedProtocols;
90	}
91
92	/**
93	 * setOption allows you to set options for this IOPlugin. Which options a plugin supports is
94	 * dependent on the plugin itself. There is currently no list of options that plugins are
95	 * suggested to implement.
96	 * @param option The option to set.
97	 * @param value The value to set the option.
98	 * @return Returns DAE_OK upon success.
99	 */
100	virtual daeInt setOption( daeString option, daeString value ) = 0;
101
102	/**
103	 * getOption retrieves the value of an option from this IOPlugin. Which options a plugin supports is
104	 * dependent on the plugin itself.
105	 * @param option The option to get.
106	 * @return Returns the string value of the option or NULL if option is not valid.
107	 */
108	virtual daeString getOption( daeString option ) = 0;
109
110protected:
111	// This is an array of the URI protocols supported by this plugin, e.g. "http", "file",
112	// etc. Each plugin should initialize this variable in the constructor.
113	std::vector<std::string> supportedProtocols;
114};
115
116
117class DLLSPEC daeIOEmpty : public daeIOPlugin {
118public:
119	virtual daeInt setMeta(daeMetaElement *topMeta) { return DAE_ERROR; }
120	virtual void setDatabase(daeDatabase* database) { }
121	virtual daeInt read(const daeURI& uri, daeString docBuffer) { return DAE_ERROR; }
122	virtual daeInt write(const daeURI& name, daeDocument *document, daeBool replace) { return DAE_ERROR; }
123	virtual daeInt setOption( daeString option, daeString value ) { return DAE_ERROR; }
124	virtual daeString getOption( daeString option ) { return ""; }
125};
126
127
128#endif // __DAE_IOPLUGIN__
129