[haiku-commits] haiku: hrev54338 - docs/user/net headers/os/net

  • From: waddlesplash <waddlesplash@xxxxxxxxx>
  • To: haiku-commits@xxxxxxxxxxxxx
  • Date: Sat, 20 Jun 2020 14:13:43 -0400 (EDT)

hrev54338 adds 3 changesets to branch 'master'
old head: fbb8bf7ee3bf055a6a2d0d7c9b5fc6f7f490d8ab
new head: bbc0611099d7193e484b43d878956433380b9377
overview: 
https://git.haiku-os.org/haiku/log/?qt=range&q=bbc0611099d7+%5Efbb8bf7ee3bf

----------------------------------------------------------------------------

fcf08bbd68ae: docs: Add documentation for BUrlProtocolRoster
  
  Change-Id: Id4bc0809c970ea14f814820b54e52073e3396502
  Reviewed-on: https://review.haiku-os.org/c/haiku/+/2928
  Reviewed-by: waddlesplash <waddlesplash@xxxxxxxxx>

b927cf68222a: docs: Add documentation for BUrlProtocolListener
  
  Change-Id: I6fb6092d31e9ff94a1c9466240b375b9b88f2d8f
  Reviewed-on: https://review.haiku-os.org/c/haiku/+/2929
  Reviewed-by: waddlesplash <waddlesplash@xxxxxxxxx>

bbc0611099d7: docs: Add docs for BUrlProtocolAsynchronousListener
  
  Change-Id: Ib9df07d42d0153a7e0135acae85c00f3a1e6bd93
  Reviewed-on: https://review.haiku-os.org/c/haiku/+/2930
  Reviewed-by: waddlesplash <waddlesplash@xxxxxxxxx>

                                       [ Leorize <leorize+oss@xxxxxxxxxxx> ]

----------------------------------------------------------------------------

4 files changed, 263 insertions(+), 85 deletions(-)
.../user/net/UrlProtocolAsynchronousListener.dox |  70 +++++++++
docs/user/net/UrlProtocolListener.dox            | 151 +++++++++++++++++++
docs/user/net/UrlProtocolRoster.dox              |  42 ++++++
headers/os/net/UrlProtocolListener.h             |  85 -----------

############################################################################

Commit:      fcf08bbd68aef788d6359c896f6bdc11fc98f1cb
URL:         https://git.haiku-os.org/haiku/commit/?id=fcf08bbd68ae
Author:      Leorize <leorize+oss@xxxxxxxxxxx>
Date:        Thu Jun 18 05:07:20 2020 UTC
Committer:   waddlesplash <waddlesplash@xxxxxxxxx>
Commit-Date: Sat Jun 20 18:13:33 2020 UTC

docs: Add documentation for BUrlProtocolRoster

Change-Id: Id4bc0809c970ea14f814820b54e52073e3396502
Reviewed-on: https://review.haiku-os.org/c/haiku/+/2928
Reviewed-by: waddlesplash <waddlesplash@xxxxxxxxx>

----------------------------------------------------------------------------

diff --git a/docs/user/net/UrlProtocolRoster.dox 
b/docs/user/net/UrlProtocolRoster.dox
new file mode 100644
index 0000000000..c17944019e
--- /dev/null
+++ b/docs/user/net/UrlProtocolRoster.dox
@@ -0,0 +1,42 @@
+/*
+ * 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/UrlProtocolRoster.h hrev54280
+ *             src/kits/network/libnetapi/UrlProtocolRoster.cpp hrev54280
+ */
+
+
+/*!
+       \file UrlProtocolRoster.h
+       \ingroup network
+       \brief Provides the BUrlProtocolRoster interface.
+*/
+
+
+/*!
+       \class BUrlProtocolRoster
+       \ingroup network
+       \brief Interfaces for protocol-agnostic operations.
+*/
+
+
+/*!
+       \fn static BUrlRequest* BUrlProtocolRoster::MakeRequest(const BUrl& url,
+               BUrlProtocolListener* listener = NULL, BUrlContext* context = 
NULL)
+       \brief Create a BUrlRequest that can handle the given BUrl
+
+       \param url The URL to create a request for
+       \param listener The BUrlProtocolListener to be registered with the 
created
+               BUrlRequest, can be \c NULL
+       \param context The BUrlContext to be registered with the created
+               BUrlRequest, can be \c NULL
+
+       \returns A pointer to the BUrlRequest that can handle the given BUrl.
+               \c NULL will be returned if there aren't any BUrlRequest that 
can
+               handle the given protocol or if memory couldn't be allocated.
+*/

