From leorize <leorize+oss@xxxxxxxxxxx>:
leorize has uploaded this change for review. (
https://review.haiku-os.org/c/haiku/+/2929 ;)
Change subject: docs: Add documentation for BUrlProtocolListener
......................................................................
docs: Add documentation for BUrlProtocolListener
Change-Id: I6fb6092d31e9ff94a1c9466240b375b9b88f2d8f
---
A docs/user/net/UrlProtocolListener.dox
M headers/os/net/UrlProtocolListener.h
2 files changed, 150 insertions(+), 85 deletions(-)
git pull ssh://git.haiku-os.org:22/haiku refs/changes/29/2929/1
diff --git a/docs/user/net/UrlProtocolListener.dox
b/docs/user/net/UrlProtocolListener.dox
new file mode 100644
index 0000000..ffda5a3
--- /dev/null
+++ b/docs/user/net/UrlProtocolListener.dox
@@ -0,0 +1,150 @@
+/*
+ * 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/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.
+
+ **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.
+
+ **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.
+
+ **Frequency**: Once
+
+ Typically this callback will be called when the HTTP status code is
received.
+
+ \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.
+
+ **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.
+
+ **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 byteReceived, ssize_t bytesTotal)
+ \brief Called each time a block of data is received.
+
+ **Frequency**: Once or more
+
+ This callback will be called after DataReceived().
+
+ \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 bytesReceived 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.
+
+ **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.
+
+ **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.
+
+ **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 `true` to ignore and proceed with the request, `false` to
abort.
+*/
diff --git a/headers/os/net/UrlProtocolListener.h
b/headers/os/net/UrlProtocolListener.h
index bc98826..1aefd13 100644
--- a/headers/os/net/UrlProtocolListener.h
+++ b/headers/os/net/UrlProtocolListener.h
@@ -28,109 +28,24 @@
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,
--
To view, visit https://review.haiku-os.org/c/haiku/+/2929
To unsubscribe, or for help writing mail filters, visit
https://review.haiku-os.org/settings
Gerrit-Project: haiku
Gerrit-Branch: master
Gerrit-Change-Id: I6fb6092d31e9ff94a1c9466240b375b9b88f2d8f
Gerrit-Change-Number: 2929
Gerrit-PatchSet: 1
Gerrit-Owner: leorize <leorize+oss@xxxxxxxxxxx>
Gerrit-MessageType: newchange
