libbase/AMF.h

   1 // AMF.h    Low level functions for manipulating and reading AMF buffers.
   2 //
   3 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software
   4 //   Foundation, Inc
   5 //
   6 // This program is free software; you can redistribute it and/or modify
   7 // it under the terms of the GNU General Public License as published by
   8 // the Free Software Foundation; either version 3 of the License, or
   9 // (at your option) any later version.
  10 //
  11 // This program is distributed in the hope that it will be useful,
  12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 // GNU General Public License for more details.
  15 //
  16 // You should have received a copy of the GNU General Public License
  17 // along with this program; if not, write to the Free Software
  18 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  19
  20 // This file provides low-level manipulators for AMF buffers. It can be used
  21 // without reliance on libcore.
  22
  23 #ifndef GNASH_AMF_H
  24 #define GNASH_AMF_H
  25
  26 #include <string>
  27 #include <boost/cstdint.hpp>
  28
  29 #include "dsodefs.h"
  30 #include "GnashException.h"
  31
  32 namespace gnash {
  33     class SimpleBuffer;
  34 }
  35
  36 namespace gnash {
  37
  38 /// Functions and classes for handling AMF.
  39 //
  40 /// AMF is a simple serialization format for ActionScript objects and values,
  41 /// allowing them to be stored and transmitted. The AMF namespace provides
  42 /// both low-level and high-level conversion to and from AMF buffers.
  43 namespace amf {
  44
  45 enum Type {
  46     NOTYPE            = -1,
  47     NUMBER_AMF0       = 0x00,
  48     BOOLEAN_AMF0      = 0x01,
  49     STRING_AMF0       = 0x02,
  50     OBJECT_AMF0       = 0x03,
  51     MOVIECLIP_AMF0    = 0x04,
  52     NULL_AMF0         = 0x05,
  53     UNDEFINED_AMF0    = 0x06,
  54     REFERENCE_AMF0    = 0x07,
  55     ECMA_ARRAY_AMF0   = 0x08,
  56     OBJECT_END_AMF0   = 0x09,
  57     STRICT_ARRAY_AMF0 = 0x0a,
  58     DATE_AMF0         = 0x0b,
  59     LONG_STRING_AMF0  = 0x0c,
  60     UNSUPPORTED_AMF0  = 0x0d,
  61     RECORD_SET_AMF0   = 0x0e,
  62     XML_OBJECT_AMF0   = 0x0f,
  63     TYPED_OBJECT_AMF0 = 0x10
  64 };
  65
  66 /// Exception for handling malformed buffers.
  67 //
  68 /// All low-level reading operations can throw this error.
  69 class DSOEXPORT
  70 AMFException : public GnashException
  71 {
  72 public:
  73     AMFException(const std::string& msg)
  74         :
  75         GnashException(msg)
  76     {}
  77 };
  78
  79 /// Read a number from an AMF buffer
  80 //
  81 /// This does not read a type byte; use AMF::Reader when the type should
  82 /// be determined from the buffer.
  83 //
  84 /// This function will throw an AMFException if it encounters ill-formed AMF.
  85 DSOEXPORT double readNumber(const boost::uint8_t*& pos,
  86         const boost::uint8_t* end);
  87
  88 /// Read a boolean value from the buffer.
  89 //
  90 /// This does not read a type byte; use AMF::Reader when the type should
  91 /// be determined from the buffer.
  92 //
  93 /// This function will throw an AMFException if it encounters ill-formed AMF.
  94 DSOEXPORT bool readBoolean(const boost::uint8_t*& pos,
  95         const boost::uint8_t* end);
  96
  97 /// Read a string value from the buffer.
  98 //
  99 /// This does not read a type byte; use AMF::Reader when the type should
 100 /// be determined from the buffer.
 101 //
 102 /// This function will throw an AMFException if it encounters ill-formed AMF.
 103 DSOEXPORT std::string readString(const boost::uint8_t*& pos,
 104         const boost::uint8_t* end);
 105
 106 /// Read a long string value from the buffer.
 107 //
 108 /// This does not read a type byte; use AMF::Reader when the type should
 109 /// be determined from the buffer.
 110 //
 111 /// This function will throw an AMFException if it encounters ill-formed AMF.
 112 DSOEXPORT std::string readLongString(const boost::uint8_t*& pos,
 113         const boost::uint8_t* end);
 114
 115 /// Read an unsigned 16-bit value in network byte order.
 116 //
 117 /// You must ensure that the buffer contains at least 2 bytes!
 118 inline boost::uint16_t
 119 readNetworkShort(const boost::uint8_t* buf)
 120 {
 121     const boost::uint16_t s = buf[0] << 8 | buf[1];
 122     return s;
 123 }
 124
 125 /// Read an unsigned 32-bit value in network byte order.
 126 //
 127 /// You must ensure that the buffer contains at least 4 bytes!
 128 inline boost::uint32_t
 129 readNetworkLong(const boost::uint8_t* buf)
 130 {
 131     const boost::uint32_t s = buf[0] << 24 | buf[1] << 16 |
 132                               buf[2] << 8 | buf[3];
 133     return s;
 134 }
 135
 136 /// Write a string to an AMF buffer.
 137 //
 138 /// This function writes the type byte and the string value. It also handles
 139 /// both long and short strings automatically.
 140 //
 141 /// This is overloaded for automatic type deduction to allow the use of
 142 /// a template for more complex operations. You must be careful when using
 143 /// it!
 144 DSOEXPORT void write(SimpleBuffer& buf, const std::string& str);
 145
 146 /// Write a C string to an AMF buffer.
 147 //
 148 /// The overload is necessary to prevent const char* being resolved to the
 149 /// boolean overload.
 150 inline void write(SimpleBuffer& buf, const char* str) {
 151     return write(buf, std::string(str));
 152 }
 153
 154 /// Write a number to an AMF buffer.
 155 //
 156 /// This function writes the type byte and the double value.
 157 //
 158 /// This is overloaded for automatic type deduction to allow the use of
 159 /// a template for more complex operations. You must be careful when using
 160 /// it!
 161 DSOEXPORT void write(SimpleBuffer& buf, double d);
 162
 163 /// Write a boolean value to an AMF buffer.
 164 //
 165 /// This function writes the type byte and the boolean value.
 166 //
 167 /// This is overloaded for automatic type deduction to allow the use of
 168 /// a template for more complex operations. You must be careful when using
 169 /// it!
 170 DSOEXPORT void write(SimpleBuffer& buf, bool b);
 171
 172 /// Encode a plain short string to an AMF buffer.
 173 //
 174 /// This does not encode a type byte; it is used for cases where a string is
 175 /// required, such as for the name of an object property, and therefore does
 176 /// not use a type byte.
 177 DSOEXPORT void writePlainString(SimpleBuffer& buf, const std::string& str,
 178         Type t);
 179
 180 /// Write a number to an AMF buffer.
 181 //
 182 /// This function writes the double value without a type byte.
 183 DSOEXPORT void writePlainNumber(SimpleBuffer& buf, double d);
 184
 185 /// Encode a string-value pair.
 186 //
 187 /// This is used for object properties; the string is always encoded with
 188 /// a 2-byte length.
 189 template<typename T>
 190 void
 191 writeProperty(SimpleBuffer& buf, const std::string& name, const T& t)
 192 {
 193     writePlainString(buf, name, STRING_AMF0);
 194     write(buf, t);
 195 }
 196
 197 } // namespace amf
 198 } // namespace gnash
 199
 200 #endif