[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/vutil/typehelper.hh

Go to the documentation of this file.

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

    Copyright (C) 2001-2003 Peter Amstutz <http://www.interreality.org>

    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 _TYPEHELPER_HH_
#define _TYPEHELPER_HH_

#include <vos/vutil/vutildefs.hh>

#include <list>
#include <deque>
#include <set>
#include <string>
#include <stdexcept>

/**
 * @defgroup libtypehelper libtypehelper
 *  Portable Type Helper-Application Abstraction Library
 */

/** Use a subclass of this class to specify action performed when a running
 * helper process ends by passing an instance to TypeHeler::addProcessEndCallback().
 * @ingroup libtypehelper
 */
class VUTIL_API ProcessEndCallback
{
public:
    virtual ~ProcessEndCallback() { }
    /// Override this method.
    virtual void notifyProcessTerminate(int pid) = 0;
};

/** A ProcessEndCallback that deletes a file when called.
 * @ingroup libtypehelper
 */
class VUTIL_API DeleteTempFile : public ProcessEndCallback
{
private:
    std::string file;
    std::set<int>* other_pids;
public:
    /** Deletes a file when called back.
     * @param f     The name of the file to delete.
     */
    DeleteTempFile(const std::string& f);

    /** Removes the PID for the helper associated with this callback from
     * the given set of PIDs. If that set is then empty, then the file
     * is deleted and the PID set is freed from the heap.
     * Use a new instance of DeleteTempFile for each process, and pass each of
     * them a pointer to the PID set.
     * @param f         File to delete when the PID set becomes empty.
     * @param pidset    The PID set. If NULL, then behavior will be as described
     *                  in DeleteTempFile(const std::string&).
     */
    DeleteTempFile(const std::string& f, std::set<int>* pidset);

    virtual ~DeleteTempFile();
    virtual void notifyProcessTerminate(int pid);
};

/** @class TypeHelper typehelper.hh typehelper/typehelper.hh
  * @ingroup libtypehelper
  *
  * This class represents a helper program.  It also contains static
  * information on all type helpers, which you can access with
  * findVobjectHelpers, findDataHelpers, addHelper, etc.
  *
  * This utility does not require VOS, but it includes special features
  * to facilitate VOS applications.
  */
class VUTIL_API TypeHelper {
public:
    typedef enum { DATA, VOBJECT } RunFunc;

private:
    std::string type;
    std::deque<std::string> parameters;
    std::string target;
    RunFunc runFunc;

public:

    /** Create a new typehelper for Data with no associated type identifier */
    TypeHelper() :
        runFunc(DATA)
    { }

    /** Create a new typehelper for Data with the givent type identifier */
    TypeHelper(std::string init_type) :
        type(init_type),
        runFunc(DATA)
    { }

    /** Create a new typehelper
        @param init_type    Type of data or Vobject
        @param vobject_or_data  DATA or VOBJECT
        @param init_target       Temporary file if DATA, URL if VOBJECT.
    */
    TypeHelper(std::string init_type, RunFunc vobject_or_data, std::string init_target ) :
        type(init_type),
        target(init_target),
        runFunc(vobject_or_data)
    { }


    /** Load helpers configuration from a config file.
        @param filename Name of the configuration file
        @todo load multiple filenames, including a default
             ~/.typehelpers.cfg and INSTALL_DIR/etc/typehelpers.cfg
            as well as the given filename.
        @throw std::runtime_error if there is an error opening the file
    */
    static void init(std::string filename);

    /** Find helpers that can handle a VOS Vobject with one of the given types.
        @return List of helpers, in the order in which they were found
                in configuration files.
        @param types If a helper is known that can handle one of these types,
                it is added to the return set.
        @param objpath URL to pass to the helper when run.
    */
    static std::deque<TypeHelper> findVobjectHelpers(const std::set<std::string>& types,
const std::string& objpath);

    /** Find helpers that can handle data with the given type. Typically
      * this is a MIME type (e.g. "audio/mpeg").  Information loaded from
      * a config file by init() will be used, as well as Gnome handlers
      * if libtypehelper was linked against Gnome libraries.

        @return List of matching helpers, in the order in which they were
                found in configuration files and platform config.
        @param type Type identifier, typically a MIME type.
        @param tempfile Name of a file to use for temporary storage, if
                one of the matching helpers needs one. (
        @todo make tempfile optional and figure out our own according to
                platform policies
    */
    static std::deque<TypeHelper> findDataHelpers(const std::string& type, const
std::string& tempfile);

    /** Add a helper to the static list of helpers.
        @param configline A string in one of these 2 forms:
            <ul>
                <li>For "Data" helpers: <code>data(</code>type<code>) = </code> command</li>
                <li>For "Vobject helpers: <code>vobject(</code>type<code>) = </code> command</li>
            </ul>

            You can use the following special character sequences in <i>command</i>:
            <dl>
                <dt><code>%f</code></dt>
                    <dd>(Data helpers only) Make a temporary file, and replace <code>%f</code> with its name</dd>
                <dt><code>%d</code></dt>
                    <dd>(Data helpers only) Replace <code>%d</code> with the data.</dd>
                <dt><code>%u</code></dt>
                    <dd>(Vobject helpers only) Replace <code>%u</code> with the URL of the starting object.</dd>
            </dl>
    */
    static void addHelper(const std::string& configline);

    /** When checkProcesses sees that a process has ended, call
        the supplied callback function.
        @see removeProcessEndCallback
        @see checkProcesses
    */
    static void addProcessEndCallback(int pid, ProcessEndCallback* pec);

    /** Remove a process-end callback.
        @see addProcessEndCallback
    */
    static void removeProcessEndCallback(int pid, ProcessEndCallback* pec);

    /** If a process associated with a process-end callback has ended,
        then call the callback and remove the callback.
        @see addProcessEndCallback
    */
    static void checkProcesses();

    /** What is the type for this helper? */
    std::string getType() { return type; }

    /** What are the command-line paramaters that will be passed to this
        helper?
    */
    const std::deque<std::string>& getParameters() { return parameters; }

    /** What is the full command line that will be run
        for this helper?
    */
    std::string getCommand();

    /** Run this helper.
        @return PID (Process ID) of the child process.
    */
    int run();

    /** Set the type for this helper */
    void setType(std::string t) { type = t; }

    /** Set the individual command-line parameters for this helper.
        params[0] is the command to run, etc. */
    void setParameters(std::deque<std::string> params) { parameters = params; }

    /** Set the full command line for this helper: it will be broken into
        individual arguments on spaces and tabs.
    */
    void setCommand(const std::string& cmd);
};


#endif