docs/user/net: add BUrlProtocolDispatchingListener documentation
Change-Id: I8515f6d5feab3399f3b0357b78e7e791cdf6df25 Reviewed-on: https://review.haiku-os.org/c/haiku/+/2982 Reviewed-by: Adrien Destugues <pulkomandy@gmail.com>
This commit is contained in:
Leorize
Adrien Destugues
parent
758dae382b
commit
937388cdd8
341
docs/user/net/UrlProtocolDispatchingListener.dox
Normal file
341
docs/user/net/UrlProtocolDispatchingListener.dox
Normal file
@ -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.
|
||||
|
||||
<table>
|
||||
<caption>The format of the emitted message</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>be:urlProtocolCaller</td>
|
||||
<td>\c B_POINTER_TYPE</td>
|
||||
<td>\a The request that generated the event</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>be:urlProtocolMessageType</td>
|
||||
<td>\c B_INT8_TYPE</td>
|
||||
<td>The message type, one of the B_URL_PROTOCOL_* constants</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
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.
|
||||
|
||||
<table>
|
||||
<caption>The format of the emitted message</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Field type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:hostIp</td>
|
||||
<td>\c B_STRING_TYPE</td>
|
||||
<td>\a ip</td>
|
||||
</tr>
|
||||
</table>
|
||||
*/
|
||||
|
||||
/*!
|
||||
\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.
|
||||
|
||||
<table>
|
||||
<caption>The format of the emitted message</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Field type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:result</td>
|
||||
<td>\c B_MESSAGE_TYPE</td>
|
||||
<td>
|
||||
An archived copy of \a result. BUrlResult(BMessage*) can be
|
||||
used to create a new BUrlResult from the received BMessage.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
*/
|
||||
|
||||
/*!
|
||||
\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().
|
||||
|
||||
<table>
|
||||
<caption>The format of the emitted message</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Field type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:bytesReceived</td>
|
||||
<td>\c B_INT64_TYPE</td>
|
||||
<td>\a bytesReceived</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:bytesTotal</td>
|
||||
<td>\c B_INT64_TYPE</td>
|
||||
<td>\a bytesTotal</td>
|
||||
</tr>
|
||||
</table>
|
||||
*/
|
||||
|
||||
/*!
|
||||
\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.
|
||||
|
||||
<table>
|
||||
<caption>The format of the emitted message</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Field type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:bytesSent</td>
|
||||
<td>\c B_INT64_TYPE</td>
|
||||
<td>\a bytesSent</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:bytesTotal</td>
|
||||
<td>\c B_INT64_TYPE</td>
|
||||
<td>\a bytesTotal</td>
|
||||
</tr>
|
||||
</table>
|
||||
*/
|
||||
|
||||
/*!
|
||||
\fn virtual void BUrlProtocolDispatchingListener::RequestCompleted(
|
||||
BUrlRequest* caller, bool success)
|
||||
\brief Emit a message once the request is complete.
|
||||
|
||||
<table>
|
||||
<caption>The format of the emitted message</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:success</td>
|
||||
<td>\c B_BOOL_TYPE</td>
|
||||
<td>\a success</td>
|
||||
</tr>
|
||||
</table>
|
||||
*/
|
||||
|
||||
/*!
|
||||
\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.
|
||||
|
||||
<table>
|
||||
<caption>The format of the emitted message</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:type</td>
|
||||
<td>\c B_INT32_TYPE</td>
|
||||
<td>\a type</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:text</td>
|
||||
<td>\c B_STRING_TYPE</td>
|
||||
<td>\a text</td>
|
||||
</tr>
|
||||
</table>
|
||||
*/
|
||||
|
||||
/*!
|
||||
\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.
|
||||
|
||||
<table>
|
||||
<caption>The format of the emitted message</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:error</td>
|
||||
<td>\c B_STRING_TYPE</td>
|
||||
<td>\a message</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:certificate</td>
|
||||
<td>\c B_POINTER_TYPE</td>
|
||||
<td>Pointer to the \a certificate to be validated</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
This message expects a reply from the handler.
|
||||
|
||||
<table>
|
||||
<caption>The expected format of the reply</caption>
|
||||
<tr>
|
||||
<th>Field name</th>
|
||||
<th>Type</th>
|
||||
<th>Value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url:continue</td>
|
||||
<td>\c B_BOOL_TYPE</td>
|
||||
<td>
|
||||
\a true if the request should be continued, \a false otherwise.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
*/
|
||||
Loading…
Reference in New Issue
Block a user