libcore/AMFConverter.h

   1 //
   2 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software
   3 //   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
  20 #ifndef GNASH_AMFCONVERTER_H
  21 #define GNASH_AMFCONVERTER_H
  22
  23 #include <map>
  24 #include <string>
  25 #include <vector>
  26
  27 #include "dsodefs.h"
  28 #include "AMF.h"
  29
  30 namespace gnash {
  31     class as_object;
  32     class as_value;
  33     class SimpleBuffer;
  34     class Global_as;
  35 }
  36
  37 namespace gnash {
  38
  39 /// Functions and classes for handling AMF.
  40 //
  41 /// AMF is a simple serialization format for ActionScript objects and values,
  42 /// allowing them to be stored and transmitted. These classes convert between
  43 /// AMF buffers and the objects they contain.
  44 namespace amf {
  45
  46 /// A class to compose AMF buffers.
  47 //
  48 /// A single amf::Writer class can take successive values and encode them
  49 /// in a single buffer. The class takes care of object references.
  50 //
  51 /// This class merely encodes basic types such as strings, numbers, and
  52 /// ActionScript Objects. It does not handle as_values. However, it
  53 /// is designed for use with as_value::writeAMF0(), which uses an
  54 /// instance of this class to serialize itself.
  55 class Writer
  56 {
  57 public:
  58
  59     typedef std::map<as_object*, size_t> OffsetTable;
  60
  61     Writer(SimpleBuffer& buf, bool strictArray = false)
  62         :
  63         _buf(buf),
  64         _strictArray(strictArray)
  65     {}
  66
  67     /// Write any simple Object type: not DisplayObjects.
  68     //
  69     /// Handles functions, dates, XML, and arrays. The object must not be null.
  70     bool writeObject(as_object* obj);
  71
  72     /// Write a string.
  73     //
  74     /// Handles long and short strings.
  75     bool writeString(const std::string& str);
  76
  77     /// Write a null value.
  78     bool writeNull();
  79
  80     /// Write an undefined value.
  81     bool writeUndefined();
  82
  83     /// Write a double.
  84     bool writeNumber(double d);
  85
  86     /// Write a boolean.
  87     bool writeBoolean(bool b);
  88
  89     /// Encode the name of an object's property.
  90     //
  91     /// You should encode the value of the property immediately afterwards.
  92     bool writePropertyName(const std::string& name);
  93
  94     /// Write custom data for special cases.
  95     void writeData(const boost::uint8_t* data, size_t length);
  96
  97 private:
  98
  99     OffsetTable _offsets;
 100     SimpleBuffer& _buf;
 101     bool _strictArray;
 102
 103 };
 104
 105
 106 /// Deserialize an AMF buffer to as_values.
 107 //
 108 /// This class relies on the public interface of as_value because we don't
 109 /// necessarily know in advance what basic type will be read from the
 110 /// buffer.
 111 //
 112 /// Note that callers may change the current buffer position. They must
 113 /// check that the read position is not past the end when a Reader object
 114 /// is called. This is very important!
 115 //
 116 /// For reading of basic types, there is no need to use VM resources. Object
 117 /// types required the construction of objects, which in turn needs a
 118 /// reference to a Global_as. For this reason, object reading functions
 119 /// are member functions, and the Reader requires a Global_as& reference
 120 /// in case it encounters object data.
 121 class Reader
 122 {
 123 public:
 124
 125     /// Construct a Reader with pointers into an AMF buffer.
 126     //
 127     /// You can use the amf::Reader in combination with other reads on the
 128     /// data as long as the read position is never moved after end.
 129     //
 130     /// @param pos      The read position in the buffer. This is moved after
 131     ///                 every read to point to the next data field. You must
 132     ///                 ensure that pos is not greater than end on every read.
 133     /// @param end      The end of the buffer.
 134     /// @param gl       A global reference for creating objects when necessary.
 135     Reader(const boost::uint8_t*& pos, const boost::uint8_t* end, Global_as& gl)
 136         :
 137         _pos(pos),
 138         _end(end),
 139         _global(gl)
 140     {}
 141
 142     /// Create a type from current position in the AMF buffer.
 143     //
 144     /// @param val      An as_value to be created from the AMF data.
 145     /// @param type     The type of the data to read.
 146     /// @return         false if this read failed for any reason.
 147     ///                 The constructed as_value is then invalid. True if
 148     ///                 the read succeeded and the as_value is valid.
 149     bool operator()(as_value& val, Type t = NOTYPE);
 150
 151 private:
 152
 153     /// Read an XML type.
 154     as_value readXML();
 155
 156     /// Read a Date object type.
 157     as_value readDate();
 158
 159     /// Read a simple object type.
 160     as_value readObject();
 161
 162     /// Read an object reference type.
 163     as_value readReference();
 164
 165     /// Read an array object type.
 166     as_value readArray();
 167
 168     /// Read a strict array object type.
 169     as_value readStrictArray();
 170
 171     /// Object references.
 172     std::vector<as_object*> _objectRefs;
 173
 174     /// The current position in the buffer.
 175     const boost::uint8_t*& _pos;
 176
 177     /// The end of the buffer.
 178     const boost::uint8_t* const _end;
 179
 180     /// For creating objects if necessary.
 181     Global_as& _global;
 182
 183 };
 184
 185 } // namespace amf
 186 } // namespace gnash
 187
 188 #endif