From b927cf68222a9a96c5e4c14f0ed9f1acb162e045 Mon Sep 17 00:00:00 2001 From: Leorize Date: Thu, 18 Jun 2020 00:08:23 -0500 Subject: [PATCH] docs: Add documentation for BUrlProtocolListener Change-Id: I6fb6092d31e9ff94a1c9466240b375b9b88f2d8f Reviewed-on: https://review.haiku-os.org/c/haiku/+/2929 Reviewed-by: waddlesplash --- docs/user/net/UrlProtocolListener.dox | 151 ++++++++++++++++++++++++++ headers/os/net/UrlProtocolListener.h | 85 --------------- 2 files changed, 151 insertions(+), 85 deletions(-) create mode 100644 docs/user/net/UrlProtocolListener.dox diff --git a/docs/user/net/UrlProtocolListener.dox b/docs/user/net/UrlProtocolListener.dox new file mode 100644 index 0000000000..36ecba6abd --- /dev/null +++ b/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, leorize+oss@disroot.org + * + * 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. +*/ diff --git a/headers/os/net/UrlProtocolListener.h b/headers/os/net/UrlProtocolListener.h index bc98826240..1aefd13757 100644 --- a/headers/os/net/UrlProtocolListener.h +++ b/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,