Haiku/haiku
Haiku/haiku
1
0
Fork 0
mirror of https://review.haiku-os.org/haiku synced 2024-11-23 07:18:40 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

HaikuBook: Prepare for newer Network Services Kit docs

Browse Source 
Change-Id: Ib2cc458f9121cb78250a643affc0933512e65bc8
This commit is contained in:
Niels Sascha Reedijk 2021-09-12 07:12:53 +01:00
parent bcd6a663c2
commit f54a5a68d7
13 changed files with 14 additions and 2024 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/user/Doxyfile
View File

@ -856,15 +856,7 @@ INPUT = . \
../../headers/os/support \
../../headers/os/translation \
../../headers/posix/syslog.h \
../../src/kits/game/GameProducer.h \
../../headers/private/netservices/Geolocation.h \
../../headers/private/netservices/HttpAuthentication.h \
../../headers/private/netservices/HttpForm.h \
../../headers/private/netservices/HttpHeaders.h \
../../headers/private/netservices/HttpRequest.h \
../../headers/private/netservices/UrlProtocolAsynchronousListener.h \
../../headers/private/netservices/UrlProtocolListener.h \
../../headers/private/netservices/UrlProtocolRoster.h
../../src/kits/game/GameProducer.h
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

15
docs/user/book.dox
View File