############################################################################

Commit:      b927cf68222a9a96c5e4c14f0ed9f1acb162e045
URL:         https://git.haiku-os.org/haiku/commit/?id=b927cf68222a
Author:      Leorize <leorize+oss@xxxxxxxxxxx>
Date:        Thu Jun 18 05:08:23 2020 UTC
Committer:   waddlesplash <waddlesplash@xxxxxxxxx>
Commit-Date: Sat Jun 20 18:13:33 2020 UTC

docs: Add documentation for BUrlProtocolListener

Change-Id: I6fb6092d31e9ff94a1c9466240b375b9b88f2d8f
Reviewed-on: https://review.haiku-os.org/c/haiku/+/2929
Reviewed-by: waddlesplash <waddlesplash@xxxxxxxxx>

----------------------------------------------------------------------------

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@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.
+
+       \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,

############################################################################

Revision:    hrev54338
Commit:      bbc0611099d7193e484b43d878956433380b9377
URL:         https://git.haiku-os.org/haiku/commit/?id=bbc0611099d7
Author:      Leorize <leorize+oss@xxxxxxxxxxx>
Date:        Thu Jun 18 05:09:06 2020 UTC
Committer:   waddlesplash <waddlesplash@xxxxxxxxx>
Commit-Date: Sat Jun 20 18:13:33 2020 UTC

docs: Add docs for BUrlProtocolAsynchronousListener

Change-Id: Ib9df07d42d0153a7e0135acae85c00f3a1e6bd93
Reviewed-on: https://review.haiku-os.org/c/haiku/+/2930
Reviewed-by: waddlesplash <waddlesplash@xxxxxxxxx>

----------------------------------------------------------------------------

diff --git a/docs/user/net/UrlProtocolAsynchronousListener.dox 
b/docs/user/net/UrlProtocolAsynchronousListener.dox
new file mode 100644
index 0000000000..676fd34f37
--- /dev/null
+++ b/docs/user/net/UrlProtocolAsynchronousListener.dox
@@ -0,0 +1,70 @@
+/*
+ * 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/UrlProtocolAsynchronousListener.h hrev54280
+ *             src/kits/network/libnetapi/UrlProtocolAsynchronousListener.cpp 
hrev54280
+ */
+
+
+/*!
+       \file UrlProtocolAsynchronousListener.h
+       \ingroup network
+       \brief Provides the BUrlProtocolAsynchronousListener interface.
+*/
+
+
+/*!
+       \class BUrlProtocolAsynchronousListener
+       \ingroup network
+       \brief Provides a handler for BUrlProtocolDispatchingListener.
+
+       BUrlProtocolAsynchronousListener transparently handles BMessage issued 
by
+       BUrlProtocolDispatchingListener via callbacks from the 
BUrlProtocolListener
+       interface.
+*/
+
+
+/*!
+       \fn 
BUrlProtocolAsynchronousListener::BUrlProtocolAsynchronousListener(bool 
transparent = false)
+       \brief Create a BUrlProtocolAsynchronousListener.
+
+       This constructor will also add the created object to the list of be_app
+       handlers.
+
+       \param transparent Whether a BUrlProtocolListener object should be 
created
+               in conjunction with the current object. This object can be 
accessed via
+               SynchronousListener().
+*/
+
+/*!
+       \fn virtual 
BUrlProtocolAsynchronousListener::~BUrlProtocolAsynchronousListener()
+       \brief Default destructor for BUrlProtocolAsynchronousListener.
+
+       This destructor will free resources associated with the current object.
+*/
+
+/*!
+       \fn BUrlProtocolListener* 
BUrlProtocolAsynchronousListener::SynchronousListener()
+       \brief The synchronous listener created from the current object.
+
+       \returns A pointer to a BUrlProtocolListener object, or \c NULL if
+               \c transparent was \c false on object creation and/or memory 
couldn't
+               be allocated for the object at the time of creation.
+
+       \warning The returned pointer lifetime is associated with the current 
object.
+               Do not attempt to delete this pointer.
+*/
+
+/*!
+       \fn virtual void 
BUrlProtocolAsynchronousListener::MessageReceived(BMessage* message)
+       \brief Handle messages that has been received by the associated looper.
+
+       This handler handles messages received from
+       BUrlProtocolDispatchingListener and handle them via callbacks as 
defined per
+       BUrlProtocolListener.
+*/


Other related posts:

  • » [haiku-commits] haiku: hrev54338 - docs/user/net headers/os/net - waddlesplash