src/httpfetch.h

   1 /*
   2 Minetest
   3 Copyright (C) 2013 celeron55, Perttu Ahola <celeron55@gmail.com>
   4
   5 This program is free software; you can redistribute it and/or modify
   6 it under the terms of the GNU Lesser General Public License as published by
   7 the Free Software Foundation; either version 2.1 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 Lesser General Public License for more details.
  14
  15 You should have received a copy of the GNU Lesser General Public License along
  16 with this program; if not, write to the Free Software Foundation, Inc.,
  17 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  18 */
  19
  20 #pragma once
  21
  22 #include <vector>
  23 #include "util/string.h"
  24 #include "config.h"
  25
  26 // These can be used in place of "caller" in to specify special handling.
  27 // Discard result (used as default value of "caller").
  28 #define HTTPFETCH_DISCARD 0
  29 // Indicates that the result should not be discarded when performing a
  30 // synchronous request (since a real caller ID is not needed for synchronous
  31 // requests because the result does not have to be retrieved later).
  32 #define HTTPFETCH_SYNC 1
  33 // Print response body to console if the server returns an error code.
  34 #define HTTPFETCH_PRINT_ERR 2
  35 // Start of regular allocated caller IDs.
  36 #define HTTPFETCH_CID_START 3
  37
  38 //  Methods
  39 enum HttpMethod : u8
  40 {
  41         HTTP_GET,
  42         HTTP_POST,
  43         HTTP_PUT,
  44         HTTP_DELETE,
  45 };
  46
  47 struct HTTPFetchRequest
  48 {
  49         std::string url = "";
  50
  51         // Identifies the caller (for asynchronous requests)
  52         // Ignored by httpfetch_sync
  53         u64 caller = HTTPFETCH_DISCARD;
  54
  55         // Some number that identifies the request
  56         // (when the same caller issues multiple httpfetch_async calls)
  57         u64 request_id = 0;
  58
  59         // Timeout for the whole transfer, in milliseconds
  60         long timeout;
  61
  62         // Timeout for the connection phase, in milliseconds
  63         long connect_timeout;
  64
  65         // Indicates if this is multipart/form-data or
  66         // application/x-www-form-urlencoded.  POST-only.
  67         bool multipart = false;
  68
  69         //  The Method to use default = GET
  70         //  Avaible methods GET, POST, PUT, DELETE
  71         HttpMethod method = HTTP_GET;
  72
  73         // Fields of the request
  74         StringMap fields;
  75
  76         // Raw data of the request overrides fields
  77         std::string raw_data;
  78
  79         // If not empty, should contain entries such as "Accept: text/html"
  80         std::vector<std::string> extra_headers;
  81
  82         // useragent to use
  83         std::string useragent;
  84
  85         HTTPFetchRequest();
  86 };
  87
  88 struct HTTPFetchResult
  89 {
  90         bool succeeded = false;
  91         bool timeout = false;
  92         long response_code = 0;
  93         std::string data = "";
  94         // The caller and request_id from the corresponding HTTPFetchRequest.
  95         u64 caller = HTTPFETCH_DISCARD;
  96         u64 request_id = 0;
  97
  98         HTTPFetchResult() = default;
  99
 100         HTTPFetchResult(const HTTPFetchRequest &fetch_request) :
 101                         caller(fetch_request.caller), request_id(fetch_request.request_id)
 102         {
 103         }
 104 };
 105
 106 // Initializes the httpfetch module
 107 void httpfetch_init(int parallel_limit);
 108
 109 // Stops the httpfetch thread and cleans up resources
 110 void httpfetch_cleanup();
 111
 112 // Starts an asynchronous HTTP fetch request
 113 void httpfetch_async(const HTTPFetchRequest &fetch_request);
 114
 115 // If any fetch for the given caller ID is complete, removes it from the
 116 // result queue, sets the fetch result and returns true. Otherwise returns false.
 117 bool httpfetch_async_get(u64 caller, HTTPFetchResult &fetch_result);
 118
 119 // Allocates a caller ID for httpfetch_async
 120 // Not required if you want to set caller = HTTPFETCH_DISCARD
 121 u64 httpfetch_caller_alloc();
 122
 123 // Allocates a non-predictable caller ID for httpfetch_async
 124 u64 httpfetch_caller_alloc_secure();
 125
 126 // Frees a caller ID allocated with httpfetch_caller_alloc
 127 // Note: This can be expensive, because the httpfetch thread is told
 128 // to stop any ongoing fetches for the given caller.
 129 void httpfetch_caller_free(u64 caller);
 130
 131 // Performs a synchronous HTTP request. This blocks and therefore should
 132 // only be used from background threads.
 133 void httpfetch_sync(const HTTPFetchRequest &fetch_request, HTTPFetchResult &fetch_result);