mirror of
https://review.haiku-os.org/haiku
synced 2025-02-09 07:09:09 +01:00
25b034e99c
* Now takes ownership of headers, form data and input data * Split Set* and Adopt* methods to help with proper use of this (Set does a copy) * Write documentation.
165 lines
4.8 KiB
Plaintext
165 lines
4.8 KiB
Plaintext
/*
|
|
* Copyright 2013 Haiku, Inc. All rights reserved.
|
|
* Distributed under the terms of the MIT License.
|
|
*
|
|
* Authors:
|
|
* Adrien Destugues, pulkomandy@pulkomandy.tk
|
|
*
|
|
* Corresponds to:
|
|
* headers/os/net/HttpRequest.h rev 46234
|
|
* src/kits/network/libnetapi/HttpRequest.cpp rev 46242
|
|
*/
|
|
|
|
/*!
|
|
\file HttpRequest.h
|
|
\ingroup network
|
|
\brief Management of HTTP or HTTPS protocol requests
|
|
*/
|
|
|
|
/*!
|
|
\class BHttpRequest
|
|
\ingroup network
|
|
\brief Handles a request over HTTP or HTTPS
|
|
|
|
Instances of ths class wil lbe created by the \ref BUrlProtocolRoster for
|
|
\ref BUrl with the "http" or "https" protocol. The HTTP protocol is
|
|
implemented as specified in RFC2616. The request headers and body can be
|
|
customized, then sent to the server. The reply is then parsed and made
|
|
available to the application.
|
|
|
|
This class only implements the client-side part of HTTP, it can't be used
|
|
to build an HTTP server.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetMethod(const char* method)
|
|
\brief Set the HTTP method.
|
|
|
|
You can use either one of the standard methods (B_HTTP_GET is the default)
|
|
or a custom one. The standard methods are B_HTTP_GET, B_HTTP_POST,
|
|
B_HTTP_PUT, B_HTTP_DELETE, B_HTTP_HEAD, B_HTTP_OPTIONS, B_HTTP_TRACE and
|
|
B_HTTP_CONNECT.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetFollowLocation(bool follow)
|
|
\brief Enable or disable following HTTP redirects
|
|
|
|
An HTTP server can redirect a request to another address, either on the
|
|
same host or elseswhere. When FollowLocation is set (the default), these
|
|
redirections will be followed until an actual page (or an error) is found.
|
|
When it is unset, the redirection will not be followed and will be reported
|
|
to the client.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetMaxRedirections(int8 maxRedirections)
|
|
\brief Set the maximal number of redirections to follow before giving up
|
|
|
|
This is only useful when \ref SetFollowLocation is enabled. It will abort
|
|
the request after the given number of redirections. This avoids and helps
|
|
diagnosing redirection cycles, where two addresses redirect to each other.
|
|
|
|
The default is to follow at most 8 redirections before giving up.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetReferred(const BString& referrer)
|
|
\brief Set the referrer
|
|
|
|
The referrer is a string sent to the server in the "Referrer:" HTTP header
|
|
field. It helps the server know where the request comes from. When
|
|
following a link in an HTML page, this is usually set to the URL of that
|
|
page.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetUserAgent(const BString& userAgent)
|
|
\brief Set the user agent
|
|
|
|
The user agent is an identifier for the client sending an HTTP request.
|
|
Some servers will use this to send different content depending on the
|
|
software asking for a page.
|
|
|
|
The default user agent is "Services Kit (Haiku)".
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetHeaders(const BHttpHeaders& headers)
|
|
\brief Set the HTTP headers
|
|
|
|
This method replaces the whole set of headers for this request with a copy
|
|
of the given ones.
|
|
|
|
\param headers the header template to copy from.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::AdoptHeaders(BHttpHeaders* const headers)
|
|
\brief Set the HTTP headers
|
|
|
|
This method replaces the whole set of headers for this request. It takes
|
|
ownership of the parameter, which must not be used afterwards.
|
|
*/
|
|
|
|
/*
|
|
\fn void BHttpRequest::SetDiscardDate(bool discard)
|
|
|
|
This is currently unused.
|
|
*/
|
|
|
|
/*
|
|
\fn void BHttpRequest::DisableListener(bool disable)
|
|
This is currently unused.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetAutoReferrer(bool enable)
|
|
\brief Automatically set the referrer when the request is done.
|
|
|
|
This allows HttpRequest to manage the referrer automatically. Each request
|
|
will set the referrer to its own URL so the next request automatically
|
|
uses that one.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetPostFields(const BHttpForm& fields)
|
|
\brief Set the fields for form POST data
|
|
|
|
Replaces the content of the request with a copy of the given POST fields.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::AdoptPostFields(BHttpForm* const fields)
|
|
\brief Set the fields for form POST data
|
|
|
|
Replaces the content of the request with the given POST fields.
|
|
|
|
This method takes ownership of the given form, which must not be used
|
|
elsewhere afterwards.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::AdoptInputData(BDataIO* const data, const ssize_t size = -1)
|
|
\brief Set the request body
|
|
|
|
If the size is -1 (the default), the data will be sent using chunked
|
|
transfers. If the size is known, it will be sent using the Content-Length
|
|
header and non-chunked mode.
|
|
|
|
You should set the size whenever possible, as some servers will not handle
|
|
chunked mode properly in all cases.
|
|
|
|
This method takes ownership of the data, which must not be used elsewhere.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetUserName(const BString& userName)
|
|
\brief Set the user name for HTTP authentication.
|
|
*/
|
|
|
|
/*!
|
|
\fn void BHttpRequest::SetPassword(const BString& password)
|
|
\brief Set the user password for HTTP authentication.
|
|
*/
|