git.sesse.net Git - casparcg/blob - SFML-1.6/include/SFML/Network/Http.hpp

   1 ////////////////////////////////////////////////////////////\r
   2 //\r
   3 // SFML - Simple and Fast Multimedia Library\r
   4 // Copyright (C) 2007-2009 Laurent Gomila (laurent.gom@gmail.com)\r
   5 //\r
   6 // This software is provided 'as-is', without any express or implied warranty.\r
   7 // In no event will the authors be held liable for any damages arising from the use of this software.\r
   8 //\r
   9 // Permission is granted to anyone to use this software for any purpose,\r
  10 // including commercial applications, and to alter it and redistribute it freely,\r
  11 // subject to the following restrictions:\r
  12 //\r
  13 // 1. The origin of this software must not be misrepresented;\r
  14 //    you must not claim that you wrote the original software.\r
  15 //    If you use this software in a product, an acknowledgment\r
  16 //    in the product documentation would be appreciated but is not required.\r
  17 //\r
  18 // 2. Altered source versions must be plainly marked as such,\r
  19 //    and must not be misrepresented as being the original software.\r
  20 //\r
  21 // 3. This notice may not be removed or altered from any source distribution.\r
  22 //\r
  23 ////////////////////////////////////////////////////////////\r
  24 \r
  25 #ifndef SFML_HTTP_HPP\r
  26 #define SFML_HTTP_HPP\r
  27 \r
  28 ////////////////////////////////////////////////////////////\r
  29 // Headers\r
  30 ////////////////////////////////////////////////////////////\r
  31 #include <SFML/System/NonCopyable.hpp>\r
  32 #include <SFML/Network/IPAddress.hpp>\r
  33 #include <SFML/Network/SocketTCP.hpp>\r
  34 #include <map>\r
  35 #include <string>\r
  36 \r
  37 \r
  38 namespace sf\r
  39 {\r
  40 ////////////////////////////////////////////////////////////\r
  41 /// This class provides methods for manipulating the HTTP\r
  42 /// protocol (described in RFC 1945).\r
  43 /// It can connect to a website, get its files, send requests, etc.\r
  44 ////////////////////////////////////////////////////////////\r
  45 class SFML_API Http : NonCopyable\r
  46 {\r
  47 public :\r
  48 \r
  49     ////////////////////////////////////////////////////////////\r
  50     /// This class wraps an HTTP request, which is basically :\r
  51     /// - a header with a method, a target URI, and a set of field/value pairs\r
  52     /// - an optional body (for POST requests)\r
  53     ////////////////////////////////////////////////////////////\r
  54     class SFML_API Request\r
  55     {\r
  56     public :\r
  57 \r
  58         ////////////////////////////////////////////////////////////\r
  59         /// Enumerate the available HTTP methods for a request\r
  60         ////////////////////////////////////////////////////////////\r
  61         enum Method\r
  62         {\r
  63             Get,  ///< Request in get mode, standard method to retrieve a page\r
  64             Post, ///< Request in post mode, usually to send data to a page\r
  65             Head  ///< Request a page's header only\r
  66         };\r
  67 \r
  68         ////////////////////////////////////////////////////////////\r
  69         /// Default constructor\r
  70         ///\r
  71         /// \param RequestMethod : Method to use for the request (Get by default)\r
  72         /// \param URI :           Target URI ("/" by default -- index page)\r
  73         /// \param Body :          Content of the request's body (empty by default)\r
  74         ///\r
  75         ////////////////////////////////////////////////////////////\r
  76         Request(Method RequestMethod = Get, const std::string& URI = "/", const std::string& Body = "");\r
  77 \r
  78         ////////////////////////////////////////////////////////////\r
  79         /// Set the value of a field; the field is added if it doesn't exist\r
  80         ///\r
  81         /// \param Field : Name of the field to set (case-insensitive)\r
  82         /// \param Value : Value of the field\r
  83         ///\r
  84         ////////////////////////////////////////////////////////////\r
  85         void SetField(const std::string& Field, const std::string& Value);\r
  86 \r
  87         ////////////////////////////////////////////////////////////\r
  88         /// Set the request method.\r
  89         /// This parameter is Http::Request::Get by default\r
  90         ///\r
  91         /// \param RequestMethod : Method to use for the request\r
  92         ///\r
  93         ////////////////////////////////////////////////////////////\r
  94         void SetMethod(Method RequestMethod);\r
  95 \r
  96         ////////////////////////////////////////////////////////////\r
  97         /// Set the target URI of the request.\r
  98         /// This parameter is "/" by default\r
  99         ///\r
 100         /// \param URI : URI to request, local to the host\r
 101         ///\r
 102         ////////////////////////////////////////////////////////////\r
 103         void SetURI(const std::string& URI);\r
 104 \r
 105         ////////////////////////////////////////////////////////////\r
 106         /// Set the HTTP version of the request.\r
 107         /// This parameter is 1.0 by default\r
 108         ///\r
 109         /// \param Major : Major version number\r
 110         /// \param Minor : Minor version number\r
 111         ///\r
 112         ////////////////////////////////////////////////////////////\r
 113         void SetHttpVersion(unsigned int Major, unsigned int Minor);\r
 114 \r
 115         ////////////////////////////////////////////////////////////\r
 116         /// Set the body of the request. This parameter is optional and\r
 117         /// makes sense only for POST requests.\r
 118         /// This parameter is empty by default\r
 119         ///\r
 120         /// \param Body : Content of the request body\r
 121         ///\r
 122         ////////////////////////////////////////////////////////////\r
 123         void SetBody(const std::string& Body);\r
 124 \r
 125     private :\r
 126 \r
 127         friend class Http;\r
 128 \r
 129         ////////////////////////////////////////////////////////////\r
 130         /// Get the string representation of the request header\r
 131         ///\r
 132         /// \return String containing the request\r
 133         ///\r
 134         ////////////////////////////////////////////////////////////\r
 135         std::string ToString() const;\r
 136 \r
 137         ////////////////////////////////////////////////////////////\r
 138         /// Check if the given field has been defined\r
 139         ///\r
 140         /// \param Field : Name of the field to check (case-insensitive)\r
 141         ///\r
 142         /// \return True if the field exists\r
 143         ///\r
 144         ////////////////////////////////////////////////////////////\r
 145         bool HasField(const std::string& Field) const;\r
 146 \r
 147         ////////////////////////////////////////////////////////////\r
 148         // Types\r
 149         ////////////////////////////////////////////////////////////\r
 150         typedef std::map<std::string, std::string> FieldTable;\r
 151 \r
 152         ////////////////////////////////////////////////////////////\r
 153         // Member data\r
 154         ////////////////////////////////////////////////////////////\r
 155         FieldTable   myFields;       ///< Fields of the header\r
 156         Method       myMethod;       ///< Method to use for the request\r
 157         std::string  myURI;          ///< Target URI of the request\r
 158         unsigned int myMajorVersion; ///< Major HTTP version\r
 159         unsigned int myMinorVersion; ///< Minor HTTP version\r
 160         std::string  myBody;         ///< Body of the request\r
 161     };\r
 162 \r
 163     ////////////////////////////////////////////////////////////\r
 164     /// This class wraps an HTTP response, which is basically :\r
 165     /// - a header with a status code and a set of field/value pairs\r
 166     /// - a body (the content of the requested resource)\r
 167     ////////////////////////////////////////////////////////////\r
 168     class SFML_API Response\r
 169     {\r
 170     public :\r
 171 \r
 172         ////////////////////////////////////////////////////////////\r
 173         /// Enumerate all the valid status codes returned in\r
 174         /// a HTTP response\r
 175         ////////////////////////////////////////////////////////////\r
 176         enum Status\r
 177         {\r
 178             // 2xx: success\r
 179             Ok        = 200, ///< Most common code returned when operation was successful\r
 180             Created   = 201, ///< The resource has successfully been created\r
 181             Accepted  = 202, ///< The request has been accepted, but will be processed later by the server\r
 182             NoContent = 204, ///< Sent when the server didn't send any data in return\r
 183 \r
 184             // 3xx: redirection\r
 185             MultipleChoices  = 300, ///< The requested page can be accessed from several locations\r
 186             MovedPermanently = 301, ///< The requested page has permanently moved to a new location\r
 187             MovedTemporarily = 302, ///< The requested page has temporarily moved to a new location\r
 188             NotModified      = 304, ///< For conditionnal requests, means the requested page hasn't changed and doesn't need to be refreshed\r
 189 \r
 190             // 4xx: client error\r
 191             BadRequest   = 400, ///< The server couldn't understand the request (syntax error)\r
 192             Unauthorized = 401, ///< The requested page needs an authentification to be accessed\r
 193             Forbidden    = 403, ///< The requested page cannot be accessed at all, even with authentification\r
 194             NotFound     = 404, ///< The requested page doesn't exist\r
 195 \r
 196             // 5xx: server error\r
 197             InternalServerError = 500, ///< The server encountered an unexpected error\r
 198             NotImplemented      = 501, ///< The server doesn't implement a requested feature\r
 199             BadGateway          = 502, ///< The gateway server has received an error from the source server\r
 200             ServiceNotAvailable = 503, ///< The server is temporarily unavailable (overloaded, in maintenance, ...)\r
 201 \r
 202             // 10xx: SFML custom codes\r
 203             InvalidResponse  = 1000, ///< Response is not a valid HTTP one\r
 204             ConnectionFailed = 1001  ///< Connection with server failed\r
 205         };\r
 206 \r
 207         ////////////////////////////////////////////////////////////\r
 208         /// Default constructor\r
 209         ///\r
 210         ////////////////////////////////////////////////////////////\r
 211         Response();\r
 212 \r
 213         ////////////////////////////////////////////////////////////\r
 214         /// Get the value of a field\r
 215         ///\r
 216         /// \param Field : Name of the field to get (case-insensitive)\r
 217         ///\r
 218         /// \return Value of the field, or empty string if not found\r
 219         ///\r
 220         ////////////////////////////////////////////////////////////\r
 221         const std::string& GetField(const std::string& Field) const;\r
 222 \r
 223         ////////////////////////////////////////////////////////////\r
 224         /// Get the header's status code\r
 225         ///\r
 226         /// \return Header's status code\r
 227         ///\r
 228         ////////////////////////////////////////////////////////////\r
 229         Status GetStatus() const;\r
 230 \r
 231         ////////////////////////////////////////////////////////////\r
 232         /// Get the major HTTP version number of the response\r
 233         ///\r
 234         /// \return Major version number\r
 235         ///\r
 236         ////////////////////////////////////////////////////////////\r
 237         unsigned int GetMajorHttpVersion() const;\r
 238 \r
 239         ////////////////////////////////////////////////////////////\r
 240         /// Get the major HTTP version number of the response\r
 241         ///\r
 242         /// \return Major version number\r
 243         ///\r
 244         ////////////////////////////////////////////////////////////\r
 245         unsigned int GetMinorHttpVersion() const;\r
 246 \r
 247         ////////////////////////////////////////////////////////////\r
 248         /// Get the body of the response. The body can contain :\r
 249         /// - the requested page (for GET requests)\r
 250         /// - a response from the server (for POST requests)\r
 251         /// - nothing (for HEAD requests)\r
 252         /// - an error message (in case of an error)\r
 253         ///\r
 254         /// \return The response body\r
 255         ///\r
 256         ////////////////////////////////////////////////////////////\r
 257         const std::string& GetBody() const;\r
 258 \r
 259     private :\r
 260 \r
 261         friend class Http;\r
 262 \r
 263         ////////////////////////////////////////////////////////////\r
 264         /// Construct the header from a response string\r
 265         ///\r
 266         /// \param Data : Content of the response's header to parse\r
 267         ///\r
 268         ////////////////////////////////////////////////////////////\r
 269         void FromString(const std::string& Data);\r
 270 \r
 271         ////////////////////////////////////////////////////////////\r
 272         // Types\r
 273         ////////////////////////////////////////////////////////////\r
 274         typedef std::map<std::string, std::string> FieldTable;\r
 275 \r
 276         ////////////////////////////////////////////////////////////\r
 277         // Member data\r
 278         ////////////////////////////////////////////////////////////\r
 279         FieldTable   myFields;       ///< Fields of the header\r
 280         Status       myStatus;       ///< Status code\r
 281         unsigned int myMajorVersion; ///< Major HTTP version\r
 282         unsigned int myMinorVersion; ///< Minor HTTP version\r
 283         std::string  myBody;         ///< Body of the response\r
 284     };\r
 285 \r
 286     ////////////////////////////////////////////////////////////\r
 287     /// Default constructor\r
 288     ///\r
 289     ////////////////////////////////////////////////////////////\r
 290     Http();\r
 291 \r
 292     ////////////////////////////////////////////////////////////\r
 293     /// Construct the Http instance with the target host\r
 294     ///\r
 295     /// \param Host : Web server to connect to\r
 296     /// \param Port : Port to use for connection (0 by default -- use the standard port of the protocol used)\r
 297     ///\r
 298     ////////////////////////////////////////////////////////////\r
 299     Http(const std::string& Host, unsigned short Port = 0);\r
 300 \r
 301     ////////////////////////////////////////////////////////////\r
 302     /// Set the target host\r
 303     ///\r
 304     /// \param Host : Web server to connect to\r
 305     /// \param Port : Port to use for connection (0 by default -- use the standard port of the protocol used)\r
 306     ///\r
 307     ////////////////////////////////////////////////////////////\r
 308     void SetHost(const std::string& Host, unsigned short Port = 0);\r
 309 \r
 310     ////////////////////////////////////////////////////////////\r
 311     /// Send a HTTP request and return the server's response.\r
 312     /// You must be connected to a host before sending requests.\r
 313     /// Any missing mandatory header field will be added with an appropriate value.\r
 314     /// Warning : this function waits for the server's response and may\r
 315     /// not return instantly; use a thread if you don't want to block your\r
 316     /// application.\r
 317     ///\r
 318     /// \param Req :     Request to send\r
 319     /// \param Timeout : Maximum time to wait, in seconds (0 by default, means no timeout)\r
 320     ///\r
 321     /// \return Server's response\r
 322     ///\r
 323     ////////////////////////////////////////////////////////////\r
 324     Response SendRequest(const Request& Req, float Timeout = 0.f);\r
 325 \r
 326 private :\r
 327 \r
 328     ////////////////////////////////////////////////////////////\r
 329     // Member data\r
 330     ////////////////////////////////////////////////////////////\r
 331     SocketTCP      myConnection; ///< Connection to the host\r
 332     IPAddress      myHost;       ///< Web host address\r
 333     std::string    myHostName;   ///< Web host name\r
 334     unsigned short myPort;       ///< Port used for connection with host\r
 335 };\r
 336 \r
 337 } // namespace sf\r
 338 \r
 339 \r
 340 #endif // SFML_HTTP_HPP\r