1/* 2 * Copyright 2013 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Adrien Destugues, pulkomandy@pulkomandy.tk 7 * John Scipione, jscipione@gmail.com 8 * 9 * Corresponds to: 10 * headers/private/netservices/HttpRequest.h hrev54923 11 * src/kits/network/libnetservices/HttpRequest.cpp hrev54923 12 */ 13 14 15/*! 16 \file HttpRequest.h 17 \ingroup netservices 18 \brief Management of HTTP or HTTPS protocol requests 19*/ 20 21 22/*! 23 \class BPrivate::Network::BHttpRequest 24 \ingroup netservices 25 \brief Handles a request over HTTP or HTTPS. 26 27 Instances of ths class will be created by the BUrlProtocolRoster for 28 BUrl with the "http" or "https" protocol. The HTTP protocol is 29 implemented as specified in RFC2616. The request headers and body can be 30 customized, then sent to the server. The reply is then parsed and made 31 available to the application. 32 33 This class only implements the client-side part of HTTP, it can't be used 34 to build an HTTP server. 35*/ 36 37 38/*! 39 \fn void BHttpRequest::SetMethod(const char* method) 40 \brief Set the HTTP method. 41 42 You can use either one of the standard methods (B_HTTP_GET is the default) 43 or a custom one. The standard methods are B_HTTP_GET, B_HTTP_POST, 44 B_HTTP_PUT, B_HTTP_DELETE, B_HTTP_HEAD, B_HTTP_OPTIONS, B_HTTP_TRACE and 45 B_HTTP_CONNECT. 46*/ 47 48 49/*! 50 \fn void BHttpRequest::SetFollowLocation(bool follow) 51 \brief Enable or disable following HTTP redirects. 52 53 An HTTP server can redirect a request to another address, either on the 54 same host or elsewhere. When FollowLocation is set (the default), these 55 redirections will be followed until an actual page (or an error) is found. 56 When it is unset, the redirection will not be followed and will be reported 57 to the client. 58*/ 59 60 61/*! 62 \fn void BHttpRequest::SetMaxRedirections(int8 maxRedirections) 63 \brief Set the maximal number of redirections to follow before giving up. 64 65 This is only useful when SetFollowLocation is enabled. It will abort 66 the request after the given number of redirections. This avoids and helps 67 diagnosing redirection cycles, where two addresses redirect to each other. 68 69 The default is to follow at most 8 redirections before giving up. 70*/ 71 72 73/*! 74 \fn void BHttpRequest::SetReferrer(const BString& referrer) 75 \brief Set the referrer. 76 77 The referrer is a string sent to the server in the "Referrer:" HTTP header 78 field. It helps the server know where the request comes from. When 79 following a link in an HTML page, this is usually set to the URL of that 80 page. 81*/ 82 83 84/*! 85 \fn void BHttpRequest::SetUserAgent(const BString& userAgent) 86 \brief Set the user agent. 87 88 The user agent is an identifier for the client sending an HTTP request. 89 Some servers will use this to send different content depending on the 90 software asking for a page. 91 92 The default user agent is "Services Kit (Haiku)". 93*/ 94 95 96/*! 97 \fn void BHttpRequest::SetHeaders(const BHttpHeaders& headers) 98 \brief Set the HTTP headers. 99 100 This method replaces the whole set of headers for this request with a copy 101 of the given ones. 102 103 \param headers the header template to copy from. 104*/ 105 106 107/*! 108 \fn void BHttpRequest::AdoptHeaders(BHttpHeaders* const headers) 109 \brief Set the HTTP headers. 110 111 This method replaces the whole set of headers for this request. It takes 112 ownership of the parameter, which must not be used afterwards. 113*/ 114 115 116/* 117 \fn void BHttpRequest::SetDiscardDate(bool discard) 118 119 This is currently unused. 120*/ 121 122 123/* 124 \fn void BHttpRequest::DisableListener(bool disable) 125 This is currently unused. 126*/ 127 128 129/*! 130 \fn void BHttpRequest::SetAutoReferrer(bool enable) 131 \brief Automatically set the referrer when the request is done. 132 133 This allows HttpRequest to manage the referrer automatically. Each request 134 will set the referrer to its own URL so the next request automatically 135 uses that one. 136*/ 137 138 139/*! 140 \fn void BHttpRequest::SetPostFields(const BHttpForm& fields) 141 \brief Set the fields for form POST data. 142 143 Replaces the content of the request with a copy of the given POST fields. 144*/ 145 146 147/*! 148 \fn void BHttpRequest::AdoptPostFields(BHttpForm* const fields) 149 \brief Set the fields for form POST data. 150 151 Replaces the content of the request with the given POST fields. 152 153 This method takes ownership of the given form, which must not be used 154 elsewhere afterwards. 155*/ 156 157 158/*! 159 \fn void BHttpRequest::AdoptInputData(BDataIO* const data, const ssize_t size = -1) 160 \brief Set the request body. 161 162 If the size is -1 (the default), the data will be sent using chunked 163 transfers. If the size is known, it will be sent using the Content-Length 164 header and non-chunked mode. 165 166 You should set the size whenever possible, as some servers will not handle 167 chunked mode properly in all cases. 168 169 This method takes ownership of the data, which must not be used elsewhere. 170*/ 171 172 173/*! 174 \fn void BHttpRequest::SetUserName(const BString& userName) 175 \brief Set the user name for HTTP authentication. 176*/ 177 178 179/*! 180 \fn void BHttpRequest::SetPassword(const BString& password) 181 \brief Set the user password for HTTP authentication. 182*/ 183