Home | History | Annotate | Download | only in dae 
      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>
     15 class daeDatabase;
     16 class daeMetaElement;
     17 class daeURI;
     18 class 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 */
     25 class DLLSPEC daeIOPlugin
     26 {
     27 public:
     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 
    110 protected:
    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 
    117 class DLLSPEC daeIOEmpty : public daeIOPlugin {
    118 public:
    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