@ -607,15 +607,22 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
\defgroup json Json Handling
\brief Provides for parsing and writing of data in Json encoding.
*/
#if __cplusplus >= 201703L
/*!
\defgroup netservices Experimental Network Services Support
\brief Experimental API to do higher level network requests
This API currently is marked as experimental. It is part of the
<code>BPrivate::Network</code> namespace, the header files are found at
<code>headers\\private\\netservices</code>, and you have to link your
application to <code>libnetservices.a</code>.
<code>headers\\private\\netservices2</code>, and you have to link your
application to <code>libnetservices2.a</code>. The new API is only
available for modern platforms (x86 and x86_64), and not for the legacy
platform (x86_gcc2). The compiler needs to support C++17 or higher.
*/
#endif
///// Namespace Documentation /////
@ -623,6 +630,8 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE);
//! \brief Internal or experimental API
namespace BPrivate {
#if __cplusplus >= 201703L
/*!
\brief Experimental Network Services API
@ -631,4 +640,6 @@ namespace BPrivate {
namespace Network {
}
#endif
}

341
docs/user/net/UrlProtocolDispatchingListener.dox
View File

@ -1,341 +0,0 @@
/*
* Copyright 2020 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Leorize, leorize+oss@disroot.org
*
* Corresponds to:
* headers/os/net/UrlProtocolDispatchingListener.h hrev54384
* src/kits/network/libnetapi/UrlProtocolDispatchingListener.cpp hrev54384
*/
/*!
\file UrlProtocolDispatchingListener.h
\ingroup network
\brief Provides the BUrlProtocolDispatchingListener class.
*/
/*!
\var B_URL_PROTOCOL_NOTIFICATION
\brief The \c what constant for BMessage emitted by
BUrlProtocolDispatchingListener.
*/
/*!
\var B_URL_PROTOCOL_CONNECTION_OPENED
\brief The type of message emitted by
BUrlProtocolDispatchingListener::ConnectionOpened().
*/
/*!
\var B_URL_PROTOCOL_HOSTNAME_RESOLVED
\brief The type of message emitted by
BUrlProtocolDispatchingListener::HostnameResolved().
*/
/*!
\var B_URL_PROTOCOL_RESPONSE_STARTED
\brief The type of message emitted by
BUrlProtocolDispatchingListener::ResponseStarted().
*/
/*!
\var B_URL_PROTOCOL_HEADERS_RECEIVED
\brief The type of message emitted by
BUrlProtocolDispatchingListener::HeadersReceived().
*/
/*!
\var B_URL_PROTOCOL_DATA_RECEIVED
\brief The type of message emitted by
BUrlProtocolDispatchingListener::DataReceived().
*/
/*!
\var B_URL_PROTOCOL_DOWNLOAD_PROGRESS
\brief The type of message emitted by
BUrlProtocolDispatchingListener::DownloadProgress().
*/
/*!
\var B_URL_PROTOCOL_UPLOAD_PROGRESS
\brief The type of message emitted by
BUrlProtocolDispatchingListener::UploadProgress().
*/
/*!
\var B_URL_PROTOCOL_REQUEST_COMPLETED
\brief The type of message emitted by
BUrlProtocolDispatchingListener::RequestCompleted().
*/
/*!
\var B_URL_PROTOCOL_CERTIFICATE_VERIFICATION_FAILED
\brief The type of message emitted by
BUrlProtocolDispatchingListener::CertificateVerificationFailed().
*/
/*!
\var B_URL_PROTOCOL_DEBUG_MESSAGE
\brief The type of message emitted by
BUrlProtocolDispatchingListener::DebugMessage().
*/
/*!
\class BUrlProtocolDispatchingListener
\ingroup network
\brief Dispatches BUrlProtocolListener events as BMessage.
BUrlProtocolDispatchingListener is a BUrlProtocolListener implementation
that dispatches received events as BMessage. A corresponding
BHandler implementation that make use of BUrlProtocolListener hooks
to handle messages emitted by this class is available as
BUrlProtocolAsynchronousListener.
BMessage emitted from this class use the code #B_URL_PROTOCOL_NOTIFICATION.
Refer to each member functions for the format of the messages they emit.
<table>
<caption>The format of the emitted message</caption>
<tr>
<th>Field name</th>
<th>Type</th>
<th>Value</th>
</tr>
<tr>
<td>be:urlProtocolCaller</td>
<td>\c B_POINTER_TYPE</td>
<td>\a The request that generated the event</td>
</tr>
<tr>
<td>be:urlProtocolMessageType</td>
<td>\c B_INT8_TYPE</td>
<td>The message type, one of the B_URL_PROTOCOL_* constants</td>
</tr>
</table>
Messages for specific events may include extra fields, documented in the
description of each of the hook methods, and usually matching the parameters
of that method.
*/
/*!
\fn virtual void BUrlProtocolDispatchingListener::ConnectionOpened(
BUrlRequest* caller)
\brief Emit a message when the socket is opened.
*/
/*!
\fn virtual void BUrlProtocolDispatchingListener::HostnameResolved(
BUrlRequest* caller, const char* ip)
\brief Emit a message when the final IP is discovered.
<table>
<caption>The format of the emitted message</caption>
<tr>
<th>Field name</th>
<th>Field type</th>
<th>Value</th>
</tr>
<tr>
<td>url:hostIp</td>
<td>\c B_STRING_TYPE</td>
<td>\a ip</td>
</tr>
</table>
*/
/*!
\fn virtual void BUrlProtocolDispatchingListener::ResponseStarted(
BUrlRequest* caller)
\brief Emit a message when the server begins to reply.
*/
/*!
\fn virtual void BUrlProtocolDispatchingListener::HeadersReceived(
BUrlRequest* caller, const BUrlResult& result);
\brief Emit a message when all of the response metadata is made available.
<table>
<caption>The format of the emitted message</caption>
<tr>
<th>Field name</th>
<th>Field type</th>
<th>Value</th>
</tr>
<tr>
<td>url:result</td>
<td>\c B_MESSAGE_TYPE</td>
<td>
An archived copy of \a result. BUrlResult(BMessage*) can be
used to create a new BUrlResult from the received BMessage.
</td>
</tr>
</table>
*/
/*!
\fn virtual void BUrlProtocolDispatchingListener::DownloadProgress(
BUrlRequest* caller, off_t bytesReceived, off_t bytesTotal)
\brief Emit a message each time a block of data is received.
This message will usually be emitted after DataReceived().
<table>
<caption>The format of the emitted message</caption>
<tr>
<th>Field name</th>
<th>Field type</th>
<th>Value</th>
</tr>
<tr>
<td>url:bytesReceived</td>
<td>\c B_INT64_TYPE</td>
<td>\a bytesReceived</td>
</tr>
<tr>
<td>url:bytesTotal</td>
<td>\c B_INT64_TYPE</td>
<td>\a bytesTotal</td>
</tr>
</table>
*/
/*!
\fn virtual void BUrlProtocolDispatchingListener::UploadProgress(
BUrlRequest* caller, off_t bytesSent, off_t bytesTotal)
\brief Emit a message each time a block of data is sent.
<table>
<caption>The format of the emitted message</caption>
<tr>
<th>Field name</th>
<th>Field type</th>
<th>Value</th>
</tr>
<tr>
<td>url:bytesSent</td>
<td>\c B_INT64_TYPE</td>
<td>\a bytesSent</td>
</tr>
<tr>
<td>url:bytesTotal</td>
<td>\c B_INT64_TYPE</td>
<td>\a bytesTotal</td>
</tr>
</table>
*/
/*!
\fn virtual void BUrlProtocolDispatchingListener::RequestCompleted(
BUrlRequest* caller, bool success)
\brief Emit a message once the request is complete.
<table>
<caption>The format of the emitted message</caption>
<tr>
<th>Field name</th>
<th>Type</th>
<th>Value</th>
</tr>
<tr>
<td>url:success</td>
<td>\c B_BOOL_TYPE</td>
<td>\a success</td>
</tr>
</table>
*/
/*!
\fn virtual void BUrlProtocolDispatchingListener::DebugMessage(BUrlRequest* caller,
BUrlProtocolDebugMessage type, const char* text)
\brief Emit a message with debugging information.
These messages are useful for tracing and analyzing requests sent and
responses received. They can be printed to the standard output, directed to
a log file, or simply ignored.
<table>
<caption>The format of the emitted message</caption>
<tr>
<th>Field name</th>
<th>Type</th>
<th>Value</th>
</tr>
<tr>
<td>url:type</td>
<td>\c B_INT32_TYPE</td>
<td>\a type</td>
</tr>
<tr>
<td>url:text</td>
<td>\c B_STRING_TYPE</td>
<td>\a text</td>
</tr>
</table>
*/
/*!
\fn virtual bool BUrlProtocolDispatchingListener::CertificateVerificationFailed(
BUrlRequest* caller, BCertificate& certificate, const char* message
)
\brief Emit a message when cerificate verification failed.
This event is triggered when a certificate failed verification, for example
because it has expired, or because the signing authority is not trusted.
The user should be informed of the problem, but may decide to continue the
request anyway.
<table>
<caption>The format of the emitted message</caption>
<tr>
<th>Field name</th>
<th>Type</th>
<th>Value</th>
</tr>
<tr>
<td>url:error</td>
<td>\c B_STRING_TYPE</td>
<td>\a message</td>
</tr>
<tr>
<td>url:certificate</td>
<td>\c B_POINTER_TYPE</td>
<td>Pointer to the \a certificate to be validated</td>
</tr>
</table>
This message expects a reply from the handler.
<table>
<caption>The expected format of the reply</caption>
<tr>
<th>Field name</th>
<th>Type</th>
<th>Value</th>
</tr>
<tr>
<td>url:continue</td>
<td>\c B_BOOL_TYPE</td>
<td>
\a true if the request should be continued, \a false otherwise.
</td>
</tr>
</table>
*/

266
docs/user/net/UrlRequest.dox
View File

@ -1,266 +0,0 @@
/*
* Copyright 2020 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Leorize, leorize+oss@disroot.org
*
* Corresponds to:
* headers/os/net/UrlRequest.h hrev54384
* src/kits/network/libnetapi/UrlRequest.cpp hrev54384
*/
/*!
\file UrlRequest.h
\ingroup network
\brief Provides the BUrlRequest class.
*/
/*!
\class BUrlRequest
\ingroup network
\brief Base class for URL request handlers.
*/
/*!
\fn BUrlRequest::BUrlRequest(const BUrl& url,
BUrlProtocolListener* listener, BUrlContext* context,
const char* threadName, const char* protocolName)
\brief Create a BUrlRequest object.
This constructor is only relevant to implementors of the interface. Users
wishing to create a request should refer to implementations like
BHttpRequest or BUrlProtocolRoster::MakeRequest().
\param url The URL in which resources will be requested from.
\param listener Pointer to a BUrlProtocolListener object for handling
events raised during the request. Can be \c NULL.
\param context Pointer to a BUrlContext. If \c NULL, a program-wide
context will be used instead.
\param threadName The name of the thread that will be spawned on Run().
\param protocolName The name of the protocol handled by this BUrlRequest.
*/
/*!
\fn virtual BUrlRequest::~BUrlRequest()
\brief The default destructor for BUrlRequest.
This destructor will Stop() the request (if running) and release resources
held by the object.
Since the destructor will only call the base version of Stop(), and not overriden methods,
implementations for each protocol must override this destructor to ensure that they do stop
all activity from the request. In particular, any spawned thread must be stopped before
the object is destroyed.
*/
/*!
\fn virtual thread_id BUrlRequest::Run()
\brief Start the request.
\returns The thread id of the request if successful, an error code
otherwise.
For implementors, this base method will create a thread using
_ThreadEntry() as the entry point and fThreadName for the name of the
thread. The created thread id will be stored in fThreadId. fRunning
will then be set to \c true.
Most implementations shouldn't have to reimplement this method.
*/
/*!
\fn virtual status_t BUrlRequest::Stop()
\brief Stop the request.
This method does not guarantee that the request will be stopped on return.
Users should wait for BUrlProtocolListener::RequestCompleted() as a
confirmation that the request has stopped before destroying the object.
The base implementation of this method does nothing but set #fQuit to
\c true.
\retval B_OK Operation successful.
\retval B_ERROR The request is not running.
*/
/*!
\fn virtual void SetTimeout(bigtime_t timeout)
\brief Set the request transfer timeout.
\note By default no timeout will be applied unless it was set with this
method.
\param timeout The amount of time in microseconds should the request be
idle (no data received from the server) before dropping out.
The base implementation of this method is a no-op.
*/
/*!
\fn status_t BUrlRequest::SetUrl(const BUrl& url)
\brief Change the URL of the request.
\param url The new URL to request from.
This must be done before starting the request with Run. It is not possible
to change the URL while the request is running.
\retval B_OK Operation successful.
\retval B_ERROR The request is running.
\sa Url() for retrieving the request URL.
*/
/*!
\fn status_t BUrlRequest::SetContext(BUrlContext* context)
\brief Change the context of the request.
\param context The pointer to a BUrlContext.
This must be done before starting the request with Run. It is not possible
to change the context while the request is running.
\note Setting the \a context to \c NULL will use the program-wide default
context. This is the default also for requests where SetContext was
never called.
\retval B_OK Operation successful.
\retval B_ERROR The request is running.
\sa Context()
*/
/*!
\fn status_t BUrlRequest::SetListener(BUrlProtocolListener* listener)
\brief Change the BUrlProtocolListener of the request.
\param listener Pointer to the new listener object. Can be \c NULL.
\retval B_OK Operation successful.
\retval B_ERROR The request is running.
\sa Listener()
*/
/*!
\fn const BUrl& BUrlRequest::Url() const
\brief Get the URL of the request.
\sa SetUrl()
*/
/*!
\fn BUrlContext* BUrlRequest::Context() const
\brief Get the context of the request.
\sa SetContext()
*/
/*!
\fn BUrlProtocolListener* BUrlRequest::Listener() const
\brief Get the BUrlProtocolListener of the request.
\sa SetListener()
*/
/*!
\fn const BString& BUrlRequest::Protocol() const
\brief Get the protocol that this object handles.
*/
/*!
\fn bool BUrlRequest::IsRunning() const
\brief Whether the request thread is running.
*/
/*!
\fn status_t BUrlRequest::Status() const
\brief Get the status of the request.
\retval B_OK The request has completed successfully.
\retval B_BUSY The request is running.
\retval B_INTERRUPTED The request was cancelled.
These are not the only errors that can be returned. The exact list
depends on the implementation of this class.
*/
/*!
\fn virtual const BUrlResult& BUrlRequest::Result() const = 0
\brief Get the BUrlResult associated with the request.
*/
/*!
\fn static int32 BUrlRequest::_ThreadEntry(void* arg)
\brief The default entry point for threads spawned via Run()
\param arg The pointer to the BUrlRequest that invoked Run().
This static method will do the following:
- Set the Status() to \c B_BUSY.
- Call _ProtocolSetup().
- Call _ProtocolLoop(). The return value of this method will be set
as the Status().
- If a valid listener is registered, this method calls
BUrlProtocolListener::RequestCompleted() to signify completion.
This alone should be adequete for most protocol implementations.
*/
/*!
\fn virtual void BUrlRequest::_ProtocolSetup()
\brief Setup the object state before entering the thread loop.
The base implementation is a no-op.
*/
/*!
\fn virtual status_t BUrlRequest::_ProtocolLoop() = 0
\brief The thread loop that process the request.
This method implements the main processing logic. The return value of this
method will be set as Status().
Implementations of this method should check #fQuit periodically as a flag to
stop the request, and should implement Stop() in a way that blocking calls
within the request can be interrupted. It's preferable that the request
can be stopped as soon as it's signalled.
*/
/*!
\fn virtual void BUrlRequest::_EmitDebug(BUrlProtocolDebugMessage type,
const char* format, ...)
\brief Emit a debug message.
If a listener is registered, this method invokes
BUrlProtocolListener::DebugMessage() with the formatted message.
\param type The type of the debug message.
\param format The format string. This should a printf-compatible format
string.
\param ... Arguments to be formatted.
*/

119
docs/user/net/UrlResult.dox
View File

@ -1,119 +0,0 @@
/*
* Copyright 2020 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Leorize, leorize+oss@disroot.org
*
* Corresponds to:
* headers/os/net/UrlResult.h hrev54384
* src/kits/network/libnetapi/UrlResult.cpp hrev54384
*/
/*!
\file UrlResult.h
\ingroup network
\brief Provides the BUrlResult class.
*/
/*!
\class BUrlResult
\ingroup network
\brief The result of a request made with BUrlRequest.
This class contains the metadata acquired during a request made
with BUrlRequest.
Note that subclasses are usually defined with protocol-specific information.
For example see BHttpResult for the result of a request using the HTTP
protocol.
*/
/*!
\fn BUrlResult::BUrlResult()
\brief Create an uninitialized BUrlResult object.
*/
/*!
\fn BUrlResult::BUrlResult(BMessage* archive)
\brief Create a BUrlResult object from a BMessage.
\param archive The BMessage used to construct the object.
\note Instantiate() should be used instead to verify whether the BMessage
can be used to construct the object.
*/
/*!
\fn virtual status_t BUrlResult::Archive(BMessage* archive, bool deep) const
\brief Archive the object into a BMessage.
\param archive Pointer to the BMessage object to archive into.
\param deep If \c true, all children of this object should be archived as
well.
\retval B_OK The operation was successful.
\retval B_BAD_VALUE \a archive was \c NULL.
\retval B_ERROR An error occurred.
\sa Instantiate() for construcing the object from the archived BMessage.
*/
/*!
\fn void BUrlResult::SetContentType(BString contentType)
\brief Set the content type of the response.
This method is used by a BUrlRequest object to set the content type
of the response. The content type should be a valid MIME type.
\param contentType The content type to set to.
\sa ContentType() for retrieving the set content type.
*/
/*!
\fn void BUrlResult::SetLength(size_t length)
\brief Set the length of the response.
This method is used by a BUrlRequest object to set the length of
the response.
\param length The length to set to.
\sa Length() for retrieving the set length.
*/
/*!
\fn virtual BString BUrlResult::ContentType() const
\brief Get the MIME type of the response contents.
\sa SetContentType() for setting the content type to be returned by this
method.
*/
/*!
\fn virtual size_t BUrlResult::Length() const
\brief Get the length of the response.
\sa SetLength() for setting the length to be returned by this method.
*/
/*!
\fn static BArchivable* BUrlResult::Instantiate(BMessage* archive)
\brief Create a BUrlResult object from a BMessage.
\param archive The BMessage to construct a BUrlResult from.
\returns A pointer to the created BUrlResult, or \c NULL if unarchival
failed.
*/

89
docs/user/netservices/Geolocation.dox
View File

@ -1,89 +0,0 @@
/*
* Copyright 2019 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Adrien Destugues, pulkomandy@pulkomandy.tk
*
* Corresponds to:
* headers/private/netservices/Geolocation.h hrev54923
* src/kits/network/libnetservices/Geolocation.cpp hrev54923
*/
/*!
\file Geolocation.h
\ingroup netservices
\brief Geolocation and geocoding services.
*/
/*!
\class BPrivate::Network::BGeolocation
\ingroup netservices
\brief Geolocation and geocoding services.
Geolocation allows to know where the computer is currently located.
This is currently done by sending a list of Wifi networks within reach to
a 3rd party webservice (Mozilla location services), which uses a database
of known networks around the world to return an estimate position.
Geocoding is about identifying places in a way more convenient than
latitude and longitude. This can include postal codes, country names,
street or building names, etc. This class allows to perform both geocoding
(finding a latitude and a longitude from a name) and reverse geocoding
(finding a suitable name for a given position). This service is provided
to haiku by the 3rd-party geonames.org
Note that most of the methods in this class perform HTTPS requests to
3rd-parties. When using it in your application, it is good practise to
first inform the user about what will be shared with these services, and
why that's needed. Of course, this also means using these services requires
internet access, and you may want to limit the number of calls, both to
save bandwidth and time, and to not overuse the provided API keys. If you
are going to do more than a few request per application run, you should
provide your own API keys instead.
\since Haiku R1
*/
/*!
\fn BGeolocation::BGeolocation()
\brief Initialize a BGeolocation using the default services and API keys.
Official builds of Haiku include a shared API key for both Mozilla Location
Services and geonames.org. You can use this constructor to use these keys
in your application.
*/
/*!
\fn BGeolocation::BGeolocation(const BUrl& geolocationService,
const BUrl& geocodingService)
\brief Initialize a BGeolocation using custom services or API keys.
You can use this constructor to provide your own URL to a webservice to
use for the requests. The services have to implement the MLS and geonames
API, respectively.
If you want to override only one of the two URLs, the other can be passed
as an empty BUrl object.
*/
/*!
\fn status_t BGeolocation::LocateSelf(float& latitude, float& longitude)
\brief Locate the computer by detecting nearby WiFi networks.
This method makes a request to Mozilla Location Services.
*/
/*!
\fn status_t BGeolocation::Country(float latitude, float longitude,
BCountry& country)
\brief Find which country a given set of coordinates is in.
This method makes a request to geonames.org.
*/

117
docs/user/netservices/HttpAuthentication.dox
View File

@ -1,117 +0,0 @@
/*
* Copyright 2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Adrien Destugues, pulkomandy@pulkomandy.tk
*
* Corresponds to:
* headers/private/netservices/HttpAuthentication.h hrev54923
* src/kits/network/libnetservices/HttpAuthentication.cpp hrev54923
*/
/*!
\file HttpAuthentication.h
\ingroup netservices
\brief Authentication token for use in HTTP protocol communications.
*/
/*!
\class BPrivate::Network::BHttpAuthentication
\ingroup netservices
\brief Authentication token for the HTTP protocol.
This class allows managing of an authenticated http session. It stores the
authentication credentials and realm and provides tools for generating the
required nonces and hashes.
An instance of this class should be used for the whole length of an HTTP
authenticated session. Initialize it by calling Initialize() and setting the
username and password (from the constructor or the setter methods). Then,
for each page that requires authentication, generate a token using the
Authorization() method.
*/
/*!
\fn BHttpAuthentication::BHttpAuthentication()
\brief Default constructor.
This will create an unconfigured authentication object with the
authentication method set to B_HTTP_AUTHENTICATION_NONE.
You have to set the username and password, and initialize the object using
the Initialize method with proper authentication data.
*/
/*!
\fn BHttpAuthentication::BHttpAuthentication(const BString& username,
const BString& password)
\brief Create an authentication session with the given name and password.
The authentication method is set to B_HTTP_AUTHENTICATION_NONE.
This object can then be used with the Initialize method to bind it to an
HTTP authenticated session.
*/
/*!
\fn void BHttpAuthentication::SetUserName(const BString& username)
\brief Set the user name.
\param username the new user name.
*/
/*!
\fn void BHttpAuthentication::SetPassword(const BString& password)
\brief Set the password
\param password the new password.
*/
/*!
\fn void BHttpAuthentication::SetMethod(BHttpAuthenticationMethod method)
\brief Set the authentication method
\param method the new authentication method.
*/
/*!
\fn status_t BHttpAuthentication::Initialize(const BString& wwwAuthenticate)
\brief Initialize the object from the given authentication data
This method will parse the given authentication challenge and initialize
the authentication type to either B_HTTP_AUTHENTICATION_BASIC or
B_HTTP_AUTHENTICATION_DIGEST. The authentication parameters (realm, nonce,
algorithm) and state (opaque, stale) are also parsed and stored.
\param wwwAuthenticate the value of the WWW-Authenticate HTTP header field.
\return B_OK if the request was parsed, B_ERROR if there is a parsing error,
B_BAD_VALUE if the authentication string is empty.
*/
/*!
\fn const BString& BHttpAuthentication::UserName() const
\returns the user name.
*/
/*!
\fn const BString& BHttpAuthentication::Password() const
\returns the password.
*/
/*!
\fn BHttpAuthenticationMethod BHttpAuthentication::Method() const
\returns the authentication method
*/
/*!
\fn BString BHttpAuthentication::Authorization(const BUrl& url,
const BString& method) const
\brief Generate an authentication reply for the given URL and method.
For basic authentication, the reply is constant and is a Base64 encoding of
the string made of 'username:password'. In digest mode, each request will
have a different reply, so you must call this method for each page you want
to authenticate with.
\return the generated reply
*/

405
docs/user/netservices/HttpForm.dox
View File

@ -1,405 +0,0 @@
/*
* Copyright 2010-2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Adrien Destugues, pulkomandy@pulkomandy.tk
* John Scipione, jscipione@gmail.com
*
* Corresponds to:
* headers/private/netservices/HttpForm.h hrev54923
* src/kits/network/libnetservices/HttpForm.cpp hrev54923
*/
/*!
\file HttpForm.h
\ingroup netservices
\brief Management of HTTP form data
*/
/*!
\enum BPrivate::Network::form_type
\ingroup netservices
*/
/*!
\var form_type B_HTTP_FORM_URL_ENCODED
*/
/*!
\var form_type B_HTTP_FORM_MULTIPART
*/
/*!
\enum BPrivate::Network::form_content_type
\ingroup netservices
*/
/*!
\var form_content_type B_HTTPFORM_UNKNOWN
*/
/*!
\var form_content_type B_HTTPFORM_STRING
*/
/*!
\var form_content_type B_HTTPFORM_FILE
*/
/*!
\var form_content_type B_HTTPFORM_BUFFER
*/
/*!
\class BPrivate::Network::BHttpFormData
\ingroup netservices
\brief Stores a form data entry sent or received during an HTTP request.
Each element in a form is stored in an instance of this class. The values
can be either strings, arbitrary binary buffers, or a pointer to a file.
The latter allows reading data from the file as it is being sent through
the network, removing hte need to buffer the whole file contents in memory.
*/
/*!
\fn BHttpFormData::BHttpFormData(const BString& name, const BString& value)
\brief Construct a BHttpFormData object with a string value.
*/
/*!
\fn BHttpFormData::BHttpFormData(const BString& name, const BPath& file)
\brief Construct a BHttpFormData object which value is a file contents
*/
/*!
\fn BHttpFormData::BHttpFormData(const BString& name, const void* buffer,
ssize_t size)
\brief Construct a BHttpFormData object which value is a binary buffer.
*/
/*!
\fn bool BHttpFormData::InitCheck() const
\brief Checks the initialization of the object
\return \c false if attempting to construct a BHttpFormData with a \c NULL
buffer.
*/
/*!
\fn const BString& BHttpFormData::Name() const
\brief Get the form field name
*/
/*!
\fn const BString& BHttpFormData::String() const
\brief Get the string value of a form field.
\return An empty string for buffer and file based fields.
*/
/*!
\fn const BPath& BHttpFormData::File() const
\brief Get the file path of a form field.
\return An empty string for buffer and string based fields.
*/
/*!
\fn const void* BHttpFormData::Buffer() const
\brief Get a pointer to the data of a form field.
\return An empty string for string and file based fields
*/
/*!
\fn ssize_t BHttpFormData::BufferSize() const;
\brief Get the buffer size
\return 0 for string and file based fields.
*/
/*!
\fn bool BHttpFormData::IsFile() const
\return \c true if the field data is a file.
*/
/*!
\fn const BString& BHttpFormData::Filename() const;
\return The name of the file, for file based fields.
*/
/*!
\fn const BString& BHttpFormData::MimeType() const
\return The MIME type of the data.
*/
/*!
\fn form_content_type BHttpFormData::Type() const
\return The kind of field.
*/
/*!
\fn status_t BHttpFormData::CopyBuffer()
\brief Make a copy of the internal buffer
The constructor for buffer-based fields does not copy the data given to it,
it just keeps a pointer. If you want to retain ownership of the data, call
this method so the buffer copies and releases it.
*/
/*!
\fn status_t BHttpFormData::MarkAsFile(const BString& filename,
const BString& mimeType)
\brief Mark a field as a file.
*/
/*!
\fn void BHttpFormData::UnmarkAsFile()
\brief Unmark a field as a file.
*/
/*!
\fn status_t BHttpFormData::CopyBuffer()
*/
/*!
\fn BHttpFormData& BHttpFormData::operator=(const BHttpFormData& other)
\brief Assignment operator.
*/
/*!
\class BPrivate::Network::BHttpForm
\ingroup netservices
\brief Container for all the BHttpFormData instances making up an HTTP form contents.
*/
/*!
\fn BHttpForm::BHttpForm()
\brief Create a new form object.
*/
/*!
\fn BHttpForm::BHttpForm(const BHttpForm& other)
\brief Create a new form object as a copy of \a other.
*/
/*!
\fn BHttpForm::BHttpForm(const BString& formString)
\brief Create a new form object and parse the \a formString.
*/
/*!
\fn BHttpForm::~BHttpForm()
\brief Clear the form and destroy the form object.
*/
/*!
\fn void BHttpForm::ParseString(const BString& formString)
\brief Parse the \a formString.
*/
/*!
\fn BString BHttpForm::RawData() const
\brief Return the form's raw data as a BString.
*/
/*!
\fn status_t BHttpForm::AddString(const BString& fieldName,
const BString& value)
\brief Add a string to the form with the specified \a fieldName and \a value.
*/
/*!
\fn status_t BHttpForm::AddInt(const BString& fieldName, int32 value)
\brief Add an int to the form with the specified \a fieldName and \a value.
*/
/*!
\fn status_t BHttpForm::AddFile(const BString& fieldName, const BPath& file)
\brief Add a file to the form with the specified \a fieldName and \a value.
*/
/*!
\fn status_t BHttpForm::AddBuffer(const BString& fieldName,
const void* buffer, ssize_t size)
\brief Add a buffer to the form with the specified \a fieldName and \a buffer
and \a size.
*/
/*!
\fn status_t BHttpForm::AddBufferCopy(const BString& fieldName,
const void* buffer, ssize_t size)
*/
/*!
\fn void BHttpForm::MarkAsFile(const BString& fieldName,
const BString& filename, const BString& mimeType)
*/
/*!
\fn void BHttpForm::MarkAsFile(const BString& fieldName,
const BString& filename)
\brief Mark a field as a filename.
*/
/*!
\fn void BHttpForm::UnmarkAsFile(const BString& fieldName)
\brief Unmark a field as a filename.
*/
/*!
\fn void BHttpForm::SetFormType(form_type type)
\brief Change form type.
*/
/*!
\fn bool BHttpForm::HasField(const BString& name) const
\brief Returns whether or not a form has a field with the specified \a name.
*/
/*!
\fn BString BHttpForm::GetMultipartHeader(const BString& fieldName) const
*/
/*!
\fn form_type BHttpForm::GetFormType() const
*/
/*!
\fn const BString& BHttpForm::GetMultipartBoundary() const
*/
/*!
\fn BString BHttpForm::GetMultipartFooter() const
*/
/*!
\fn ssize_t BHttpForm::ContentLength() const
*/
/*!
\fn BHttpForm::Iterator BHttpForm::GetIterator()
*/
/*!
\fn void BHttpForm::Clear()
*/
/*!
\fn BHttpFormData& BHttpForm::operator[](const BString& name)
*/
/*!
\fn void BHttpForm::_ExtractNameValuePair(const BString& formString, int32* index)
*/
/*!
\fn void BHttpForm::_GenerateMultipartBoundary()
*/
/*!
\fn void BHttpForm::Clear()
*/
/*!
\class BPrivate::Network::BHttpForm::Iterator
\ingroup netservices
\brief Form Iterator.
*/
/*!
\fn BHttpForm::Iterator::Iterator(BHttpForm* form)
\brief Constructor.
*/
/*!
\fn BHttpForm::Iterator::Iterator(const Iterator& other);
\brief Copy contstructor.
*/
/*!
\fn bool BHttpForm::Iterator::HasNext() const
*/
/*!
\fn BHttpFormData* BHttpForm::Iterator::Next()
*/
/*!
\fn void BHttpForm::Iterator::Remove()
*/
/*!
\fn BString BHttpForm::Iterator::MultipartHeader()
*/
/*!
\fn BHttpForm::Iterator& BHttpForm::Iterator::operator=(const Iterator& other)
\brief Assignment operator.
*/

182
docs/user/netservices/HttpHeaders.dox
View File

@ -1,182 +0,0 @@
/*
* Copyright 2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Adrien Destugues, pulkomandy@pulkomandy.tk
*
* Corresponds to:
* headers/private/netservices/HttpHeaders.h hrev54923
* src/kits/network/libnetservices/HttpHeaders.cpp hrev54923
*/
/*!
\file HttpHeaders.h
\ingroup netservices
\brief Management of HTTP headers
*/
/*!
\class BPrivate::Network::BHttpHeader
\ingroup netservices
\brief Represent a single header field for an HTTP connection
HTTP headers are key-value pairs, where both the key and the value are
strings. The main purpose of this class is storing the pair and encoding it
to the HTTP protocol format, where some characters have to be escaped.
*/
/*!
\fn BHttpHeader::BHttpHeader()
\brief Default constructor.
The header is initialized with empty key and value.
*/
/*!
\fn BHttpHeader::BHttpHeader(const char* string)
\brief Construct a BHttpHeader from an already encoded string
The given string should be in the form "key:value" with all special
characters properly escaped. There is no way to detect parsing errors when
the given string is not properly formatted. Consider using SetHeader()
instead, where this can be checked.
\param string the http-encoded header to parse
*/
/*!
\fn BHttpHeader::BHttpHeader(const char* name, const char* value)
\brief Construct a BHttpHeader from an unencoded key-value pair.
\param name the key
\param value the value
*/
/*!
\fn BHttpHeader::BHttpHeader(const BHttpHeader& copy)
\brief Copy constructor.
*/
/*!
\fn void BHttpHeader::SetName(const char* name)
\brief Sets the key for this header.
The key is trimmed (BString::Trim()) to remove any whitespace.
\param name the new key
*/
/*!
\fn void BHttpHeader::SetValue(const char* value)
\brief Sets the value for this header.
The value is trimmed (BString::Trim()) to remove any whitespace.
\param value the new value
*/
/*!
\fn bool BHttpHeader::SetHeader(const char* string)
\brief Parse the given string and configure this object
Extracts and decode the name and value from the given string.
\param string the header data to parse
\return wether parsing succeeded
*/
/*!
\fn const char* BHttpHeader::Name() const
\return the key for this header
*/
/*!
\fn const char* BHttpHeader::Value() const
\return the value for this header
*/
/*!
\fn const char* BHttpHeader::Header() const
\return the encoded header
*/
/*!
\fn bool BHttpHeader::NameIs(const char* name) const
\brief Compare this header name with the given one
Both names are trimmed from whitespace, and the comparison is not case
sensitive (as per the HTTP specification).
*/
/*!
\class BPrivate::Network::BHttpHeaders
\ingroup netservices
\brief Container for a set of HTTP headers.
This class allows management of the set of headers for a single HTTP
transaction. They are stored in a list and can be iterated on.
*/
/*!
\fn BHttpHeaders::BHttpHeaders()
\brief Construct an empty header list.
*/
/*!
\fn BHttpHeaders::BHttpHeaders(const BHttpHeaders& copy)
\brief Copy constructor
A deep copy is performed, so modifying the headers in the copy does not
change the original.
*/
/*!
\fn const char* BHttpHeaders::HeaderValue(const char* name) const
\return the value mapped to the given key, or NULL if not found.
*/
/*!
\fn BHttpHeader& BHttpHeaders::HeaderAt(int32 index) const
\brief Find header by position
\param index must be in bounds, else this method will crash.
\see CountHeaders()
*/
/*!
\fn int32 BHttpHeaders::CountHeaders() const
\return the number of entries in this set
*/
/*!
\fn int32 BHttpHeaders::HasHeader(const char* name) const
\brief Find an header by key
\return The index of the header for use with HeaderAt(), or B_ERROR if not
found.
*/
/*!
\fn bool BHttpHeaders::AddHeader(const char* line)
\brief Add a new header to the list, from an HTTP header line.
Duplicates headers are allowed.
\return false when out of memory.
*/
/*!
\fn bool BHttpHeaders::AddHeader(const char* name, const char* value)
\brief Add a new header from the given key:value pair
*/
/*!
\fn bool BHttpHeaders::AddHeader(const char* name, int32 value)
\brief Convenience method to add a header with a numeric value.
*/
/*!
\fn void BHttpHeaders::Clear()
\brief Remove all HTTP headers from the list
*/

182
docs/user/netservices/HttpRequest.dox
View File

@ -1,182 +0,0 @@
/*
* Copyright 2013 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Adrien Destugues, pulkomandy@pulkomandy.tk
* John Scipione, jscipione@gmail.com
*
* Corresponds to:
* headers/private/netservices/HttpRequest.h hrev54923
* src/kits/network/libnetservices/HttpRequest.cpp hrev54923
*/
/*!
\file HttpRequest.h
\ingroup netservices
\brief Management of HTTP or HTTPS protocol requests
*/
/*!
\class BPrivate::Network::BHttpRequest
\ingroup netservices
\brief Handles a request over HTTP or HTTPS.
Instances of ths class will be created by the BUrlProtocolRoster for
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 elsewhere. 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 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::SetReferrer(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.
*/

70
docs/user/netservices/UrlProtocolAsynchronousListener.dox
View File

@ -1,70 +0,0 @@
/*
* Copyright 2020 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Leorize, leorize+oss@disroot.org
*
* Corresponds to:
* headers/private/netservices/UrlProtocolAsynchronousListener.h hrev54923
* src/kits/network/libnetapi/UrlProtocolAsynchronousListener.cpp hrev54923
*/
/*!
\file UrlProtocolAsynchronousListener.h
\ingroup netservices
\brief Provides the BUrlProtocolAsynchronousListener interface.
*/
/*!
\class BPrivate::Network::BUrlProtocolAsynchronousListener
\ingroup netservices
\brief Provides a handler for BUrlProtocolDispatchingListener.
BUrlProtocolAsynchronousListener transparently handles BMessage issued by
BUrlProtocolDispatchingListener via callbacks from the BUrlProtocolListener
interface.
*/
/*!
\fn BUrlProtocolAsynchronousListener::BUrlProtocolAsynchronousListener(bool transparent = false)
\brief Create a BUrlProtocolAsynchronousListener.
This constructor will also add the created object to the list of be_app
handlers.
\param transparent Whether a BUrlProtocolListener object should be created
in conjunction with the current object. This object can be accessed via
SynchronousListener().
*/
/*!
\fn virtual BUrlProtocolAsynchronousListener::~BUrlProtocolAsynchronousListener()
\brief Default destructor for BUrlProtocolAsynchronousListener.
This destructor will free resources associated with the current object.
*/
/*!
\fn BUrlProtocolListener* BUrlProtocolAsynchronousListener::SynchronousListener()
\brief The synchronous listener created from the current object.
\returns A pointer to a BUrlProtocolListener object, or \c NULL if
\c transparent was \c false on object creation and/or memory couldn't
be allocated for the object at the time of creation.
\warning The returned pointer lifetime is associated with the current object.
Do not attempt to delete this pointer.
*/
/*!
\fn virtual void BUrlProtocolAsynchronousListener::MessageReceived(BMessage* message)
\brief Handle messages that has been received by the associated looper.
This handler handles messages received from
BUrlProtocolDispatchingListener and handle them via callbacks as defined per
BUrlProtocolListener.
*/

198
docs/user/netservices/UrlProtocolListener.dox
View File

@ -1,198 +0,0 @@
/*
* Copyright 2020 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Leorize, leorize+oss@disroot.org
*
* Corresponds to:
* headers/private/netservices/UrlProtocolListener.h hrev54923
* src/kits/network/libnetapi/UrlProtocolListener.cpp hrev54923
*/
/*!
\file UrlProtocolListener.h
\ingroup netservices
\brief Provides the BUrlProtocolListener abstract interface.
*/
/*!
\enum BPrivate::Network::BUrlProtocolDebugMessage
\brief The type of the debug message.
*/
/*!
\var B_URL_PROTOCOL_DEBUG_TEXT
\brief Informational debug message.
*/
/*!
\var B_URL_PROTOCOL_DEBUG_ERROR
\brief Error debug message.
*/
/*!
\var B_URL_PROTOCOL_DEBUG_HEADER_IN
\brief Debug messages related to metadata received.
*/
/*!
\var B_URL_PROTOCOL_DEBUG_HEADER_OUT
\brief Debug messages related to metadata sent.
*/
/*!
\var B_URL_PROTOCOL_DEBUG_TRANSFER_IN
\brief Debug messages related to data received.
*/
/*!
\var B_URL_PROTOCOL_DEBUG_TRANSFER_OUT
\brief Debug messages related to data sent.
*/
/*!
\class BPrivate::Network::BUrlProtocolListener
\ingroup netservices
\brief Abstract interface for handling BUrlRequest events.
BUrlProtocolListener is the base class for handling networking events from
BUrlRequest.
*/
/*!
\fn virtual void BUrlProtocolListener::ConnectionOpened(BUrlRequest* caller)
\brief Called when the socket is opened.
\b Frequency: Once
\param caller The BUrlRequest that invoked this callback.
*/
/*!
\fn virtual void BUrlProtocolListener::HostnameResolved(BUrlRequest* caller,
const char* ip)
\brief Called when the final IP is discovered.
\b Frequency: Once
\param caller The BUrlRequest that invoked this callback.
\param ip String representing the IP address of the resource host.
*/
/*!
\fn virtual void BUrlProtocolListener::ResponseStarted(BUrlRequest* caller)
\brief Called when the request has been emitted and the server begins to reply.
Typically this callback will be called when the HTTP status code is
received.
\b Frequency: Once
\param caller The BUrlRequest that invoked this callback.
*/
/*!
\fn virtual void BUrlProtocolListener::HeadersReceived(BUrlRequest* caller)
\brief Called when all of the server response metadata (such as headers)
have been read and parsed.
\b Frequency: Once
\param caller The BUrlRequest that invoked this callback.
*/
/*!
\fn virtual void BUrlProtocolListener::BytesWritten(BUrlRequest* caller,
size_t size)
\brief Called each time a block of data is written.
This callback is called whenever a block of data is written to the
BDataIO associated with the request. If no BDataIO is associated, the
callback will not be invoked.
\b Frequency: Zero or more
\param caller The BUrlRequest that invoked this callback.
\param size Size of the written data block.
*/
/*!
\fn virtual void BUrlProtocolListener::DownloadProgress(BUrlRequest* caller,
off_t bytesReceived, off_t bytesTotal)
\brief Called each time a block of data is downloaded.
This callback might still be invoked even when no BDataIO is associated
with the request, as data can still be downloaded and discarded so that the
request can be completed and the socket can be reused.
\b Frequency: Zero or more
\param caller The BUrlRequest that invoked this callback.
\param bytesReceived Number of data bytes received. This is the number of
bytes received prior to any processing and can be smaller than the
size of the data block written to the output BDataIO as the transport
might be compressed.
\param bytesTotal Total number of data bytes expected. \c 0 will be passed
if the total number of data bytes is not available.
*/
/*!
\fn virtual void BUrlProtocolListener::UploadProgress(BUrlRequest* caller,
off_t bytesSent, off_t bytesTotal)
\brief Called each time a block of data is sent.
\note Currently this callback is never called.
\param caller The BUrlRequest that invoked this callback.
\param bytesSent Number of data bytes sent.
\param bytesTotal Total number of data bytes left.
*/
/*!
\fn virtual void BUrlProtocolListener::RequestCompleted(BUrlRequest* caller,
bool success)
\brief Called once the request is complete.
\b Frequency: Once
\param caller The BUrlRequest that invoked this callback.
\param success Whether the request has been successfully completed.
*/
/*!
\fn virtual void BUrlProtocolListener::DebugMessage(BUrlRequest* caller,
BUrlProtocolDebugMessage type, const char* text)
\brief Called each time a debug message is emitted.
\b Frequency: Zero or more
\param caller The BUrlRequest that invoked this callback.
\param type Type of the message.
\param text The message.
*/
/*!
\fn virtual bool BUrlProtocolListener::CertificateVerificationFailed(
BUrlRequest* caller, BCertificate& certificate, const char* message
)
\brief Called when cerificate verification failed.
\b Frequency: Once
\param caller The BUrlRequest that invoked this callback.
\param certificate The SSL certificate of which validation failed.
\param message The error message describing the issue.
\returns \c true to ignore and proceed with the request, \c false to abort.
*/

44
docs/user/netservices/UrlProtocolRoster.dox
View File

@ -1,44 +0,0 @@
/*
* Copyright 2020 Haiku, Inc. All rights reserved.
* Distributed under the terms of the MIT License.
*
* Authors:
* Leorize, leorize+oss@disroot.org
*
* Corresponds to:
* headers/private/netservices/UrlProtocolRoster.h hrev54923
* src/kits/network/libnetservices/UrlProtocolRoster.cpp hrev54923
*/
/*!
\file UrlProtocolRoster.h
\ingroup netservices
\brief Provides the BUrlProtocolRoster interface.
*/
/*!
\class BPrivate::Network::BUrlProtocolRoster
\ingroup netservices
\brief Interfaces for protocol-agnostic operations.
*/
/*!
\fn static BUrlRequest* BUrlProtocolRoster::MakeRequest(const BUrl& url,
BDataIO* output, BUrlProtocolListener* listener = NULL,
BUrlContext* context = NULL)
\brief Create a BUrlRequest that can handle the given BUrl
\param url The URL to create a request for
\param output The BDataIO to output to
\param listener The BUrlProtocolListener to be registered with the created
BUrlRequest, can be \c NULL
\param context The BUrlContext to be registered with the created
BUrlRequest, can be \c NULL
\returns A pointer to the BUrlRequest that can handle the given BUrl.
\c NULL will be returned if there aren't any BUrlRequest that can
handle the given protocol or if memory couldn't be allocated.
*/