1 // 2 // Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 3 // 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 <iosfwd> 58 59 #include "dsodefs.h" 60 61 namespace gnash { 62 63 /// A custom form of communication with the host application. 64 // 65 /// This comprises a string and any type of argument. 66 class CustomMessage 67 { 68 public: 69 explicit CustomMessage(std::string s, 70 boost::any arg = boost::blank()) 71 : _name(std::move (s))72 _name(std::move(s)), 73 _arg(std::move(arg)) 74 {} name()75 const std::string& name() const { return _name; } arg()76 const boost::any& arg() const { return _arg; } 77 private: 78 std::string _name; 79 boost::any _arg; 80 }; 81 82 /// Built-in forms of communication with the host application. 83 // 84 /// These messages should be supported for ActionScript compatibility. 85 class HostMessage 86 { 87 public: 88 89 /// The messages that a hosting application should handle. 90 // 91 /// 92 enum KnownEvent { 93 94 /// Whether to display a mouse pointer 95 /// - Argument type: bool 96 /// - Effects: show mouse if true, hide if false 97 /// - Return: boolean, true if the mouse was visible before 98 SHOW_MOUSE, 99 100 /// Resize the stage 101 /// - Argument type: std::pair<int, int>(x, y) 102 /// - Effects: resize stage to x pixels by y pixels 103 /// - Return: none 104 RESIZE_STAGE, 105 106 /// Update the stage 107 /// - Argument type: none 108 /// - Effects: update the stage 109 /// - Return: none 110 UPDATE_STAGE, 111 112 /// Whether to show the menu or not 113 /// - Argument type: bool 114 /// - Effects: show menu if true, hide if false 115 /// - Return: none 116 /// @todo This is probably insufficient. 117 SHOW_MENU, 118 119 /// Whether to show in fullscreen or not 120 /// - Argument type: movie_root::DisplayState 121 /// - Effects: display fullscreen if movie_root::DISPLAYSTATE_FULLSCREEN, 122 /// otherwise normal 123 /// - Return: none 124 SET_DISPLAYSTATE, 125 126 /// Set system clipboard 127 /// - Argument type: std::string 128 /// - Effects: set system clipboard 129 /// - Return: none 130 SET_CLIPBOARD, 131 132 /// Get screen resolution 133 /// - Argument type: none 134 /// - Effects: get screen resolution 135 /// - Return: std::pair<int, int>(x, y) 136 SCREEN_RESOLUTION, 137 138 /// Get screen DPI. 139 /// - Argument type: none 140 /// - Effects: get screen DPI 141 /// - Return: double 142 SCREEN_DPI, 143 144 /// Get pixel aspect ratio 145 /// - Argument type: none 146 /// - Effects: return pixel aspect ratio 147 /// - Return: double 148 PIXEL_ASPECT_RATIO, 149 150 /// Get player type 151 /// - Argument type: none 152 /// - Effects: return "Plugin" or "StandAlone" 153 /// - Return: std::string 154 PLAYER_TYPE, 155 156 /// Get screen color 157 /// - Argument type: none 158 /// - Effects: return "Color" or something else 159 /// - Return: std::string 160 SCREEN_COLOR, 161 162 /// Notify an error 163 /// - Argument type: std::string 164 /// - Effects: notify the user of an error 165 /// - Return: none 166 NOTIFY_ERROR, 167 168 /// Ask a question 169 /// - Argument type: std::string 170 /// - Effects: get the answer to a question 171 /// - Return: bool 172 QUERY, 173 174 /// @todo check if the following types are appropriate. 175 EXTERNALINTERFACE_ISPLAYING, 176 EXTERNALINTERFACE_PAN, 177 EXTERNALINTERFACE_PLAY, 178 EXTERNALINTERFACE_REWIND, 179 EXTERNALINTERFACE_SETZOOMRECT, 180 EXTERNALINTERFACE_STOPPLAY, 181 EXTERNALINTERFACE_ZOOM 182 }; 183 184 explicit HostMessage(KnownEvent e, boost::any arg = boost::blank()) 185 : _event(e)186 _event(e), 187 _arg(std::move(arg)) 188 {} 189 event()190 KnownEvent event() const { return _event; } arg()191 const boost::any& arg() const { return _arg; } 192 193 private: 194 KnownEvent _event; 195 boost::any _arg; 196 }; 197 198 /// Abstract base class for FS handlers 199 class FsCallback 200 { 201 public: 202 virtual void notify(const std::string& cmd, const std::string& arg) = 0; ~FsCallback()203 virtual ~FsCallback() {} 204 }; 205 206 /// Abstract base class for hosting app handler 207 class HostInterface 208 { 209 public: 210 ~HostInterface()211 virtual ~HostInterface() {} 212 213 typedef boost::variant<HostMessage, CustomMessage> Message; 214 215 /// Pass a message to the hosting application with an optional return 216 // 217 /// The core library should access this function through 218 /// movie_root::callInterface() or movie_root::callInterface<>() 219 // 220 /// @param e The message to pass 221 /// @return A return of any type. Both callers and users 222 /// should know the expected type. 223 virtual boost::any call(const Message& e) = 0; 224 225 /// Instruct the hosting application to exit. 226 // 227 /// The hosting application may ignore this: do not rely on it 228 /// to exit the program. 229 virtual void exit() = 0; 230 231 }; 232 233 /// Stream a description of any host interface message type. 234 DSOEXPORT std::ostream& operator<<(std::ostream& os, const HostMessage& m); 235 DSOEXPORT std::ostream& operator<<(std::ostream& os, const CustomMessage& m); 236 237 /// Stream a description of an expected message. 238 DSOEXPORT std::ostream& operator<<(std::ostream& os, HostMessage::KnownEvent e); 239 240 241 } // namespace gnash 242 243 #endif 244