From 937388cdd82bea475ced15a2b14f5d864a06ad6a Mon Sep 17 00:00:00 2001 From: Leorize Date: Fri, 3 Jul 2020 02:01:01 -0500 Subject: [PATCH] docs/user/net: add BUrlProtocolDispatchingListener documentation Change-Id: I8515f6d5feab3399f3b0357b78e7e791cdf6df25 Reviewed-on: https://review.haiku-os.org/c/haiku/+/2982 Reviewed-by: Adrien Destugues --- .../net/UrlProtocolDispatchingListener.dox | 341 ++++++++++++++++++ 1 file changed, 341 insertions(+) create mode 100644 docs/user/net/UrlProtocolDispatchingListener.dox diff --git a/docs/user/net/UrlProtocolDispatchingListener.dox b/docs/user/net/UrlProtocolDispatchingListener.dox new file mode 100644 index 0000000000..3b51a87580 --- /dev/null +++ b/docs/user/net/UrlProtocolDispatchingListener.dox @@ -0,0 +1,341 @@ +/* + * 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/UrlProtocolDispatchingListener.h hrev54384 + * src/kits/network/libnetapi/UrlProtocolDispatchingListener.cpp hrev54384 + */ + + +/*! + \file UrlProtocolDispatchingListener.h + \ingroup network + \brief Provides the BUrlProtocolDispatchingListener class. +*/ + + +/*! + \var B_URL_PROTOCOL_NOTIFICATION + \brief The \c what constant for BMessage emitted by + BUrlProtocolDispatchingListener. +*/ + + +/*! + \var B_URL_PROTOCOL_CONNECTION_OPENED + \brief The type of message emitted by + BUrlProtocolDispatchingListener::ConnectionOpened(). +*/ + + +/*! + \var B_URL_PROTOCOL_HOSTNAME_RESOLVED + \brief The type of message emitted by + BUrlProtocolDispatchingListener::HostnameResolved(). +*/ + + +/*! + \var B_URL_PROTOCOL_RESPONSE_STARTED + \brief The type of message emitted by + BUrlProtocolDispatchingListener::ResponseStarted(). +*/ + + +/*! + \var B_URL_PROTOCOL_HEADERS_RECEIVED + \brief The type of message emitted by + BUrlProtocolDispatchingListener::HeadersReceived(). +*/ + + +/*! + \var B_URL_PROTOCOL_DATA_RECEIVED + \brief The type of message emitted by + BUrlProtocolDispatchingListener::DataReceived(). +*/ + + +/*! + \var B_URL_PROTOCOL_DOWNLOAD_PROGRESS + \brief The type of message emitted by + BUrlProtocolDispatchingListener::DownloadProgress(). +*/ + + +/*! + \var B_URL_PROTOCOL_UPLOAD_PROGRESS + \brief The type of message emitted by + BUrlProtocolDispatchingListener::UploadProgress(). +*/ + + +/*! + \var B_URL_PROTOCOL_REQUEST_COMPLETED + \brief The type of message emitted by + BUrlProtocolDispatchingListener::RequestCompleted(). +*/ + + +/*! + \var B_URL_PROTOCOL_CERTIFICATE_VERIFICATION_FAILED + \brief The type of message emitted by + BUrlProtocolDispatchingListener::CertificateVerificationFailed(). +*/ + + +/*! + \var B_URL_PROTOCOL_DEBUG_MESSAGE + \brief The type of message emitted by + BUrlProtocolDispatchingListener::DebugMessage(). +*/ + + +/*! + \class BUrlProtocolDispatchingListener + \ingroup network + \brief Dispatches BUrlProtocolListener events as BMessage. + + BUrlProtocolDispatchingListener is a BUrlProtocolListener implementation + that dispatches received events as BMessage. A corresponding + BHandler implementation that make use of BUrlProtocolListener hooks + to handle messages emitted by this class is available as + BUrlProtocolAsynchronousListener. + + BMessage emitted from this class use the code #B_URL_PROTOCOL_NOTIFICATION. + Refer to each member functions for the format of the messages they emit. + + + + + + + + + + + + + + + + + + +
The format of the emitted message
Field nameTypeValue
be:urlProtocolCaller\c B_POINTER_TYPE\a The request that generated the event
be:urlProtocolMessageType\c B_INT8_TYPEThe message type, one of the B_URL_PROTOCOL_* constants
+ + Messages for specific events may include extra fields, documented in the + description of each of the hook methods, and usually matching the parameters + of that method. +*/ + + +/*! + \fn virtual void BUrlProtocolDispatchingListener::ConnectionOpened( + BUrlRequest* caller) + \brief Emit a message when the socket is opened. + +*/ + +/*! + \fn virtual void BUrlProtocolDispatchingListener::HostnameResolved( + BUrlRequest* caller, const char* ip) + \brief Emit a message when the final IP is discovered. + + + + + + + + + + + + + +
The format of the emitted message
Field nameField typeValue
url:hostIp\c B_STRING_TYPE\a ip
+*/ + +/*! + \fn virtual void BUrlProtocolDispatchingListener::ResponseStarted( + BUrlRequest* caller) + \brief Emit a message when the server begins to reply. +*/ + +/*! + \fn virtual void BUrlProtocolDispatchingListener::HeadersReceived( + BUrlRequest* caller, const BUrlResult& result); + \brief Emit a message when all of the response metadata is made available. + + + + + + + + + + + + + +
The format of the emitted message
Field nameField typeValue
url:result\c B_MESSAGE_TYPE + An archived copy of \a result. BUrlResult(BMessage*) can be + used to create a new BUrlResult from the received BMessage. +
+*/ + +/*! + \fn virtual void BUrlProtocolDispatchingListener::DownloadProgress( + BUrlRequest* caller, off_t bytesReceived, off_t bytesTotal) + \brief Emit a message each time a block of data is received. + + This message will usually be emitted after DataReceived(). + + + + + + + + + + + + + + + + + + +
The format of the emitted message
Field nameField typeValue
url:bytesReceived\c B_INT64_TYPE\a bytesReceived
url:bytesTotal\c B_INT64_TYPE\a bytesTotal
+*/ + +/*! + \fn virtual void BUrlProtocolDispatchingListener::UploadProgress( + BUrlRequest* caller, off_t bytesSent, off_t bytesTotal) + \brief Emit a message each time a block of data is sent. + + + + + + + + + + + + + + + + + + +
The format of the emitted message
Field nameField typeValue
url:bytesSent\c B_INT64_TYPE\a bytesSent
url:bytesTotal\c B_INT64_TYPE\a bytesTotal
+*/ + +/*! + \fn virtual void BUrlProtocolDispatchingListener::RequestCompleted( + BUrlRequest* caller, bool success) + \brief Emit a message once the request is complete. + + + + + + + + + + + + + +
The format of the emitted message
Field nameTypeValue
url:success\c B_BOOL_TYPE\a success
+*/ + +/*! + \fn virtual void BUrlProtocolDispatchingListener::DebugMessage(BUrlRequest* caller, + BUrlProtocolDebugMessage type, const char* text) + \brief Emit a message with debugging information. + + These messages are useful for tracing and analyzing requests sent and + responses received. They can be printed to the standard output, directed to + a log file, or simply ignored. + + + + + + + + + + + + + + + + + + +
The format of the emitted message
Field nameTypeValue
url:type\c B_INT32_TYPE\a type
url:text\c B_STRING_TYPE\a text
+*/ + +/*! + \fn virtual bool BUrlProtocolDispatchingListener::CertificateVerificationFailed( + BUrlRequest* caller, BCertificate& certificate, const char* message + ) + \brief Emit a message when cerificate verification failed. + + This event is triggered when a certificate failed verification, for example + because it has expired, or because the signing authority is not trusted. + The user should be informed of the problem, but may decide to continue the + request anyway. + + + + + + + + + + + + + + + + + + +
The format of the emitted message
Field nameTypeValue
url:error\c B_STRING_TYPE\a message
url:certificate\c B_POINTER_TYPEPointer to the \a certificate to be validated
+ + This message expects a reply from the handler. + + + + + + + + + + + + + +
The expected format of the reply
Field nameTypeValue
url:continue\c B_BOOL_TYPE + \a true if the request should be continued, \a false otherwise. +
+*/