From leorize <leorize+oss@xxxxxxxxxxx>:
leorize has uploaded this change for review. (
https://review.haiku-os.org/c/haiku/+/2984 ;)
Change subject: docs/user/net: add BUrlRequest documentation
......................................................................
docs/user/net: add BUrlRequest documentation
Change-Id: I88bff3c452ed9e2025c7d258167ced14919c4e9c
---
A docs/user/net/UrlRequest.dox
1 file changed, 309 insertions(+), 0 deletions(-)
git pull ssh://git.haiku-os.org:22/haiku refs/changes/84/2984/1
diff --git a/docs/user/net/UrlRequest.dox b/docs/user/net/UrlRequest.dox
new file mode 100644
index 0000000..98793c7
--- /dev/null
+++ b/docs/user/net/UrlRequest.dox
@@ -0,0 +1,309 @@
+/*
+ * Copyright 2020 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ * Leorize, leorize+oss@xxxxxxxxxxx
+ *
+ * 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 Stop(), implementors should override
+ this destructor to ensure that any spawned thread will 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::Pause()
+ \brief Pause the request.
+
+ The base implementation of this method always returns \c B_ERROR.
+*/
+
+
+/*!
+ \fn virtual status_t BUrlRequest::Resume()
+ \brief Pause the request.
+
+ The base implementation of this method always returns \c B_ERROR.
+*/
+
+
+/*!
+ \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 transfer or any operations) 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.
+
+ \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.
+
+ \warning Unlike BUrlRequest(), setting the \a context to \c NULL will
+ \b not employ the use of the program-wide context.
+
+ \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.
+*/
+
+
+/*!
+ \var BUrl BUrlRequest::fUrl
+ \brief The BUrl associated with this request.
+
+ Users may access this value via Url() and SetUrl(). The value is
+ not modifiable by the user while the request thread is running.
+*/
+
+
+/*!
+ \var BReference<BUrlContext> BUrlRequest::fContext
+ \brief The BUrlContext associated with this request.
+
+ Users may access this value via Context() and SetContext(). The value is
+ not modifiable by the user while the request thread is running.
+*/
+
+
+/*!
+ \var BUrlProtocolListener* BUrlRequest::fListener
+ \brief The BUrlProtocolListener associated with this request.
+
+ Users may access this value via Listener() and SetListener(). The value
is
+ not modifiable by the user while the request thread is running.
+*/
+
+
+/*!
+ \var bool BUrlRequest::fQuit
+ \brief Whether the request should be aborted.
+
+ This flag signify whether the request should be aborted. Implementations
+ are expected to check this whenever possible to quit the request. This
+ flag will be set to \c true upon Stop().
+*/
--
To view, visit https://review.haiku-os.org/c/haiku/+/2984
To unsubscribe, or for help writing mail filters, visit
https://review.haiku-os.org/settings
Gerrit-Project: haiku
Gerrit-Branch: master
Gerrit-Change-Id: I88bff3c452ed9e2025c7d258167ced14919c4e9c
Gerrit-Change-Number: 2984
Gerrit-PatchSet: 1
Gerrit-Owner: leorize <leorize+oss@xxxxxxxxxxx>
Gerrit-MessageType: newchange
