libcore/HostInterface.h

   1 //
   2 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010,
   3 //   2011 Free Software Foundation, Inc
   4 //
   5 // This program is free software; you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation; either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // This program is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with this program; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19 /// \page interface Host Interface
  20 ///
  21 /// The core Gnash libraries support a flexible way of interacting with
  22 /// hosting applications. This is necessary for ActionScript execution, as
  23 /// well as for user notifications.
  24 ///
  25 /// 1. The hosting application may ignore any message without dangerous
  26 ///    side effects.
  27 ///
  28 /// 2. A set of expected messages exist, which should be supported for
  29 ///    proper ActionScript compatibility.
  30 ///
  31 /// 3. Users must return the exact type expected (see KnownEvent), as
  32 ///    no implicit conversion is used. This means, for instance, that
  33 ///    where a std::string is expected, a const char* may not be used.
  34 ///
  35 /// 4. There is the possibility to add custom messages for use in
  36 ///    ActionScript extensions.
  37 ///
  38 /// The rationale for the current design is that hosting applications
  39 /// should be able to support as many of the expected messages types as
  40 /// they choose using a single interface: gnash::HostInterface::call(). This
  41 /// should support various types of argument and various types of
  42 /// return, so that the different
  43 ///
  44 /// The drawback of this flexibility is that there is no compile-time
  45 /// check for the correct use of the interface. Within the core
  46 /// libraries, this host interface is accessed only through
  47 /// gnash::movie_root::callInterface(),
  48 /// ensuring that any mistakes in the hosting application are handled
  49 /// safely and logged.
  50
  51 #ifndef GNASH_HOST_INTERFACE_H
  52 #define GNASH_HOST_INTERFACE_H
  53
  54 #include <boost/variant.hpp>
  55 #include <boost/any.hpp>
  56 #include <string>
  57 #include <ostream>
  58
  59 namespace gnash {
  60
  61 /// A custom form of communication with the host application.
  62 //
  63 /// This comprises a string and any type of argument.
  64 class CustomMessage
  65 {
  66 public:
  67     explicit CustomMessage(const std::string& s,
  68             const boost::any& arg = boost::blank())
  69         :
  70         _name(s),
  71         _arg(arg)
  72     {}
  73     const std::string& name() const { return _name; }
  74     const boost::any& arg() const { return _arg; }
  75 private:
  76     std::string _name;
  77     boost::any _arg;
  78 };
  79
  80 /// Built-in forms of communication with the host application.
  81 //
  82 /// These messages should be supported for ActionScript compatibility.
  83 class HostMessage
  84 {
  85 public:
  86
  87     /// The messages that a hosting application should handle.
  88     //
  89     ///
  90     enum KnownEvent {
  91
  92         /// Whether to display a mouse pointer
  93         /// - Argument type: bool
  94         /// - Effects: show mouse if true, hide if false
  95         /// - Return: boolean, true if the mouse was visible before
  96         SHOW_MOUSE,
  97
  98         /// Resize the stage
  99         /// - Argument type: std::pair<int, int>(x, y)
 100         /// - Effects: resize stage to x pixels by y pixels
 101         /// - Return: none
 102         RESIZE_STAGE,
 103
 104         /// Update the stage
 105         /// - Argument type: none
 106         /// - Effects: update the stage
 107         /// - Return: none
 108         UPDATE_STAGE,
 109
 110         /// Whether to show the menu or not
 111         /// - Argument type: bool
 112         /// - Effects: show menu if true, hide if false
 113         /// - Return: none
 114         /// @todo   This is probably insufficient.
 115         SHOW_MENU,
 116
 117         /// Whether to show in fullscreen or not
 118         /// - Argument type: movie_root::DisplayState
 119         /// - Effects: display fullscreen if movie_root::DISPLAYSTATE_FULLSCREEN,
 120         ///            otherwise normal
 121         /// - Return: none
 122         SET_DISPLAYSTATE,
 123
 124         /// Set system clipboard
 125         /// - Argument type: std::string
 126         /// - Effects: set system clipboard
 127         /// - Return: none
 128         SET_CLIPBOARD,
 129
 130         /// Get screen resolution
 131         /// - Argument type: none
 132         /// - Effects: get screen resolution
 133         /// - Return: std::pair<int, int>(x, y)
 134         SCREEN_RESOLUTION,
 135
 136         /// Get screen DPI.
 137         /// - Argument type: none
 138         /// - Effects: get screen DPI
 139         /// - Return: double
 140         SCREEN_DPI,
 141
 142         /// Get pixel aspect ratio
 143         /// - Argument type: none
 144         /// - Effects: return pixel aspect ratio
 145         /// - Return: double
 146         PIXEL_ASPECT_RATIO,
 147
 148         /// Get player type
 149         /// - Argument type: none
 150         /// - Effects: return "Plugin" or "StandAlone"
 151         /// - Return: std::string
 152         PLAYER_TYPE,
 153
 154         /// Get screen color
 155         /// - Argument type: none
 156         /// - Effects: return "Color" or something else
 157         /// - Return: std::string
 158         SCREEN_COLOR,
 159
 160         /// Notify an error
 161         /// - Argument type: std::string
 162         /// - Effects: notify the user of an error
 163         /// - Return: none
 164         NOTIFY_ERROR,
 165
 166         /// Ask a question
 167         /// - Argument type: std::string
 168         /// - Effects: get the answer to a question
 169         /// - Return: bool
 170         QUERY,
 171
 172         /// @todo check if the following types are appropriate.
 173         EXTERNALINTERFACE_ISPLAYING,
 174         EXTERNALINTERFACE_PAN,
 175         EXTERNALINTERFACE_PLAY,
 176         EXTERNALINTERFACE_REWIND,
 177         EXTERNALINTERFACE_SETZOOMRECT,
 178         EXTERNALINTERFACE_STOPPLAY,
 179         EXTERNALINTERFACE_ZOOM
 180     };
 181
 182     explicit HostMessage(KnownEvent e, const boost::any& arg = boost::blank())
 183         :
 184         _event(e),
 185         _arg(arg)
 186     {}
 187
 188     KnownEvent event() const { return _event; }
 189     const boost::any& arg() const { return _arg; }
 190
 191 private:
 192     KnownEvent _event;
 193     boost::any _arg;
 194 };
 195
 196 /// Abstract base class for FS handlers
 197 class FsCallback
 198 {
 199 public:
 200     virtual void notify(const std::string& cmd, const std::string& arg) = 0;
 201     virtual ~FsCallback() {}
 202 };
 203
 204 /// Abstract base class for hosting app handler
 205 class HostInterface
 206 {
 207 public:
 208
 209     virtual ~HostInterface() {}
 210
 211     typedef boost::variant<HostMessage, CustomMessage> Message;
 212
 213     /// Pass a message to the hosting application with an optional return
 214     //
 215     /// The core library should access this function through
 216     /// movie_root::callInterface() or movie_root::callInterface<>()
 217     //
 218     /// @param e    The message to pass
 219     /// @return     A return of any type. Both callers and users
 220     ///             should know the expected type.
 221     virtual boost::any call(const Message& e) = 0;
 222
 223     /// Instruct the hosting application to exit.
 224     //
 225     /// The hosting application may ignore this: do not rely on it
 226     /// to exit the program.
 227     virtual void exit() = 0;
 228
 229 };
 230
 231 /// Stream a description of any host interface message type.
 232 std::ostream& operator<<(std::ostream& os, const HostMessage& m);
 233 std::ostream& operator<<(std::ostream& os, const CustomMessage& m);
 234
 235 /// Stream a description of an expected message.
 236 std::ostream& operator<<(std::ostream& os, HostMessage::KnownEvent e);
 237
 238
 239 } // namespace gnash
 240
 241 #endif