libbase/URL.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 #ifndef GNASH_URL_H
  20 #define GNASH_URL_H
  21
  22 #include "dsodefs.h"
  23
  24 #include <iosfwd>
  25 #include <string>
  26 #include <map>
  27
  28 namespace gnash {
  29
  30 /// Uniform Resource Locator
  31 //
  32 /// This class is used to manage URLs.
  33 ///
  34 class DSOEXPORT URL
  35 {
  36
  37 public:
  38
  39         friend std::ostream& operator<< (std::ostream&o, const URL& u);
  40
  41         /// Construct an URL from the given absolute url string.
  42         //
  43         /// A relative URL will be considered a filesystem
  44         /// path relative to the current working directory.
  45         ///
  46         /// Throws std::runtime_error on error
  47         ///
  48         URL(const std::string& absolute_url);
  49
  50         /// Construct an URL from the given relative url string,
  51         /// using the given URL for resolving it.
  52         //
  53         /// Throws std::runtime_error on error
  54         ///
  55         URL(const std::string& relative_url, const URL& baseurl);
  56
  57         /// Return the 'protocol' member of this URL, as a string
  58         const std::string& protocol() const { return _proto; }
  59
  60         /// Return the 'hostname' member of this URL, as a string
  61         //
  62         /// NOTE: return the empty string if protocol() is "file"
  63         ///
  64         const std::string& hostname() const { return _host; }
  65
  66         /// Return the 'port' member of this URL, as a string
  67         //
  68         /// NOTE: return the empty string if the port isn't specified,
  69         /// as this is an optional field.
  70         ///
  71         const std::string& port() const { return _port; }
  72
  73         /// Return the 'path' member of this URL, as a string
  74     //
  75     /// The returned path starts with '/'
  76         const std::string& path() const { return _path; }
  77
  78         /// Return the 'anchor' member of this URL, as a string
  79         //
  80         /// The anchor is the string after the '#' character
  81         ///
  82         const std::string& anchor() const { return _anchor; }
  83
  84         /// Return the 'querystring' member of this URL, as a string
  85         //
  86         /// The query is the string after the '?' character
  87         ///
  88         const std::string& querystring() const { return _querystring; }
  89
  90         /// Set the 'querystring' member of this URL to a new value
  91         //
  92         void set_querystring(const std::string& value) { _querystring = value; }
  93
  94         /// Return the full absolute URL as a string.
  95         //
  96         /// TODO: make output operator and operator+ for strings
  97         std::string str() const;
  98
  99         /// Parse a query string filling the provided map
 100         //
 101         /// @param query_string
 102         ///     the url-escaped query string
 103         ///     (can include or not the starting question mark)
 104         ///
 105         /// @param target_map
 106         ///     A standard map to put parsed values into.
 107         ///     Note: existing elements of the map will be replaced.
 108         ///
 109         /// @todo url-unescape names and values
 110         ///
 111         /// @todo supports duplicated keys (var=value1&var=value2)
 112         ///
 113         static void parse_querystring(const std::string& query_string,
 114                  std::map<std::string, std::string>& target_map);
 115
 116         /// \brief
 117         /// Encode a string to URL-encoded format
 118         /// converting all dodgy characters to %AB hex sequences
 119         //
 120         /// Characters that need escaping are:
 121         /// - ASCII control characters: 0-31 and 127
 122         /// - Non-ASCII chars: 128-255
 123         /// - URL syntax characters: $ & + , / : ; = ? @
 124         /// - Unsafe characters: SPACE " < > # % { } | \ ^ ~ [ ] `
 125         /// Encoding is a % followed by two hexadecimal characters, case insensitive.
 126         /// See RFC1738 http://www.rfc-editor.org/rfc/rfc1738.txt,
 127         /// Section 2.2 "URL Character Encoding Issues"
 128         ///
 129         ///
 130         /// @param str
 131         ///     The input/output string
 132         ///
 133         static void encode(std::string& str);
 134
 135         /// \brief
 136         /// Encode a string to URL-encoded format
 137         /// converting all dodgy characters to %AB hex sequences. This
 138         /// merely uses the void encode() function on a new string.
 139         ///
 140         /// @ param str
 141         ///     The input string
 142         /// @ return
 143         ///     An encoded version of the input string
 144         static std::string encode(const std::string& str);
 145
 146         /// \brief
 147         /// Decode a string from URL-encoded format
 148         /// converting all hexadecimal sequences to ASCII characters.
 149         //
 150         /// A sequence to convert is % followed by two case-independent hexadecimal
 151         /// digits, which is replaced by the equivalent ASCII character.
 152         /// See RFC1738 http://www.rfc-editor.org/rfc/rfc1738.txt,
 153         /// Section 2.2 "URL Character Encoding Issues"
 154         ///
 155         /// @param str
 156         ///     The input/output string
 157         ///
 158         static void decode(std::string& str);
 159
 160 private:
 161         void init_absolute(const std::string& absurl);
 162
 163         void init_relative(const std::string& relurl, const URL& baseurl);
 164
 165         /// Extract anchor from path
 166         void split_anchor_from_path();
 167
 168         /// Extract tcp/ip port from path
 169         void split_port_from_host();
 170
 171         /// Extract and parse query string from path
 172         void split_querystring_from_path();
 173
 174         /// Normalize a 'path' component of an url
 175         //
 176         /// Normalization currently include removal
 177         /// of adjacent slashes, "./" dirs components
 178         /// removal, and "/../" components resolution
 179         ///
 180         void normalize_path(std::string& path);
 181
 182         std::string _proto;
 183         std::string _host;
 184         std::string _port;
 185         std::string _path;
 186         std::string _anchor;
 187         std::string _querystring;
 188 };
 189
 190 DSOEXPORT std::ostream& operator<< (std::ostream&o, const URL& u);
 191
 192 } // end of gnash namespace
 193
 194 // __GNASH_URL_H__
 195 #endif
 196