docs: Add documentation for BUrlProtocolListener

Change-Id: I6fb6092d31e9ff94a1c9466240b375b9b88f2d8f
Reviewed-on: https://review.haiku-os.org/c/haiku/+/2929
Reviewed-by: waddlesplash <[email protected]>

docs/user/net/UrlProtocolListener.dox

@@ -0,0 +1,151 @@
+/*
+ * Copyright 2020 Haiku, Inc. All rights reserved.
+ * Distributed under the terms of the MIT License.
+ *
+ * Authors:
+ *		Leorize, [email protected]
+ *
+ * Corresponds to:
+ *		headers/os/net/UrlProtocolListener.h hrev54280
+ *		src/kits/network/libnetapi/UrlProtocolListener.cpp hrev54280
+ */
+
+
+/*!
+	\file UrlProtocolListener.h
+	\ingroup network
+	\brief Provides the BUrlProtocolListener abstract interface.
+*/
+
+
+/*!
+	\class BUrlProtocolListener
+	\ingroup network
+	\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,
+		const BUrlResult& result);
+	\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.
+	\param result The BUrlResult associated with the request.
+*/
+
+/*!
+	\fn virtual void BUrlProtocolListener::DataReceived(BUrlRequest* caller,
+		const char* data, off_t position, size_t size)
+	\brief Called each time a block of data is received.
+
+	\b Frequency: Zero or more
+
+	\param caller The BUrlRequest that invoked this callback.
+	\param data Pointer to the data block in memory.
+	\param position Offset of the data in the stream.
+	\param size Size of the data block.
+*/
+
+/*!
+	\fn virtual void BUrlProtocolListener::DownloadProgress(BUrlRequest* caller,
+		ssize_t bytesReceived, ssize_t bytesTotal)
+	\brief Called each time a block of data is received.
+
+	This callback will be called after DataReceived().
+
+	\b Frequency: Once or more
+
+	\param caller The BUrlRequest that invoked this callback.
+	\param bytesReceived Number of data bytes received.
+	\param bytesTotal Total number of data bytes expected. This value is not
+		guaranteed to be meaningful.
+*/
+
+/*!
+	\fn virtual void BUrlProtocolListener::UploadProgress(BUrlRequest* caller,
+		ssize_t bytesSent, ssize_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.
+*/

headers/os/net/UrlProtocolListener.h

@@ -28,109 +28,24 @@ enum BUrlProtocolDebugMessage {
 
 class BUrlProtocolListener {
 public:
-	/**
-		ConnectionOpened()
-		Frequency:	Once
-
-		Called when the socket is opened.
-	*/
 	virtual	void				ConnectionOpened(BUrlRequest* caller);
-
-	/**
-		HostnameResolved(ip)
-		Frequency:	Once
-		Parameters:	ip		 String representing the IP address of the resource
-							host.
-
-		Called when the final IP is discovered
-	*/
 	virtual void				HostnameResolved(BUrlRequest* caller,
 									const char* ip);
-
-	/**
-		ReponseStarted()
-		Frequency:	Once
-
-		Called when the request has been emitted and the server begins to
-		reply. Typically when the HTTP status code is received.
-	*/
 	virtual void				ResponseStarted(BUrlRequest* caller);
-
-	/**
-		HeadersReceived()
-		Frequency:	Once
-
-		Called when all the server response metadata (such as headers) have
-		been read and parsed.
-	*/
 	virtual void				HeadersReceived(BUrlRequest* caller,
 									const BUrlResult& result);
-
-	/**
-		DataReceived(data, position, size)
-		Frequency:	Zero or more
-		Parameters:	data	 Pointer to the data block in memory
-					position Offset of the data in the stream
-					size	 Size of the data block
-
-		Called each time a full block of data is received.
-	*/
 	virtual void				DataReceived(BUrlRequest* caller,
 									const char* data, off_t position,
 									ssize_t size);
-
-	/**
-		DownloadProgress(bytesReceived, bytesTotal)
-		Frequency:	Once or more
-		Parameters:	bytesReceived	Number of data bytes received
-					bytesTotal		Total number of data bytes expected
-
-		Called each time a data block is received.
-	*/
 	virtual	void				DownloadProgress(BUrlRequest* caller,
 									ssize_t bytesReceived, ssize_t bytesTotal);
-
-	/**
-		UploadProgress(bytesSent, bytesTotal)
-		Frequency:	Once or more
-		Parameters:	bytesSent		Number of data bytes sent
-					bytesTotal		Total number of data bytes expected
-
-		Called each time a data block is emitted.
-	*/
 	virtual void				UploadProgress(BUrlRequest* caller,
 									ssize_t bytesSent, ssize_t bytesTotal);
-
-	/**
-		RequestCompleted(success)
-		Frequency:	Once
-		Parameters:	success			true if the resource have been successfully
-									false if not
-
-		Called once the request is complete.
-	*/
 	virtual void				RequestCompleted(BUrlRequest* caller,
 									bool success);
-
-	/**
-		DebugMessage(type, text)
-		Frequency:	zero or more
-		Parameters:	type	Type of the verbose message (see BUrlProtocolDebug)
-
-		Called each time a debug message is emitted
-	*/
 	virtual void				DebugMessage(BUrlRequest* caller,
 									BUrlProtocolDebugMessage type,
 									const char* text);
-
-	/**
-		CertificateVerificationFailed(certificate, message)
-		Frequency: Once
-		Parameters: certificate	SSL certificate which coulnd't be validated
-					message error message describing the problem
-
-		Return true to proceed anyway, false to abort the connection
-	*/
 	virtual bool				CertificateVerificationFailed(
 									BUrlRequest* caller,
 									BCertificate& certificate,