diff --git a/docs/user/net/UrlRequest.dox b/docs/user/net/UrlRequest.dox new file mode 100644 index 0000000000..0dc13c060c --- /dev/null +++ b/docs/user/net/UrlRequest.dox @@ -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. +*/ + +