docs/user/net: add BUrlRequest documentation
Change-Id: I88bff3c452ed9e2025c7d258167ced14919c4e9c Reviewed-on: https://review.haiku-os.org/c/haiku/+/2984 Reviewed-by: Adrien Destugues <pulkomandy@gmail.com>
This commit is contained in:
Leorize
Adrien Destugues
parent
9b692462b3
commit
42819a8b49
266
docs/user/net/UrlRequest.dox
Normal file
266
docs/user/net/UrlRequest.dox
Normal file
@ -0,0 +1,266 @@
|
||||
/*
|
||||
* 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.
|
||||
*/
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user