haiku/docs/user/net/UrlRequest.dox

/*
 * 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.
*/