vos/metaobjects/misc/talkative.hh

Go to the documentation of this file.

/* $Id: talkative.hh,v 1.30 2003/07/24 05:25:49 tetron Exp $ */


/* This file was generated by otd2cpp.pl, a script for ADR by Reed Hedges <reed@zerohour.net>.

    Copyright (C) 2002 Reed Hedges <reed@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 _TALKATIVE_HH_
#define _TALKATIVE_HH_

#include <time.h>

#include <vos/corelibs/vos/vos.hh>
#include <vos/metaobjects/property/property.hh>


#if defined(_WIN32) && defined(_MSC_VER)
# ifdef MISC_EXPORTS
#  define MISC_API __declspec(dllexport)
# else
#  define MISC_API __declspec(dllimport)
# endif
#else
# define MISC_API
#endif

#define VOS_TALK_NO_VOICE "#f"
#define VOS_TALK_VOICE_DATATYPE "application/x-festival"

class TalkMessage;

/** MetaObject implementing Talkative Object Type.
    This object type facilitates verbal intercommunication in the form of text which may be synthesized as human speech (if possible).
*/


class MISC_API Talkative : public virtual MetaObject
{
private:
    PropertyAccessControl *defaultPropertyAC;

public:

    /** @name Message scope codes */
    //@{

    static const unsigned short UNSPECIFIED;
    static const unsigned short PUBLIC;
    static const unsigned short PRIVATE;
    static const unsigned short AUTO;
    static const unsigned short FROM_APP;   ///<Same as SYSTEM
    static const unsigned short SYSTEM; ///<Same as FROM_APP

    //@}

public:

    /** Constructor */
    Talkative(MetaObject* superobject);

    /** Initialize default property AC (For local Talkative objects only) to &NoPropertyAccessControl::static_ */
    void initialize();

    /** Initialize default property AC (For local Talkative objects only) to given policy */
    void initialize(PropertyAccessControl* ac);

    /** Initialize default property AC (For local Talkative objects only) to given policy */
    inline void setPropertyAccessControl(PropertyAccessControl* ac) {
        initialize(ac);
    }


    /** Return type string ("talkative") */
    const std::string getType();

    /** Register Extenders */
    static void registerExtenders();


    /** @name Access Subobjects (if any)  */
    //@{

    /** Get the value of voice property. */
    std::string get_voice();

    /** Get the datatype of voice property. */
    std::string get_voice_datatype();

    /** Set voice property.
        @param value The new value
        @param datatype The new datatype: if omitted, then the existing datatype will be preserved.
        @param ac    Access control policy for the voice property (Ignored by Remote Talkative objects)
     */
    void set_voice(const std::string& value, const std::string& datatype = "?", PropertyAccessControl* ac = NULL);

    //@}


    /** @name Actuators. User-functions that correspond to message actions. */
//@{

    /** Send a talk message to this object. This message contains text to be spoken or displayed. The "voice" property should be used, to select a voice if applicable.
        @see Talkative::TalkMessage
    */

    virtual void do_say(TalkMessage& msg) = 0;

    /** Contructs a TalkMessage and calls do_say(TalkMessage&)
    @deprecated
    */
    void do_say(const std::string& text, Talkative& sender,
                const unsigned short scope, const int priority = 0,
                const std::string& replynonce = "",
                const std::string& thisnonce = "");

    /** calls do_say(text, sender, UNSPECIFIED, 0, "")
        @deprecated
    */
    void do_say(const std::string& text, Talkative& sender, const std::string& in_reply_to = "") {
        do_say(text, sender, UNSPECIFIED, 0, in_reply_to);
    }

    //@}

};

/** Structure defining a talk message */
class MISC_API TalkMessage {
public:
    std::string text;
    Talkative& sender;
    unsigned short scope;   ///<See scope codes below. Combine multiple codes with |.
    int priority;
    time_t time;  ///< Time message was sent (seconds since midnight, Jan 1 1970, UTC., except -1 means no time available.)
    std::string reply_nonce;  ///< If not empty (""), this is the nonce (message ID) of a previous message to which this one is a reply.
    std::string this_nonce;   ///< If not empty (""), this is the nonce (message ID) of this talk message. Combine with URL of sender to form a unique ID.

    TalkMessage(Talkative& se, std::string t = "",
        unsigned short sc = Talkative::UNSPECIFIED,
        int pr = 0,
        time_t tm = -1, std::string rn = "", std::string tn = "" ) :
        text(t), sender(se), scope(sc), priority(pr), time(tm),
        reply_nonce(rn), this_nonce(tn)
        {   }

};

/** Interface for message listeners.
    @see addTalkListener.
*/
class MISC_API TalkListener {
public:
    /** Override this method to handle talk messages. */
    virtual void notifyTalkMessage(TalkMessage& m) = 0;
};

/** Local version of Talkative. */

class MISC_API LocalTalkative : public virtual Talkative {

private:
    typedef vector<TalkListener*> ListenerList;
    ListenerList listeners;

    /* Which object sent us the last message? (or NULL for none) */
    Talkative* replyto;

    /* What was the nonce of the last message? */
    std::string replynonce;

public:

    /* Constructor */
    LocalTalkative(MetaObject* superobject);

    /* Destructor */
    ~LocalTalkative();

    /* Static generator, for factory. */
    static MetaObject* new_LocalTalkative(MetaObject* superobject, const std::string& type);


    /** Register a new TalkListener.
        @param l The listener object. If l is also a RefCounted object, a
        referece will be acquired.
    */
    void addTalkListener(TalkListener* l);

    /** Remove a TalkListener
        @param l The listener object. If l is also a RefCounted object, the
        referece will be released.
    */
    void removeTalkListener(TalkListener* l);

    /** Send a message from this object, to whatever object sent this object
    * the last message with scope "PRIVATE"
        @throws NoSuchObjectError if there is no object to reply to.
    */
    void reply_to_last(const std::string& text, const int priority = 0 );


    /** Send a message from this object to all children of 'parent' that are
    * talkative with scope "PUBLIC" */
    void say_to_all(const std::string& text, Vobject& parent, const int priority = 0, const std::string& replynonce = "" );


    /** Send a message to this object.
        If there are no TalkListener%s registered, then the message will
        simply be LOG%ged.  Otherwise, each of the listeners will be passed the
        message (in the order in which they were registered).
        It is also possible to override this method to do something else
        entirely.
    */
    void do_say(TalkMessage& msg);

protected:

    /* Handle message say (This message contains text to be spoken or displayed. If spoken (synthesized), then the "voice" property should be used, if possible, to select a voice. ) */
    virtual void handle_say(Message* m);

};


/** Remote version of Talkative. */

class MISC_API RemoteTalkative : public virtual Talkative
{

public:

    /* Constructor */
    RemoteTalkative(MetaObject* superobject);

    /* Static generator, for factory. */
    static MetaObject* new_RemoteTalkative(MetaObject* superobject, const std::string& type);

    /** Send a say messsage to the local object.
        If the "time" field of msg is -1, then it will be filled in with the
        current time.
    */
    virtual void do_say(TalkMessage& msg);


};


#endif // #ifdef _TALKATIVE_HH_

---