added limited support for COLLADA_DOM. Will need to add jam/msvcgen build support.
This commit is contained in:
ejcoumans
487
Extras/COLLADA_DOM/include/dae/daeURI.h
Normal file
487
Extras/COLLADA_DOM/include/dae/daeURI.h
Normal file
@@ -0,0 +1,487 @@
|
||||
/*
|
||||
* Copyright 2006 Sony Computer Entertainment Inc.
|
||||
*
|
||||
* Licensed under the SCEA Shared Source License, Version 1.0 (the "License"); you may not use this
|
||||
* file except in compliance with the License. You may obtain a copy of the License at:
|
||||
* http://research.scea.com/scea_shared_source_license.html
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software distributed under the License
|
||||
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
* implied. See the License for the specific language governing permissions and limitations under the
|
||||
* License.
|
||||
*/
|
||||
|
||||
#ifndef __DAE_URI_H__
|
||||
#define __DAE_URI_H__
|
||||
|
||||
#include <dae/daeTypes.h>
|
||||
#include <dae/daeElement.h>
|
||||
|
||||
/**
|
||||
* The @c daeURI is a simple class designed to aid in the parsing and resolution
|
||||
* of URI references inside COLLADA elements.
|
||||
* A @c daeURI is created for every @c anyURL and @c IDREF in the COLLADA schema.
|
||||
* For example, the <instance> element has the url= attribute of type @c anyURL, and the
|
||||
* <controller> element has the target= attribute of type @c IDREF.
|
||||
* The @c daeURI class contains a URI string; the @c setURI() method breaks the string into
|
||||
* its components including protocol, authority, path (directory), and ID.
|
||||
* It also has the capability to attempt to resolve this reference
|
||||
* into a @c daeElement, through the method @c resolveElement().
|
||||
* If a @c daeURI is stored within a @c daeElement, it fills
|
||||
* its container field to point to the containing element.
|
||||
*
|
||||
* The main API on the @c daeURI, @c resolveElement(), uses a @c daeURIResolver
|
||||
* to search for the @c daeElement inside a @c daeDatabase.
|
||||
*
|
||||
* URIs are resolved hierarchically, where each URI is resolved based on
|
||||
* the following criteria via itself and its element's base URI, which represents the
|
||||
* URI of the document that contains the element, retrieved by
|
||||
* <tt>daeElement::getBaseURI().</tt>
|
||||
* If no base URI is provided, then the application URI
|
||||
* is used as a base.
|
||||
*
|
||||
* The URI resolution order for the COLLADA DOM is as follows:
|
||||
* - Absolute URI is specified (see definition below):
|
||||
* The URI ignores its parent/base URI when validating.
|
||||
* - Relative URI is specified:
|
||||
* The URI uses the base URI to provide the protocol, authority, and base path.
|
||||
* This URI's path is appended to the path given the the base URI.
|
||||
* This URI's file and ID are used.
|
||||
* - Each level of URI is resolved in this way against the base URI of the
|
||||
* containing file until the top level is reached. Then the application URI
|
||||
* is used as the default.
|
||||
*
|
||||
* <b>Definition of Absolute URI:</b>
|
||||
* For the purposes of the COLLADA DOM, a URI is considered absolute
|
||||
* if it starts by specifying a protocol.
|
||||
* For example,
|
||||
* - file://c:/data/foo.dae#myScene is an absolute URI.
|
||||
* - foo.dae#myScene is relative.
|
||||
* - foo.dae is a top-level file reference and is relative.
|
||||
* If the URI does not include a pound sign (#), the <tt><i>id</i></tt> is empty.
|
||||
*/
|
||||
class daeURI
|
||||
{
|
||||
private:
|
||||
void internalSetURI(daeString uri);
|
||||
|
||||
public:
|
||||
/**
|
||||
* An enum describing the status of the URI resolution process.
|
||||
*/
|
||||
enum ResolveState{
|
||||
/** No URI specified */
|
||||
uri_empty,
|
||||
/** URI specified but unresolved */
|
||||
uri_loaded,
|
||||
/** Resolution pending */
|
||||
uri_pending,
|
||||
/** Resolution successful */
|
||||
uri_success,
|
||||
/** Failure due to unsupported URI scheme */
|
||||
uri_failed_unsupported_protocol,
|
||||
/** Failure because the file was not found */
|
||||
uri_failed_file_not_found,
|
||||
/** Failure because the ID was not found */
|
||||
uri_failed_id_not_found,
|
||||
/** Failure due to an invalid ID */
|
||||
uri_failed_invalid_id,
|
||||
/** A flag specifying that the URI should be resolved locally to its own document */
|
||||
uri_resolve_local,
|
||||
/** A flag specifying that the URI should be resolved using this relative URI */
|
||||
uri_resolve_relative,
|
||||
/** A flag specifying that the URI should be resolved using this absolute URI */
|
||||
uri_resolve_absolute,
|
||||
/** Failure due to an invalid reference */
|
||||
uri_failed_invalid_reference,
|
||||
/** Failure due to an external error */
|
||||
uri_failed_externalization,
|
||||
/** Failure due to missing document */
|
||||
uri_failed_missing_container,
|
||||
/** Failure because autmoatic loading of a document is turned off */
|
||||
uri_failed_external_document
|
||||
};
|
||||
|
||||
private:
|
||||
/** Resolved version of the URI */
|
||||
daeString uriString;
|
||||
|
||||
/** Original URI before resolution */
|
||||
daeString originalURIString;
|
||||
|
||||
// Parceled out of storage as const char*'s
|
||||
/** Protocol substring parsed from the URI */
|
||||
daeString protocol;
|
||||
/** authority substring parsed from the URI */
|
||||
daeString authority;
|
||||
/** Path substring parsed from the URI */
|
||||
daeString filepath;
|
||||
/** File name substring parsed from the URI */
|
||||
daeString file;
|
||||
/** Id substring parsed from the URI */
|
||||
daeString id;
|
||||
/** Extension parsed from the filename in the URI */
|
||||
daeString extension;
|
||||
/** Reference to the element that the URI resolves to in memory */
|
||||
daeElementRef element;
|
||||
/** Pointer to the element that owns this URI */
|
||||
daeElement* container;
|
||||
/** Current resolver state of the URI */
|
||||
ResolveState state;
|
||||
/** Flag for if this URI references an external element. */
|
||||
daeBool external;
|
||||
|
||||
public:
|
||||
/**
|
||||
* Constructs a daeURI object that contains no URI reference.
|
||||
*/
|
||||
daeURI();
|
||||
/**
|
||||
* Destructor
|
||||
*/
|
||||
~daeURI();
|
||||
|
||||
/**
|
||||
* Constructs a daeURI object that points to the application's current working
|
||||
* directory.
|
||||
* @param dummy An integer value that has no meaning.
|
||||
* @note This is used only to initialize the Application URI. It's a simple
|
||||
* workaround to insure that the ApplicationURI is initialized only once and before the user can call
|
||||
* daeURI::setBaseURI() (so when we initialize ApplicationURI there is no chance of wiping out a user value).
|
||||
*/
|
||||
daeURI(int dummy);
|
||||
|
||||
/**
|
||||
* Constructs a daeURI object from a URI passed in as a string.
|
||||
* @param URIString Passed to setURI() automatically.
|
||||
* @param nofrag If true, the fragment part of the URI is stripped off before construction.
|
||||
*/
|
||||
daeURI(daeString URIString, daeBool nofrag = false);
|
||||
|
||||
/**
|
||||
* Constructs a daeURI object using a <tt><i>baseURI</i></tt> and a <tt><i>uriString.</i></tt>
|
||||
* Calls setURI(URIString), and @c validate(baseURI).
|
||||
* @param baseURI Base URI to resolve against.
|
||||
* @param URIString String designating this URI.
|
||||
*/
|
||||
daeURI(daeURI& baseURI, daeString URIString);
|
||||
|
||||
/**
|
||||
* Constructs a daeURI object based on a simple copy from an existing @c daeURI.
|
||||
* @param constructFromURI URI to copy into this one.
|
||||
*/
|
||||
daeURI(daeURI& constructFromURI);
|
||||
|
||||
/**
|
||||
* Gets the ID string parsed from the URI.
|
||||
* @return Returns a pointer to the string.
|
||||
*/
|
||||
inline daeString getID(){return(id);};
|
||||
|
||||
/**
|
||||
* Gets the file string parsed from the URI.
|
||||
* @return Returns a pointer to the string.
|
||||
*/
|
||||
inline daeString getFile(){return(file);};
|
||||
|
||||
/**
|
||||
* Gets the path string to the file, without the path name, parsed from the URI.
|
||||
* @return Returns a pointer to the string.
|
||||
*/
|
||||
inline daeString getFilepath(){return(filepath);};
|
||||
|
||||
/**
|
||||
* Gets the protocol string parsed from the URI.
|
||||
* @return Returns a pointer to the string.
|
||||
*/
|
||||
inline daeString getProtocol(){return(protocol);};
|
||||
|
||||
/**
|
||||
* Gets the authority string parsed from the URI.
|
||||
* @return Returns a pointer to the string.
|
||||
*/
|
||||
inline daeString getAuthority(){return(authority);};
|
||||
|
||||
/**
|
||||
* Gets the extension string parsed from the URI.
|
||||
* @return Returns a pointer to the string.
|
||||
*/
|
||||
inline daeString getExtension(){return(extension);};
|
||||
|
||||
/**
|
||||
* Gets the element that this URI resolves to in memory.
|
||||
* @return Returns a ref to the element.
|
||||
*/
|
||||
inline daeElementRef getElement(){return(element);};
|
||||
|
||||
/**
|
||||
* Gets the element that this URI resolves to in memory.
|
||||
* @return Returns a ref to the element.
|
||||
*/
|
||||
inline daeElementConstRef getElement() const {return(element);};
|
||||
|
||||
/**
|
||||
* Sets the element that this URI resolves to in memory.
|
||||
* @param newref A ref to the element.
|
||||
*/
|
||||
inline void setElement(daeElementRef newref){element=newref;};
|
||||
|
||||
/**
|
||||
* Gets the resolve state of the URI.
|
||||
* @return Returns the current state.
|
||||
* @note This will be removed when daeURI starts managing its state internally.
|
||||
*/
|
||||
inline ResolveState getState() const {return(state);};
|
||||
|
||||
/**
|
||||
* Sets the resolve state of the URI.
|
||||
* @param newState The new state.
|
||||
* @note This will be removed when daeURI starts managing its state internally.
|
||||
*/
|
||||
inline void setState(ResolveState newState){state=newState;};
|
||||
|
||||
/**
|
||||
* Gets a pointer to the @c daeElement that contains this URI.
|
||||
* @return Returns the pointer to the containing daeElmement.
|
||||
*/
|
||||
inline daeElement* getContainer() const {return(container);};
|
||||
|
||||
/**
|
||||
* Sets the pointer to the @c daeElement that contains this URI.
|
||||
* @param element Pointer to the containing @c daeElmement.
|
||||
*/
|
||||
inline void setContainer(daeElement* element){container=element;};
|
||||
|
||||
/**
|
||||
* Copies parameter <tt><i>uri</i></tt> into data member <tt><i>uriString,</i></tt> and then decomposes each of
|
||||
* <tt><i>protocol, authority, filepath, file,</i></tt> and <tt><i>id.</i></tt>
|
||||
* After @c setURI(), the <tt><i>state</i></tt> is set to @c uri_loaded.
|
||||
* @param uri String to use to configure this URI.
|
||||
*/
|
||||
void setURI(daeString uri);
|
||||
|
||||
/**
|
||||
* Gets the URI stored in the daeURI.
|
||||
* @return Returns the full URI String, from <tt><i>uriString.</i></tt>
|
||||
*/
|
||||
daeString getURI() const;
|
||||
|
||||
/**
|
||||
* Gets the original URI String as originally set, not flattened against the base URI.
|
||||
* @return Returns the original URI String as originally set, not flattened against the base URI.
|
||||
*/
|
||||
daeString getOriginalURI() const;
|
||||
|
||||
/**
|
||||
* Gets if this URI resolves to an element that is not contained in the same document as the URI.
|
||||
* @return Returns true if the URI references an external element. False otherwise.
|
||||
*/
|
||||
daeBool isExternalReference() const { return external; }
|
||||
|
||||
/**
|
||||
* Uses the @c daeURIResolver static API to try to resolve this URI
|
||||
* into a @c daeElement reference, placing the resolved element into <tt><i>element.</i></tt>
|
||||
* This function can effectively force a load of a file, perform
|
||||
* a database query, and so on, based on the @c daeURIResolver plugins implemented.
|
||||
*/
|
||||
void resolveElement(daeString typeNameHint = NULL);
|
||||
|
||||
/**
|
||||
* Configures the <tt><i>uriString</i></tt> for this @c daeURI based on the element set in <tt><i>element.</i></tt>
|
||||
* Uses the element's base URI and ID information to configure
|
||||
* the URI string.
|
||||
*/
|
||||
void resolveURI();
|
||||
|
||||
/**
|
||||
* Flattens this URI with base URI to obtain a useable
|
||||
* complete URI for resolution.
|
||||
* @param baseURI Base URI to flatten against if this URI is
|
||||
* relative.
|
||||
* @note After @c validate(), state is @c uri_pending as it is awaiting a call to
|
||||
* @c resolveElement().
|
||||
*/
|
||||
void validate(daeURI* baseURI = NULL);
|
||||
|
||||
/**
|
||||
* Copies the URI specified in <tt><i>from</i></tt> into @c this.
|
||||
* Performs a simple copy without validating the URI.
|
||||
* @param from URI to copy from.
|
||||
*/
|
||||
void copyFrom(daeURI& from);
|
||||
|
||||
/**
|
||||
* Outputs all components of this URI to stderr.
|
||||
* Useful for debugging URIs, this outputs each part of the URI separately.
|
||||
*/
|
||||
void print();
|
||||
|
||||
/**
|
||||
* Makes the "originalURI" in this URI relative to some other uri
|
||||
* @param uri the URI to make "this" relative to.
|
||||
* @note this is experimental and not fully tested, please don't use in critical code yet.
|
||||
*/
|
||||
int daeURI::makeRelativeTo(daeURI* uri);
|
||||
|
||||
/**
|
||||
* Comparison operator.
|
||||
* @return Returns true if URI's are equal.
|
||||
*/
|
||||
inline bool operator==(const daeURI& other) const{
|
||||
return (!strcmp(other.getURI(), getURI())); }
|
||||
|
||||
private:
|
||||
/**
|
||||
* Resets this URI; frees all string references
|
||||
* and returns <tt><i>state</i></tt> to @c empty.
|
||||
*/
|
||||
void reset();
|
||||
|
||||
/**
|
||||
* Provides a shared initialization for all constructors
|
||||
*/
|
||||
void initialize();
|
||||
public:
|
||||
/**
|
||||
* Gets the path part of the URI, including everything from immediately after the authority up to and
|
||||
* including the file name, but not the query or fragment.
|
||||
* @param dest The user allocated buffer that will receive the path.
|
||||
* @param size The size of the buffer.
|
||||
* @return Returns true for success, false if the path exceeded the size of the user provided buffer.
|
||||
*/
|
||||
daeBool getPath(daeChar *dest, daeInt size);
|
||||
|
||||
public:
|
||||
/**
|
||||
* Sets the application's default base URI. This is effectively the default protocol,
|
||||
* authority, and path in the case of top-level relative URIs.
|
||||
* @param uri Base URI to use as the default application URI.
|
||||
*/
|
||||
static void setBaseURI(daeURI& uri);
|
||||
|
||||
/**
|
||||
* Gets the application's default base URI.
|
||||
* @return Returns the base URI used in the case of top-level relative URIs.
|
||||
*/
|
||||
static daeURI* getBaseURI();
|
||||
|
||||
/**
|
||||
* Performs RFC2396 path normalization.
|
||||
* @param path Path to be normalized.
|
||||
*/
|
||||
static void normalizeURIPath(char *path);
|
||||
|
||||
};
|
||||
|
||||
class daeURIResolver;
|
||||
typedef daeTArray<daeURIResolver*> daeURIResolverPtrArray;
|
||||
|
||||
/**
|
||||
* The @c daeURIResolver class is the plugin point for URI resolution.
|
||||
* This class is an abstract base class that defines an interface for
|
||||
* resolving URIs.
|
||||
* All instances of @c daeURIResolvers are tracked centrally.
|
||||
* Every URI is passed through this list of @c daeURIResolvers for resolution.
|
||||
* Before a @c daeURIResolver receives a URI, the API checks whether it supports
|
||||
* the protocol.
|
||||
* The list is ordered on a first come, first serve basis, and resolution
|
||||
* terminates after any resolver instance resolves the URI.
|
||||
*/
|
||||
class daeURIResolver
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* This base constructor appends @c this to KnownResolvers list.
|
||||
*/
|
||||
daeURIResolver();
|
||||
|
||||
/**
|
||||
* Destructor
|
||||
*/
|
||||
virtual ~daeURIResolver();
|
||||
|
||||
protected:
|
||||
static daeURIResolverPtrArray _KnownResolvers;
|
||||
|
||||
static daeBool _loadExternalDocuments;
|
||||
|
||||
public:
|
||||
/**
|
||||
* Iterates through known resolvers
|
||||
* calling @c isProtocolSupported() and, if it is supported, calling
|
||||
* @c resolveElement().
|
||||
* @param uri @c daeURI to resolve.
|
||||
*/
|
||||
static void attemptResolveElement(daeURI &uri, daeString typeNameHint = NULL);
|
||||
|
||||
/**
|
||||
* Iterates through known resolvers
|
||||
* calling @c isProtocolSupported() and, if it is supported, calling
|
||||
* @c resolveURI().
|
||||
* @param uri @c daeURI to resolve.
|
||||
*/
|
||||
static void attemptResolveURI(daeURI &uri);
|
||||
|
||||
/**
|
||||
* Sets a flag that tells the URI resolver whether or not to load a separate document if a URI
|
||||
* being resolved points to one.
|
||||
* @param load Set to true if you want the URI Resolver to automatically load other documents to
|
||||
* resolve URIs.
|
||||
*/
|
||||
static void setAutoLoadExternalDocuments( daeBool load ) { _loadExternalDocuments = load; }
|
||||
|
||||
/**
|
||||
* Gets a flag that tells if the URI resolver is set to load an external document if a URI
|
||||
* being resolved points to one.
|
||||
* @return Returns true if the resolver will automatically load documents to resolve a URI.
|
||||
* False otherwise.
|
||||
*/
|
||||
static daeBool getAutoLoadExternalDocuments() { return _loadExternalDocuments; }
|
||||
|
||||
public: // Abstract Interface
|
||||
/**
|
||||
* Provides an abstract interface for converting a @c daeURI into a @c daeElement
|
||||
* @param uri @c daeURI to resolve.
|
||||
* @return Returns true if the @c daeURIResolver successfully resolved the URI,
|
||||
* returns false otherwise.
|
||||
*/
|
||||
virtual daeBool resolveElement(daeURI& uri, daeString typeNameHint = NULL) = 0;
|
||||
/**
|
||||
* Provides an abstract interface for converting a @c daeElement into a @c daeURI
|
||||
* @param uri @c daeURI to resolve.
|
||||
* @return Returns true if the @c daeURIResolver successfully resolved the element
|
||||
* into a URI, returns false otherwise.
|
||||
*/
|
||||
virtual daeBool resolveURI(daeURI& uri) = 0;
|
||||
|
||||
/**
|
||||
* Gets the name of this resolver.
|
||||
* @return Returns the resolver name as a string.
|
||||
*/
|
||||
virtual daeString getName() = 0;
|
||||
|
||||
/**
|
||||
* Determines whether this resolver supports a particular protocol
|
||||
* for resolution.
|
||||
* @param protocol Determine whether the resolver supports this protocol.
|
||||
* @return Returns true if this @c daeURIResolver understands how to resolve using this protocol, returns
|
||||
* false otherwise
|
||||
*/
|
||||
virtual daeBool isProtocolSupported(daeString protocol) = 0;
|
||||
|
||||
/**
|
||||
* Determines whether this resolver supports the given extension.
|
||||
* This keeps parsers from trying to process incompatible
|
||||
* file formats.
|
||||
* @param extension Extension string found after the '.' in the file name.
|
||||
* @return Returns true if the given extension is supported, returns false otherwise.
|
||||
*/
|
||||
virtual daeBool isExtensionSupported(daeString extension) = 0;
|
||||
|
||||
};
|
||||
|
||||
|
||||
#endif //__DAE_URI_H__
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user