vos/corelibs/typechain/typechain.hh

Go to the documentation of this file.

/* $Id: typechain.hh,v 1.33 2003/07/24 17:37:44 tetron Exp $ */

/*

    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001, 2002,2002 Reed Hedges <reed@zerohour.net>

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
*/

#ifndef _TYPECHAIN_HH_
#define _TYPECHAIN_HH_

#if defined(_WIN32) && defined(_MSC_VER)
# ifdef TYPECHAIN_EXPORTS
#  define TYPECHAIN_API __declspec(dllexport)
# else
#  define TYPECHAIN_API __declspec(dllimport)
# endif
#else
# define TYPECHAIN_API
#endif

#include <string>
#include <map>
#include <queue>
#include <stdexcept>

using namespace std;

#define TYPECHAIN_DELIMS    ";:|"   // Typechain delimiters as described in typechian documentation.



#if !defined(TC_PLUGIN_DIR)
#define TC_PLUGIN_DIR   "/usr/local/lib/typehandlers"
#endif

class TypeHandler;

/** This class helps you decode data with known encodings. Use it's static methods for registering
    and unregistering type/encoding handlers (TypeHandler),  and for processing data according
    to typechain identifiers.
    Typechain is described in more detail in the Virtual Object System manual (see 
            http://interreality.org/doc/manual/html)
    @todo encoding
    @todo methods that operate on streams
    @todo support "?" (unknown type): if type is unknown (no type identifier given), attempt to find
        a magic number or otherwise guess the datatype, and re-decode until next type in typestring
        (or an unknown type) is reached.
    @see TypeHandler
    @author Reed Hedges <reed@zerohour.net> February, 2002
*/
class TYPECHAIN_API TypeChain {

public:

    /** Error decoding data */
    class DecodeError : public runtime_error {
    public:
        string type;
        DecodeError(string info, string thetype) : runtime_error(info), type(thetype) { }
        virtual ~DecodeError() throw() { }
    };

    /** Error encoding data */
    class EncodeError : public runtime_error {
    public:
        string type;
        EncodeError(string info, string thetype) : runtime_error(info), type(thetype) { }
        virtual ~EncodeError() throw() { }
    };

    /** the internal handlers list, which is a map<string, TypeHandler*>.
        If a key exists, but the type handler is a PluginPlaceholder, that means that the handler was
        detected as a plugin, but not loaded.
        @note Modify this map at your own risk. There are no garauntees here, especially regarding
        future version compatability.
    */

    static map<string, TypeHandler*> handlers;

    /** internal list of abbreviated type names for filename "extensions" and type
        names: used by guessTypeFromFilename().
    */
    static map<string, string> filename_extensions;

    /** Initialize plugins. Scans the plugins directory and loads (or schedules for later loading)
        dynamically loadable libraries whose names match a certain form.
        The plugin libraries should be named like this:
        Plugins should have a void function with no arguments named plugin_init(), which should call
        TypeChain::registerHandler().

        @bug On Mac OSX: crashes if there are any files in the plugins directory that are not MH_BUNDLE files.

    */
    static void initialize();


    /** Initialize plugins.
        @param dirname,... search these directories for plugins as well as standard location. terminate list with 0.
        @see initialize();
        @bug On Mac OSX: crashes if there are any files in a plugins directory that are not MH_BUNDLE files.
     */
    static void initialize(const char* dirname, ...);

    /** Uninitialize typechain: all handlers are deleted and DLL's are closed. */
    static void uninitialize();


    /** Decode data (stored in a string) according to a type identifier.
        For each unit in the type identifier, the first type handler in the handlers list is
        @param data Reference to the data being processed: will be replaced with the new data. (your old data WILL be clobbered!!)
        @param type type identifier. (not clobbered)
        @param params parameters may be passed to and from the handlers using this map.
        @return the new type identifier for the new data.
    */

    static string decode(string& data, const string& type, map<string,string>& params) ;

    /** Decode data, with no params list. */
    static string decode(string& data, const string& type) {
        map<string,string> foo;
        return decode(data, type, foo);
    }


    /** Encode data according to type identifier, analagous to decode.
        @param data Reference to data to encode. it will be replaced by new encoded data.
        @param type type identifier to encode towards.
        @return the new type identifer (ie, should be identical to param type if successful)
        @warning does nothing currently

    */
    static void encode(string& data, const string& type, map<string,string>& params);

    /** Encode data, with no params list. */
    static void encode(string& data, const string& type) {
        map<string,string> foo;
        encode(data, type, foo);
    }

    /** Register a type handler. If it already exists, it will be replaced.
        @param handler  instance of a TypeHandler derivation. don't use the same handler pointer twice: the uninitialize() method will attempt to delete it twice.
    */
    static void registerHandler(TypeHandler* handler);


    /** Unregister a type handler (remove from internal list).
        @return the handler removed (TypeHandler*). You probably want to <code>delete</code> it if you're not going to use it anymore.
        @param type type/encoding identifier.
    */
    static TypeHandler *removeHandler(const string& type);

    /** Unregister a type handler, and also delete it:
        it will be removed from internal list, and the C++ handler object
        will be destroyed with 'delete'.
        @param type type/encoding identifier.
    */
    static void deleteHandler(const string& type);



    /** Guess at the type of a file, given the filename with an abbreviated extension,
        based on currently registered set of type handlers.
    */
    static string guessTypeFromFilename(const string& filename);

    /** Construct useful filename from type */
    static string makeFilename(const string& type, const string& basename);


protected:

public:

    int countEncodings(const string& type); 


};



#endif

---