interreality.org [VOS]
[Home] [About]
[Screenshots]
 [Download]
[News]
 [Community]
[Documentation] [Manual]
[Bugs & Requests] [Wiki]

/home/tetron/hack/vos/libs/vos/metaobjects/misc/talkative.hh

Go to the documentation of this file.
00001 /* $Id: talkative.hh,v 1.14 2005/12/18 09:59:40 tetron Exp $ */
00002 
00003 
00004 /*
00005 
00006     Copyright (C)
2002,2003,3004 Reed Hedges interreality.org
00007 
00008     This library is free software; you can redistribute it and/or
00009     modify it under the terms of the GNU Lesser General Public
00010     License as published by the Free Software Foundation; either
00011     version 2 of the License, or (at your option) any later version.
00012 
00013     This library is distributed in the hope that it will be useful,
00014     but WITHOUT ANY WARRANTY; without even the implied warranty of
00015     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00016     Lesser General Public License for more details.
00017 
00018     You should have received a copy of the GNU Lesser General Public
00019     License along with this library; if not, write to the Free Software
00020     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
00021 
00022 */
00023 
00024 #ifndef _TALKATIVE_HH_
00025 #define _TALKATIVE_HH_
00026 
00027 #include <time.h>
00028 
00029 #include <vos/vos/vos.hh>
00030 
00031 
00032 #include "miscdefs.hh"
00033 
00034 namespace VOS {
00035 
00036 #define VOS_TALK_NO_VOICE "#f"
00037 #define VOS_TALK_VOICE_DATATYPE "application/x-festival"
00038 
00039 class TalkMessage;
00040 class TalkListener;
00041 
00042 /** @class Talkative talkative.hh vos/metaobjects/misc/talkative.hh
00043  * @ingroup libmetaobject_misc
00044     This object type facilitates verbal intercommunication in the form of
00045     text (which may be synthesized as human speech if possible).
00046 */
00047 
00048 
00049 class MISC_API Talkative : public MetaObject
00050 {
00051 protected:
00052     virtual void do_say(TalkMessage& msg) = 0;
00053     virtual void do_resend(Talkative* resendTo, TalkMessage& m) = 0;
00054 public:
00055 
00056     /** @name Message scope codes */
00057     //@{
00058 
00059     static const unsigned short UNSPECIFIED;
00060     static const unsigned short PUBLIC;
00061     static const unsigned short PRIVATE;
00062     static const unsigned short AUTO;
00063     static const unsigned short FROM_APP;   ///<Same as SYSTEM
00064     static const unsigned short SYSTEM; ///<Same as FROM_APP
00065     static const unsigned short EMOTE;
00066 
00067     //@}
00068 
00069 public:
00070 
00071     Talkative(VobjectBase* superobject);
00072 
00073     /** Return type string ("talkative") */
00074     const std::string getVOSType();
00075 
00076     /** Get the voice property.
00077             @see setVoice
00078     */
00079     std::string getVoice();
00080 
00081     /** Set voice property.
00082         @param value The new value. This is a voice definition to be passed to
00083             the Festival speech synthesis system: it can be a predefined
00084             voice, a full voice definition function, or "#f" for no voice.
00085      */
00086     void setVoice(const std::string& value);
00087 
00088 
00089     /** 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.
00090         @see Talkative::TalkMessage
00091     */
00092 
00093     virtual void say(TalkMessage& msg);
00094 
00095     /** Contructs a TalkMessage and calls say(TalkMessage&) */
00096     void say(const std::string& text, Talkative& sender,
00097              const unsigned short scope, const int priority = 0,
00098              uint32_t replynonce = 0,
00099              uint32_t thisnonce = 0);
00100 
00101     /** calls say(text, sender, UNSPECIFIED, 0, "")
00102     */
00103     void say(const std::string& text, Talkative& sender, uint32_t in_reply_to = 0) {
00104         say(text, sender, UNSPECIFIED, 0, in_reply_to);
00105     }
00106 
00107     /** @return the object containing relay listeners, if it exists. */
00108     virtual VUtil::vRef<Vobject> getRelayListeners();
00109 
00110     virtual void addRelay(Talkative* t);
00111     virtual void removeRelay(Talkative* t);
00112 
00113     /** If the target object has a relay listeners group, then resend message via
00114      *  that target object, otherwise, iterate over target object's children and
00115      *  send the message directly to each talkative object (other than this).
00116      *  For example, use this method to send a message to the other members of an A3DL
00117      *  world sector.
00118      */
00119     virtual void sayToAllMembers(Vobject* target, TalkMessage& msg);
00120 
00121 
00122     /** Have this object resend the supplied message as if it came
00123         from itself.
00124     */
00125     virtual void resend(Talkative* resendTo, TalkMessage& msg);
00126 
00127     /** Contructs a TalkMessage and calls resend(TalkMessage&) */
00128     void resend(Talkative* resendTo,
00129              const std::string& text,
00130              const unsigned short scope, const int priority = 0,
00131              uint32_t replynonce = 0,
00132              uint32_t thisnonce = 0);
00133 
00134     /** calls resend(text, sender, UNSPECIFIED, 0, "")
00135     */
00136     void resend(Talkative* resendTo, const std::string& text,
00137                 uint32_t in_reply_to = 0)
00138         {
00139             resend(resendTo, text, UNSPECIFIED, 0, in_reply_to);
00140         }
00141 };
00142 
00143 /** @class TalkListener talkative.hh vos/metaobjects/misc/talkative.hh
00144  *  MetaObject implementing Talkative Object Type.Interface for message listeners.
00145  *  @see LocalTalkative::addTalkListener.
00146  * @ingroup libmetaobject_misc
00147 */
00148 class MISC_API TalkListener {
00149 public:
00150     virtual ~TalkListener() { }
00151 
00152     /** Override this method to handle talk messages. */
00153     virtual void notifyTalkMessage(TalkMessage& m) = 0;
00154 };
00155 
00156 /** @class TalkMessage talkative.hh vos/metaobjects/misc/talkative.hh
00157  * @ingroup libmetaobject_misc
00158  *  Structure defining a talk message */
00159 class MISC_API TalkMessage : public VUtil::RefCounted {
00160 private:
00161     std::string text;
00162     std::vector< VUtil::vRef<Talkative> > relay_path;
00163 
00164     VUtil::vRef<Talkative> origin;
00165     VUtil::vRef<Talkative> last_sender;
00166 
00167     unsigned short scope;   ///<See scope codes below. Combine multiple codes with |.
00168     int priority;
00169     time_t time;  ///< Time message was sent (seconds since midnight, Jan 1 1970, UTC., except -1 means no time available.)
00170     uint32_t reply_nonce;  ///< If not zero, this is the nonce (message ID) of a previous message to which this one is a reply.
00171     uint32_t this_nonce;   ///< If not zero, this is the nonce (message ID) of this talk message. Combine with URL of sender to form a unique ID.
00172 
00173     VUtil::vRef<Message> vosmessage;
00174 public:
00175 
00176     TalkMessage(Talkative& se, std::string t = "",
00177                 unsigned short sc = Talkative::UNSPECIFIED,
00178                 int pr = 0, time_t tm = -1,
00179                 uint32_t rn = 0,
00180                 uint32_t tn = 0);
00181     TalkMessage(Message* m);
00182 
00183     VUtil::vRef<Talkative> getReceiver() { return relay_path.back(); }
00184     VUtil::vRef<Talkative> getLastSender() { return last_sender; }
00185     VUtil::vRef<Talkative> getOrigin() { return origin; }
00186     const std::vector< VUtil::vRef<Talkative> >& getRelayPath()
00187             { return relay_path; }
00188 
00189     void addHop(Talkative* t);
00190 
00191     const std::string& getText() { return text; }
00192     unsigned short getScope() { return scope; }
00193     int getPriority() { return priority; }
00194     time_t getTime() { return time; }
00195     uint32_t getReplyNonce() { return reply_nonce; }
00196     uint32_t getNonce() { return this_nonce; }
00197     VUtil::vRef<Message> getVOSMessage();
00198 
00199     virtual void deliverTo(TalkListener* tl)
00200         {
00201             tl->notifyTalkMessage(*this);
00202         }
00203 };
00204 
00205 
00206 /** @class LocalTalkative talkative.hh vos/metaobjects/misc/talkative.hh
00207  *  Local implementation of Talkative.
00208  * @ingroup libmetaobject_misc
00209  */
00210 
00211 class MISC_API LocalTalkative : public Talkative {
00212 
00213 private:
00214     VUtil::ListenerBase<TalkListener, TalkMessage> listeners;
00215 
00216     /* Which object sent us the last message? (or clear/invalid for none) */
00217     VUtil::vRef<Talkative> replyto;
00218 
00219     /* Handle "say" message (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. ) */
00220     virtual void handleSay(Message* m);
00221     virtual void handleResend(Message* m);
00222 
00223 protected:
00224 
00225     /** Send a message to this object.
00226         If there are no TalkListener%s registered, then the message will
00227         simply be LOG%ged.  Otherwise, each of the listeners will be passed the
00228         message (in the order in which they were registered).
00229         It is also possible to override this method to do something else
00230         entirely.
00231     */
00232     virtual void do_say(TalkMessage& msg);
00233 
00234     virtual void do_resend(Talkative* sendTo, TalkMessage& m);
00235 
00236 public:
00237 
00238     LocalTalkative(VobjectBase* superobject);
00239 
00240     ~LocalTalkative();
00241 
00242     static MetaObject* new_LocalTalkative(VobjectBase* superobject, const std::string& type);
00243 
00244     /** Register a new TalkListener.
00245         @param l The listener object. If l is also a VUtil::RefCounted object, a
00246         referece will be acquired.
00247     */
00248     virtual void addTalkListener(TalkListener* l);
00249 
00250     /** Remove a TalkListener
00251         @param l The listener object. If l is also a VUtil::RefCounted object, the
00252         referece will be released.
00253     */
00254     virtual void removeTalkListener(TalkListener* l);
00255 };
00256 
00257 
00258 /** @class RemoteTalkative talkative.hh vos/metaobjects/misc/talkative.hh
00259  *  Remote proxy for Talkative.
00260  * @ingroup libmetaobject_misc
00261  */
00262 class MISC_API RemoteTalkative : public virtual Talkative
00263 {
00264 protected:
00265     /** Send a say messsage to the local object.
00266         @param msg The message. If the "time" field of msg is -1, then it will
00267         be filled in with the current time.
00268     */
00269     virtual void do_say(TalkMessage& msg);
00270 
00271     virtual void do_resend(Talkative* sendTo, TalkMessage& m);
00272 
00273 public:
00274 
00275     RemoteTalkative(VobjectBase* superobject);
00276 
00277     static MetaObject* new_RemoteTalkative(VobjectBase* superobject,
00278                                            const std::string& type);
00279 };
00280 
00281 
00282 class MISC_API TalkativeAccessControl
00283 {
00284 public:
00285     virtual ~TalkativeAccessControl() { }
00286 
00287         /** Get a short string describing this policy. */
00288         virtual const std::string getPolicyName() = 0;
00289 
00290         virtual bool checkSendPermission(Vobject* requester,
00291                                          Vobject* parent,
00292                                          TalkMessage& msg,
00293                                          std::string& errmessage) = 0;
00294         virtual bool checkResendPermission(Vobject* requester,
00295                                            Vobject* parent,
00296                                            TalkMessage& msg,
00297                                            std::string& errmessage) = 0;
00298 
00299 };
00300 
00301 class MISC_API AcceptAllTalkativeAC : public TalkativeAccessControl
00302 {
00303 public:
00304     static AcceptAllTalkativeAC static_;
00305 
00306     virtual ~AcceptAllTalkativeAC() { }
00307 
00308         /** Get a short string describing this policy. */
00309         virtual const std::string getPolicyName()
00310         { return "talkative:accept-all"; }
00311 
00312         virtual bool checkSendPermission(Vobject* requester,
00313                                          Vobject* parent,
00314                                          TalkMessage& msg,
00315                                          std::string& errmessage)
00316         { return true; }
00317 
00318         virtual bool checkResendPermission(Vobject* requester,
00319                                            Vobject* parent,
00320                                            TalkMessage& msg,
00321                                            std::string& errmessage)
00322         { return true; }
00323 };
00324 
00325 class MISC_API SendOnlyTalkativeAC : public TalkativeAccessControl
00326 {
00327 public:
00328     static SendOnlyTalkativeAC static_;
00329 
00330     virtual ~SendOnlyTalkativeAC() { }
00331 
00332         /** Get a short string describing this policy. */
00333         virtual const std::string getPolicyName()
00334         { return "talkative:send-only"; }
00335 
00336         virtual bool checkSendPermission(Vobject* requester,
00337                                          Vobject* parent,
00338                                          TalkMessage& msg,
00339                                          std::string& errmessage)
00340         { return true; }
00341 
00342         virtual bool checkResendPermission(Vobject* requester,
00343                                            Vobject* parent,
00344                                            TalkMessage& msg,
00345                                            std::string& errmessage)
00346         { return false; }
00347 };
00348 
00349 class MISC_API DenyAllTalkativeAC : public TalkativeAccessControl
00350 {
00351 public:
00352     static DenyAllTalkativeAC static_;
00353 
00354     virtual ~DenyAllTalkativeAC() { }
00355 
00356         /** Get a short string describing this policy. */
00357     virtual const std::string getPolicyName()
00358         { return "talkative:deny-all"; }
00359 
00360         virtual bool checkSendPermission(Vobject* requester,
00361                                          Vobject* parent,
00362                                          TalkMessage& msg,
00363                                          std::string& errmessage)
00364         { return false; }
00365 
00366         virtual bool checkResendPermission(Vobject* requester,
00367                                            Vobject* parent,
00368                                            TalkMessage& msg,
00369                                            std::string& errmessage)
00370         { return false; }
00371 };
00372 
00373 } // namespace VOS
00374 
00375 #ifndef MISC_EXPORTS
00376 IMPORT_METAOBJECT_FACTORIES(Talkative)
00377 #endif
00378 
00379 #endif // #ifdef _TALKATIVE_HH_
00380