diff --git a/docs/user/Doxyfile b/docs/user/Doxyfile index 0ea20bb11f..f53f2e82a4 100644 --- a/docs/user/Doxyfile +++ b/docs/user/Doxyfile @@ -856,15 +856,7 @@ INPUT = . \ ../../headers/os/support \ ../../headers/os/translation \ ../../headers/posix/syslog.h \ - ../../src/kits/game/GameProducer.h \ - ../../headers/private/netservices/Geolocation.h \ - ../../headers/private/netservices/HttpAuthentication.h \ - ../../headers/private/netservices/HttpForm.h \ - ../../headers/private/netservices/HttpHeaders.h \ - ../../headers/private/netservices/HttpRequest.h \ - ../../headers/private/netservices/UrlProtocolAsynchronousListener.h \ - ../../headers/private/netservices/UrlProtocolListener.h \ - ../../headers/private/netservices/UrlProtocolRoster.h + ../../src/kits/game/GameProducer.h # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/docs/user/book.dox b/docs/user/book.dox index fff5bbaa2d..cab38a330f 100644 --- a/docs/user/book.dox +++ b/docs/user/book.dox @@ -607,15 +607,22 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); \defgroup json Json Handling \brief Provides for parsing and writing of data in Json encoding. +*/ + +#if __cplusplus >= 201703L +/*! \defgroup netservices Experimental Network Services Support \brief Experimental API to do higher level network requests This API currently is marked as experimental. It is part of the BPrivate::Network namespace, the header files are found at - headers\\private\\netservices, and you have to link your - application to libnetservices.a. + headers\\private\\netservices2, and you have to link your + application to libnetservices2.a. The new API is only + available for modern platforms (x86 and x86_64), and not for the legacy + platform (x86_gcc2). The compiler needs to support C++17 or higher. */ +#endif ///// Namespace Documentation ///// @@ -623,6 +630,8 @@ snooze_until(time - Latency(), B_SYSTEM_TIMEBASE); //! \brief Internal or experimental API namespace BPrivate { + +#if __cplusplus >= 201703L /*! \brief Experimental Network Services API @@ -631,4 +640,6 @@ namespace BPrivate { namespace Network { } +#endif + } \ No newline at end of file diff --git a/docs/user/net/UrlProtocolDispatchingListener.dox b/docs/user/net/UrlProtocolDispatchingListener.dox deleted file mode 100644 index 3b51a87580..0000000000 --- a/docs/user/net/UrlProtocolDispatchingListener.dox +++ /dev/null @@ -1,341 +0,0 @@ -/* - * 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. -
-*/ diff --git a/docs/user/net/UrlRequest.dox b/docs/user/net/UrlRequest.dox deleted file mode 100644 index 0dc13c060c..0000000000 --- a/docs/user/net/UrlRequest.dox +++ /dev/null @@ -1,266 +0,0 @@ -/* - * 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/UrlRequest.h hrev54384 - * src/kits/network/libnetapi/UrlRequest.cpp hrev54384 - */ - - -/*! - \file UrlRequest.h - \ingroup network - \brief Provides the BUrlRequest class. -*/ - - -/*! - \class BUrlRequest - \ingroup network - \brief Base class for URL request handlers. -*/ - - -/*! - \fn BUrlRequest::BUrlRequest(const BUrl& url, - BUrlProtocolListener* listener, BUrlContext* context, - const char* threadName, const char* protocolName) - \brief Create a BUrlRequest object. - - This constructor is only relevant to implementors of the interface. Users - wishing to create a request should refer to implementations like - BHttpRequest or BUrlProtocolRoster::MakeRequest(). - - \param url The URL in which resources will be requested from. - \param listener Pointer to a BUrlProtocolListener object for handling - events raised during the request. Can be \c NULL. - \param context Pointer to a BUrlContext. If \c NULL, a program-wide - context will be used instead. - \param threadName The name of the thread that will be spawned on Run(). - \param protocolName The name of the protocol handled by this BUrlRequest. -*/ - - -/*! - \fn virtual BUrlRequest::~BUrlRequest() - \brief The default destructor for BUrlRequest. - - This destructor will Stop() the request (if running) and release resources - held by the object. - - Since the destructor will only call the base version of Stop(), and not overriden methods, - implementations for each protocol must override this destructor to ensure that they do stop - all activity from the request. In particular, any spawned thread must be stopped before - the object is destroyed. -*/ - - -/*! - \fn virtual thread_id BUrlRequest::Run() - \brief Start the request. - - \returns The thread id of the request if successful, an error code - otherwise. - - For implementors, this base method will create a thread using - _ThreadEntry() as the entry point and fThreadName for the name of the - thread. The created thread id will be stored in fThreadId. fRunning - will then be set to \c true. - - Most implementations shouldn't have to reimplement this method. -*/ - - -/*! - \fn virtual status_t BUrlRequest::Stop() - \brief Stop the request. - - This method does not guarantee that the request will be stopped on return. - Users should wait for BUrlProtocolListener::RequestCompleted() as a - confirmation that the request has stopped before destroying the object. - - The base implementation of this method does nothing but set #fQuit to - \c true. - - \retval B_OK Operation successful. - \retval B_ERROR The request is not running. -*/ - - -/*! - \fn virtual void SetTimeout(bigtime_t timeout) - \brief Set the request transfer timeout. - - \note By default no timeout will be applied unless it was set with this - method. - - \param timeout The amount of time in microseconds should the request be - idle (no data received from the server) before dropping out. - - The base implementation of this method is a no-op. -*/ - - -/*! - \fn status_t BUrlRequest::SetUrl(const BUrl& url) - \brief Change the URL of the request. - - \param url The new URL to request from. - - This must be done before starting the request with Run. It is not possible - to change the URL while the request is running. - - \retval B_OK Operation successful. - \retval B_ERROR The request is running. - - \sa Url() for retrieving the request URL. -*/ - - -/*! - \fn status_t BUrlRequest::SetContext(BUrlContext* context) - \brief Change the context of the request. - - \param context The pointer to a BUrlContext. - - This must be done before starting the request with Run. It is not possible - to change the context while the request is running. - - \note Setting the \a context to \c NULL will use the program-wide default - context. This is the default also for requests where SetContext was - never called. - - \retval B_OK Operation successful. - \retval B_ERROR The request is running. - - \sa Context() -*/ - - -/*! - \fn status_t BUrlRequest::SetListener(BUrlProtocolListener* listener) - \brief Change the BUrlProtocolListener of the request. - - \param listener Pointer to the new listener object. Can be \c NULL. - - \retval B_OK Operation successful. - \retval B_ERROR The request is running. - - \sa Listener() -*/ - - -/*! - \fn const BUrl& BUrlRequest::Url() const - \brief Get the URL of the request. - - \sa SetUrl() -*/ - - -/*! - \fn BUrlContext* BUrlRequest::Context() const - \brief Get the context of the request. - - \sa SetContext() -*/ - - -/*! - \fn BUrlProtocolListener* BUrlRequest::Listener() const - \brief Get the BUrlProtocolListener of the request. - - \sa SetListener() -*/ - - -/*! - \fn const BString& BUrlRequest::Protocol() const - \brief Get the protocol that this object handles. -*/ - - -/*! - \fn bool BUrlRequest::IsRunning() const - \brief Whether the request thread is running. -*/ - - -/*! - \fn status_t BUrlRequest::Status() const - \brief Get the status of the request. - - \retval B_OK The request has completed successfully. - \retval B_BUSY The request is running. - \retval B_INTERRUPTED The request was cancelled. - - These are not the only errors that can be returned. The exact list - depends on the implementation of this class. -*/ - - -/*! - \fn virtual const BUrlResult& BUrlRequest::Result() const = 0 - \brief Get the BUrlResult associated with the request. -*/ - - -/*! - \fn static int32 BUrlRequest::_ThreadEntry(void* arg) - \brief The default entry point for threads spawned via Run() - - \param arg The pointer to the BUrlRequest that invoked Run(). - - This static method will do the following: - - Set the Status() to \c B_BUSY. - - Call _ProtocolSetup(). - - Call _ProtocolLoop(). The return value of this method will be set - as the Status(). - - If a valid listener is registered, this method calls - BUrlProtocolListener::RequestCompleted() to signify completion. - - This alone should be adequete for most protocol implementations. -*/ - - -/*! - \fn virtual void BUrlRequest::_ProtocolSetup() - \brief Setup the object state before entering the thread loop. - - The base implementation is a no-op. -*/ - - -/*! - \fn virtual status_t BUrlRequest::_ProtocolLoop() = 0 - \brief The thread loop that process the request. - - This method implements the main processing logic. The return value of this - method will be set as Status(). - - Implementations of this method should check #fQuit periodically as a flag to - stop the request, and should implement Stop() in a way that blocking calls - within the request can be interrupted. It's preferable that the request - can be stopped as soon as it's signalled. -*/ - - -/*! - \fn virtual void BUrlRequest::_EmitDebug(BUrlProtocolDebugMessage type, - const char* format, ...) - \brief Emit a debug message. - - If a listener is registered, this method invokes - BUrlProtocolListener::DebugMessage() with the formatted message. - - \param type The type of the debug message. - \param format The format string. This should a printf-compatible format - string. - \param ... Arguments to be formatted. -*/ - - diff --git a/docs/user/net/UrlResult.dox b/docs/user/net/UrlResult.dox deleted file mode 100644 index 90daac9011..0000000000 --- a/docs/user/net/UrlResult.dox +++ /dev/null @@ -1,119 +0,0 @@ -/* - * 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/UrlResult.h hrev54384 - * src/kits/network/libnetapi/UrlResult.cpp hrev54384 - */ - - -/*! - \file UrlResult.h - \ingroup network - \brief Provides the BUrlResult class. -*/ - - -/*! - \class BUrlResult - \ingroup network - \brief The result of a request made with BUrlRequest. - - This class contains the metadata acquired during a request made - with BUrlRequest. - - Note that subclasses are usually defined with protocol-specific information. - For example see BHttpResult for the result of a request using the HTTP - protocol. -*/ - - -/*! - \fn BUrlResult::BUrlResult() - \brief Create an uninitialized BUrlResult object. -*/ - - -/*! - \fn BUrlResult::BUrlResult(BMessage* archive) - \brief Create a BUrlResult object from a BMessage. - - \param archive The BMessage used to construct the object. - - \note Instantiate() should be used instead to verify whether the BMessage - can be used to construct the object. -*/ - - -/*! - \fn virtual status_t BUrlResult::Archive(BMessage* archive, bool deep) const - \brief Archive the object into a BMessage. - - \param archive Pointer to the BMessage object to archive into. - \param deep If \c true, all children of this object should be archived as - well. - - \retval B_OK The operation was successful. - \retval B_BAD_VALUE \a archive was \c NULL. - \retval B_ERROR An error occurred. - - \sa Instantiate() for construcing the object from the archived BMessage. -*/ - - -/*! - \fn void BUrlResult::SetContentType(BString contentType) - \brief Set the content type of the response. - - This method is used by a BUrlRequest object to set the content type - of the response. The content type should be a valid MIME type. - - \param contentType The content type to set to. - - \sa ContentType() for retrieving the set content type. -*/ - - -/*! - \fn void BUrlResult::SetLength(size_t length) - \brief Set the length of the response. - - This method is used by a BUrlRequest object to set the length of - the response. - - \param length The length to set to. - - \sa Length() for retrieving the set length. -*/ - - -/*! - \fn virtual BString BUrlResult::ContentType() const - \brief Get the MIME type of the response contents. - - \sa SetContentType() for setting the content type to be returned by this - method. -*/ - - -/*! - \fn virtual size_t BUrlResult::Length() const - \brief Get the length of the response. - - \sa SetLength() for setting the length to be returned by this method. -*/ - - -/*! - \fn static BArchivable* BUrlResult::Instantiate(BMessage* archive) - \brief Create a BUrlResult object from a BMessage. - - \param archive The BMessage to construct a BUrlResult from. - - \returns A pointer to the created BUrlResult, or \c NULL if unarchival - failed. -*/ diff --git a/docs/user/netservices/Geolocation.dox b/docs/user/netservices/Geolocation.dox deleted file mode 100644 index 8c5ce5f4f6..0000000000 --- a/docs/user/netservices/Geolocation.dox +++ /dev/null @@ -1,89 +0,0 @@ -/* - * Copyright 2019 Haiku, Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Adrien Destugues, pulkomandy@pulkomandy.tk - * - * Corresponds to: - * headers/private/netservices/Geolocation.h hrev54923 - * src/kits/network/libnetservices/Geolocation.cpp hrev54923 - */ - - -/*! - \file Geolocation.h - \ingroup netservices - \brief Geolocation and geocoding services. -*/ - - -/*! - \class BPrivate::Network::BGeolocation - \ingroup netservices - \brief Geolocation and geocoding services. - - Geolocation allows to know where the computer is currently located. - This is currently done by sending a list of Wifi networks within reach to - a 3rd party webservice (Mozilla location services), which uses a database - of known networks around the world to return an estimate position. - - Geocoding is about identifying places in a way more convenient than - latitude and longitude. This can include postal codes, country names, - street or building names, etc. This class allows to perform both geocoding - (finding a latitude and a longitude from a name) and reverse geocoding - (finding a suitable name for a given position). This service is provided - to haiku by the 3rd-party geonames.org - - Note that most of the methods in this class perform HTTPS requests to - 3rd-parties. When using it in your application, it is good practise to - first inform the user about what will be shared with these services, and - why that's needed. Of course, this also means using these services requires - internet access, and you may want to limit the number of calls, both to - save bandwidth and time, and to not overuse the provided API keys. If you - are going to do more than a few request per application run, you should - provide your own API keys instead. - - \since Haiku R1 -*/ - - -/*! - \fn BGeolocation::BGeolocation() - \brief Initialize a BGeolocation using the default services and API keys. - - Official builds of Haiku include a shared API key for both Mozilla Location - Services and geonames.org. You can use this constructor to use these keys - in your application. -*/ - - -/*! - \fn BGeolocation::BGeolocation(const BUrl& geolocationService, - const BUrl& geocodingService) - \brief Initialize a BGeolocation using custom services or API keys. - - You can use this constructor to provide your own URL to a webservice to - use for the requests. The services have to implement the MLS and geonames - API, respectively. - - If you want to override only one of the two URLs, the other can be passed - as an empty BUrl object. -*/ - - -/*! - \fn status_t BGeolocation::LocateSelf(float& latitude, float& longitude) - \brief Locate the computer by detecting nearby WiFi networks. - - This method makes a request to Mozilla Location Services. -*/ - - -/*! - \fn status_t BGeolocation::Country(float latitude, float longitude, - BCountry& country) - \brief Find which country a given set of coordinates is in. - - This method makes a request to geonames.org. -*/ diff --git a/docs/user/netservices/HttpAuthentication.dox b/docs/user/netservices/HttpAuthentication.dox deleted file mode 100644 index 09c3f81e90..0000000000 --- a/docs/user/netservices/HttpAuthentication.dox +++ /dev/null @@ -1,117 +0,0 @@ -/* - * Copyright 2013 Haiku, Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Adrien Destugues, pulkomandy@pulkomandy.tk - * - * Corresponds to: - * headers/private/netservices/HttpAuthentication.h hrev54923 - * src/kits/network/libnetservices/HttpAuthentication.cpp hrev54923 - */ - -/*! - \file HttpAuthentication.h - \ingroup netservices - \brief Authentication token for use in HTTP protocol communications. -*/ - -/*! - \class BPrivate::Network::BHttpAuthentication - \ingroup netservices - \brief Authentication token for the HTTP protocol. - - This class allows managing of an authenticated http session. It stores the - authentication credentials and realm and provides tools for generating the - required nonces and hashes. - - An instance of this class should be used for the whole length of an HTTP - authenticated session. Initialize it by calling Initialize() and setting the - username and password (from the constructor or the setter methods). Then, - for each page that requires authentication, generate a token using the - Authorization() method. -*/ - -/*! - \fn BHttpAuthentication::BHttpAuthentication() - \brief Default constructor. - - This will create an unconfigured authentication object with the - authentication method set to B_HTTP_AUTHENTICATION_NONE. - - You have to set the username and password, and initialize the object using - the Initialize method with proper authentication data. -*/ - -/*! - \fn BHttpAuthentication::BHttpAuthentication(const BString& username, - const BString& password) - \brief Create an authentication session with the given name and password. - - The authentication method is set to B_HTTP_AUTHENTICATION_NONE. - This object can then be used with the Initialize method to bind it to an - HTTP authenticated session. -*/ - -/*! - \fn void BHttpAuthentication::SetUserName(const BString& username) - \brief Set the user name. - - \param username the new user name. -*/ - -/*! - \fn void BHttpAuthentication::SetPassword(const BString& password) - \brief Set the password - - \param password the new password. -*/ - -/*! - \fn void BHttpAuthentication::SetMethod(BHttpAuthenticationMethod method) - \brief Set the authentication method - - \param method the new authentication method. -*/ - -/*! - \fn status_t BHttpAuthentication::Initialize(const BString& wwwAuthenticate) - \brief Initialize the object from the given authentication data - - This method will parse the given authentication challenge and initialize - the authentication type to either B_HTTP_AUTHENTICATION_BASIC or - B_HTTP_AUTHENTICATION_DIGEST. The authentication parameters (realm, nonce, - algorithm) and state (opaque, stale) are also parsed and stored. - - \param wwwAuthenticate the value of the WWW-Authenticate HTTP header field. - \return B_OK if the request was parsed, B_ERROR if there is a parsing error, - B_BAD_VALUE if the authentication string is empty. -*/ - -/*! - \fn const BString& BHttpAuthentication::UserName() const - \returns the user name. -*/ - -/*! - \fn const BString& BHttpAuthentication::Password() const - \returns the password. -*/ - -/*! - \fn BHttpAuthenticationMethod BHttpAuthentication::Method() const - \returns the authentication method -*/ - -/*! - \fn BString BHttpAuthentication::Authorization(const BUrl& url, - const BString& method) const - \brief Generate an authentication reply for the given URL and method. - - For basic authentication, the reply is constant and is a Base64 encoding of - the string made of 'username:password'. In digest mode, each request will - have a different reply, so you must call this method for each page you want - to authenticate with. - - \return the generated reply -*/ diff --git a/docs/user/netservices/HttpForm.dox b/docs/user/netservices/HttpForm.dox deleted file mode 100644 index f9c673a8df..0000000000 --- a/docs/user/netservices/HttpForm.dox +++ /dev/null @@ -1,405 +0,0 @@ -/* - * Copyright 2010-2013 Haiku, Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Adrien Destugues, pulkomandy@pulkomandy.tk - * John Scipione, jscipione@gmail.com - * - * Corresponds to: - * headers/private/netservices/HttpForm.h hrev54923 - * src/kits/network/libnetservices/HttpForm.cpp hrev54923 - */ - - -/*! - \file HttpForm.h - \ingroup netservices - \brief Management of HTTP form data -*/ - - -/*! - \enum BPrivate::Network::form_type - \ingroup netservices -*/ - - -/*! - \var form_type B_HTTP_FORM_URL_ENCODED -*/ - - -/*! - \var form_type B_HTTP_FORM_MULTIPART -*/ - - -/*! - \enum BPrivate::Network::form_content_type - \ingroup netservices -*/ - - -/*! - \var form_content_type B_HTTPFORM_UNKNOWN -*/ - - -/*! - \var form_content_type B_HTTPFORM_STRING -*/ - - -/*! - \var form_content_type B_HTTPFORM_FILE -*/ - - -/*! - \var form_content_type B_HTTPFORM_BUFFER -*/ - - -/*! - \class BPrivate::Network::BHttpFormData - \ingroup netservices - \brief Stores a form data entry sent or received during an HTTP request. - - Each element in a form is stored in an instance of this class. The values - can be either strings, arbitrary binary buffers, or a pointer to a file. - - The latter allows reading data from the file as it is being sent through - the network, removing hte need to buffer the whole file contents in memory. -*/ - - -/*! - \fn BHttpFormData::BHttpFormData(const BString& name, const BString& value) - \brief Construct a BHttpFormData object with a string value. -*/ - - -/*! - \fn BHttpFormData::BHttpFormData(const BString& name, const BPath& file) - \brief Construct a BHttpFormData object which value is a file contents -*/ - - -/*! - \fn BHttpFormData::BHttpFormData(const BString& name, const void* buffer, - ssize_t size) - \brief Construct a BHttpFormData object which value is a binary buffer. -*/ - - -/*! - \fn bool BHttpFormData::InitCheck() const - \brief Checks the initialization of the object - - \return \c false if attempting to construct a BHttpFormData with a \c NULL - buffer. -*/ - - -/*! - \fn const BString& BHttpFormData::Name() const - \brief Get the form field name -*/ - - -/*! - \fn const BString& BHttpFormData::String() const - \brief Get the string value of a form field. - - \return An empty string for buffer and file based fields. -*/ - - -/*! - \fn const BPath& BHttpFormData::File() const - \brief Get the file path of a form field. - - \return An empty string for buffer and string based fields. -*/ - - -/*! - \fn const void* BHttpFormData::Buffer() const - \brief Get a pointer to the data of a form field. - - \return An empty string for string and file based fields -*/ - - -/*! - \fn ssize_t BHttpFormData::BufferSize() const; - \brief Get the buffer size - - \return 0 for string and file based fields. -*/ - - -/*! - \fn bool BHttpFormData::IsFile() const - \return \c true if the field data is a file. -*/ - - -/*! - \fn const BString& BHttpFormData::Filename() const; - \return The name of the file, for file based fields. -*/ - - -/*! - \fn const BString& BHttpFormData::MimeType() const - \return The MIME type of the data. -*/ - - -/*! - \fn form_content_type BHttpFormData::Type() const - \return The kind of field. -*/ - - -/*! - \fn status_t BHttpFormData::CopyBuffer() - \brief Make a copy of the internal buffer - - The constructor for buffer-based fields does not copy the data given to it, - it just keeps a pointer. If you want to retain ownership of the data, call - this method so the buffer copies and releases it. -*/ - - -/*! - \fn status_t BHttpFormData::MarkAsFile(const BString& filename, - const BString& mimeType) - \brief Mark a field as a file. -*/ - - -/*! - \fn void BHttpFormData::UnmarkAsFile() - \brief Unmark a field as a file. -*/ - - -/*! - \fn status_t BHttpFormData::CopyBuffer() -*/ - - -/*! - \fn BHttpFormData& BHttpFormData::operator=(const BHttpFormData& other) - \brief Assignment operator. -*/ - - -/*! - \class BPrivate::Network::BHttpForm - \ingroup netservices - \brief Container for all the BHttpFormData instances making up an HTTP form contents. -*/ - - -/*! - \fn BHttpForm::BHttpForm() - \brief Create a new form object. -*/ - - -/*! - \fn BHttpForm::BHttpForm(const BHttpForm& other) - \brief Create a new form object as a copy of \a other. -*/ - - -/*! - \fn BHttpForm::BHttpForm(const BString& formString) - \brief Create a new form object and parse the \a formString. -*/ - - -/*! - \fn BHttpForm::~BHttpForm() - \brief Clear the form and destroy the form object. -*/ - - -/*! - \fn void BHttpForm::ParseString(const BString& formString) - \brief Parse the \a formString. -*/ - - -/*! - \fn BString BHttpForm::RawData() const - \brief Return the form's raw data as a BString. -*/ - - -/*! - \fn status_t BHttpForm::AddString(const BString& fieldName, - const BString& value) - \brief Add a string to the form with the specified \a fieldName and \a value. -*/ - - -/*! - \fn status_t BHttpForm::AddInt(const BString& fieldName, int32 value) - \brief Add an int to the form with the specified \a fieldName and \a value. -*/ - - -/*! - \fn status_t BHttpForm::AddFile(const BString& fieldName, const BPath& file) - \brief Add a file to the form with the specified \a fieldName and \a value. -*/ - - -/*! - \fn status_t BHttpForm::AddBuffer(const BString& fieldName, - const void* buffer, ssize_t size) - \brief Add a buffer to the form with the specified \a fieldName and \a buffer - and \a size. -*/ - - -/*! - \fn status_t BHttpForm::AddBufferCopy(const BString& fieldName, - const void* buffer, ssize_t size) -*/ - - -/*! - \fn void BHttpForm::MarkAsFile(const BString& fieldName, - const BString& filename, const BString& mimeType) -*/ - - -/*! - \fn void BHttpForm::MarkAsFile(const BString& fieldName, - const BString& filename) - \brief Mark a field as a filename. -*/ - - -/*! - \fn void BHttpForm::UnmarkAsFile(const BString& fieldName) - \brief Unmark a field as a filename. -*/ - - -/*! - \fn void BHttpForm::SetFormType(form_type type) - \brief Change form type. -*/ - - -/*! - \fn bool BHttpForm::HasField(const BString& name) const - \brief Returns whether or not a form has a field with the specified \a name. -*/ - - -/*! - \fn BString BHttpForm::GetMultipartHeader(const BString& fieldName) const -*/ - - -/*! - \fn form_type BHttpForm::GetFormType() const -*/ - - -/*! - \fn const BString& BHttpForm::GetMultipartBoundary() const -*/ - - -/*! - \fn BString BHttpForm::GetMultipartFooter() const -*/ - - -/*! - \fn ssize_t BHttpForm::ContentLength() const -*/ - - -/*! - \fn BHttpForm::Iterator BHttpForm::GetIterator() -*/ - - -/*! - \fn void BHttpForm::Clear() -*/ - - -/*! - \fn BHttpFormData& BHttpForm::operator[](const BString& name) -*/ - - -/*! - \fn void BHttpForm::_ExtractNameValuePair(const BString& formString, int32* index) -*/ - - -/*! - \fn void BHttpForm::_GenerateMultipartBoundary() -*/ - - -/*! - \fn void BHttpForm::Clear() -*/ - - -/*! - \class BPrivate::Network::BHttpForm::Iterator - \ingroup netservices - \brief Form Iterator. -*/ - - -/*! - \fn BHttpForm::Iterator::Iterator(BHttpForm* form) - \brief Constructor. -*/ - - -/*! - \fn BHttpForm::Iterator::Iterator(const Iterator& other); - \brief Copy contstructor. -*/ - - -/*! - \fn bool BHttpForm::Iterator::HasNext() const -*/ - - -/*! - \fn BHttpFormData* BHttpForm::Iterator::Next() -*/ - - -/*! - \fn void BHttpForm::Iterator::Remove() -*/ - - -/*! - \fn BString BHttpForm::Iterator::MultipartHeader() -*/ - - -/*! - \fn BHttpForm::Iterator& BHttpForm::Iterator::operator=(const Iterator& other) - \brief Assignment operator. -*/ diff --git a/docs/user/netservices/HttpHeaders.dox b/docs/user/netservices/HttpHeaders.dox deleted file mode 100644 index b93f05908f..0000000000 --- a/docs/user/netservices/HttpHeaders.dox +++ /dev/null @@ -1,182 +0,0 @@ -/* - * Copyright 2013 Haiku, Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Adrien Destugues, pulkomandy@pulkomandy.tk - * - * Corresponds to: - * headers/private/netservices/HttpHeaders.h hrev54923 - * src/kits/network/libnetservices/HttpHeaders.cpp hrev54923 - */ - -/*! - \file HttpHeaders.h - \ingroup netservices - \brief Management of HTTP headers -*/ - -/*! - \class BPrivate::Network::BHttpHeader - \ingroup netservices - \brief Represent a single header field for an HTTP connection - - HTTP headers are key-value pairs, where both the key and the value are - strings. The main purpose of this class is storing the pair and encoding it - to the HTTP protocol format, where some characters have to be escaped. -*/ - -/*! - \fn BHttpHeader::BHttpHeader() - \brief Default constructor. - - The header is initialized with empty key and value. -*/ - -/*! - \fn BHttpHeader::BHttpHeader(const char* string) - \brief Construct a BHttpHeader from an already encoded string - - The given string should be in the form "key:value" with all special - characters properly escaped. There is no way to detect parsing errors when - the given string is not properly formatted. Consider using SetHeader() - instead, where this can be checked. - - \param string the http-encoded header to parse -*/ - -/*! - \fn BHttpHeader::BHttpHeader(const char* name, const char* value) - \brief Construct a BHttpHeader from an unencoded key-value pair. - - \param name the key - \param value the value -*/ - -/*! - \fn BHttpHeader::BHttpHeader(const BHttpHeader& copy) - \brief Copy constructor. -*/ - -/*! - \fn void BHttpHeader::SetName(const char* name) - \brief Sets the key for this header. - - The key is trimmed (BString::Trim()) to remove any whitespace. - - \param name the new key -*/ - -/*! - \fn void BHttpHeader::SetValue(const char* value) - \brief Sets the value for this header. - - The value is trimmed (BString::Trim()) to remove any whitespace. - - \param value the new value -*/ - -/*! - \fn bool BHttpHeader::SetHeader(const char* string) - \brief Parse the given string and configure this object - - Extracts and decode the name and value from the given string. - - \param string the header data to parse - \return wether parsing succeeded -*/ - -/*! - \fn const char* BHttpHeader::Name() const - \return the key for this header -*/ - -/*! - \fn const char* BHttpHeader::Value() const - \return the value for this header -*/ - -/*! - \fn const char* BHttpHeader::Header() const - \return the encoded header -*/ - -/*! - \fn bool BHttpHeader::NameIs(const char* name) const - \brief Compare this header name with the given one - - Both names are trimmed from whitespace, and the comparison is not case - sensitive (as per the HTTP specification). -*/ - -/*! - \class BPrivate::Network::BHttpHeaders - \ingroup netservices - \brief Container for a set of HTTP headers. - - This class allows management of the set of headers for a single HTTP - transaction. They are stored in a list and can be iterated on. -*/ - -/*! - \fn BHttpHeaders::BHttpHeaders() - \brief Construct an empty header list. -*/ - -/*! - \fn BHttpHeaders::BHttpHeaders(const BHttpHeaders& copy) - \brief Copy constructor - - A deep copy is performed, so modifying the headers in the copy does not - change the original. -*/ - -/*! - \fn const char* BHttpHeaders::HeaderValue(const char* name) const - \return the value mapped to the given key, or NULL if not found. -*/ - -/*! - \fn BHttpHeader& BHttpHeaders::HeaderAt(int32 index) const - \brief Find header by position - - \param index must be in bounds, else this method will crash. - \see CountHeaders() -*/ - -/*! - \fn int32 BHttpHeaders::CountHeaders() const - \return the number of entries in this set -*/ - -/*! - \fn int32 BHttpHeaders::HasHeader(const char* name) const - \brief Find an header by key - \return The index of the header for use with HeaderAt(), or B_ERROR if not - found. -*/ - -/*! - \fn bool BHttpHeaders::AddHeader(const char* line) - \brief Add a new header to the list, from an HTTP header line. - - Duplicates headers are allowed. - - \return false when out of memory. -*/ - -/*! - \fn bool BHttpHeaders::AddHeader(const char* name, const char* value) - \brief Add a new header from the given key:value pair -*/ - -/*! - \fn bool BHttpHeaders::AddHeader(const char* name, int32 value) - \brief Convenience method to add a header with a numeric value. -*/ - -/*! - \fn void BHttpHeaders::Clear() - \brief Remove all HTTP headers from the list -*/ - diff --git a/docs/user/netservices/HttpRequest.dox b/docs/user/netservices/HttpRequest.dox deleted file mode 100644 index cf40b48cd4..0000000000 --- a/docs/user/netservices/HttpRequest.dox +++ /dev/null @@ -1,182 +0,0 @@ -/* - * Copyright 2013 Haiku, Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Adrien Destugues, pulkomandy@pulkomandy.tk - * John Scipione, jscipione@gmail.com - * - * Corresponds to: - * headers/private/netservices/HttpRequest.h hrev54923 - * src/kits/network/libnetservices/HttpRequest.cpp hrev54923 - */ - - -/*! - \file HttpRequest.h - \ingroup netservices - \brief Management of HTTP or HTTPS protocol requests -*/ - - -/*! - \class BPrivate::Network::BHttpRequest - \ingroup netservices - \brief Handles a request over HTTP or HTTPS. - - Instances of ths class will be created by the BUrlProtocolRoster for - BUrl with the "http" or "https" protocol. The HTTP protocol is - implemented as specified in RFC2616. The request headers and body can be - customized, then sent to the server. The reply is then parsed and made - available to the application. - - This class only implements the client-side part of HTTP, it can't be used - to build an HTTP server. -*/ - - -/*! - \fn void BHttpRequest::SetMethod(const char* method) - \brief Set the HTTP method. - - You can use either one of the standard methods (B_HTTP_GET is the default) - or a custom one. The standard methods are B_HTTP_GET, B_HTTP_POST, - B_HTTP_PUT, B_HTTP_DELETE, B_HTTP_HEAD, B_HTTP_OPTIONS, B_HTTP_TRACE and - B_HTTP_CONNECT. -*/ - - -/*! - \fn void BHttpRequest::SetFollowLocation(bool follow) - \brief Enable or disable following HTTP redirects. - - An HTTP server can redirect a request to another address, either on the - same host or elsewhere. When FollowLocation is set (the default), these - redirections will be followed until an actual page (or an error) is found. - When it is unset, the redirection will not be followed and will be reported - to the client. -*/ - - -/*! - \fn void BHttpRequest::SetMaxRedirections(int8 maxRedirections) - \brief Set the maximal number of redirections to follow before giving up. - - This is only useful when SetFollowLocation is enabled. It will abort - the request after the given number of redirections. This avoids and helps - diagnosing redirection cycles, where two addresses redirect to each other. - - The default is to follow at most 8 redirections before giving up. -*/ - - -/*! - \fn void BHttpRequest::SetReferrer(const BString& referrer) - \brief Set the referrer. - - The referrer is a string sent to the server in the "Referrer:" HTTP header - field. It helps the server know where the request comes from. When - following a link in an HTML page, this is usually set to the URL of that - page. -*/ - - -/*! - \fn void BHttpRequest::SetUserAgent(const BString& userAgent) - \brief Set the user agent. - - The user agent is an identifier for the client sending an HTTP request. - Some servers will use this to send different content depending on the - software asking for a page. - - The default user agent is "Services Kit (Haiku)". -*/ - - -/*! - \fn void BHttpRequest::SetHeaders(const BHttpHeaders& headers) - \brief Set the HTTP headers. - - This method replaces the whole set of headers for this request with a copy - of the given ones. - - \param headers the header template to copy from. -*/ - - -/*! - \fn void BHttpRequest::AdoptHeaders(BHttpHeaders* const headers) - \brief Set the HTTP headers. - - This method replaces the whole set of headers for this request. It takes - ownership of the parameter, which must not be used afterwards. -*/ - - -/* - \fn void BHttpRequest::SetDiscardDate(bool discard) - - This is currently unused. -*/ - - -/* - \fn void BHttpRequest::DisableListener(bool disable) - This is currently unused. -*/ - - -/*! - \fn void BHttpRequest::SetAutoReferrer(bool enable) - \brief Automatically set the referrer when the request is done. - - This allows HttpRequest to manage the referrer automatically. Each request - will set the referrer to its own URL so the next request automatically - uses that one. -*/ - - -/*! - \fn void BHttpRequest::SetPostFields(const BHttpForm& fields) - \brief Set the fields for form POST data. - - Replaces the content of the request with a copy of the given POST fields. -*/ - - -/*! - \fn void BHttpRequest::AdoptPostFields(BHttpForm* const fields) - \brief Set the fields for form POST data. - - Replaces the content of the request with the given POST fields. - - This method takes ownership of the given form, which must not be used - elsewhere afterwards. -*/ - - -/*! - \fn void BHttpRequest::AdoptInputData(BDataIO* const data, const ssize_t size = -1) - \brief Set the request body. - - If the size is -1 (the default), the data will be sent using chunked - transfers. If the size is known, it will be sent using the Content-Length - header and non-chunked mode. - - You should set the size whenever possible, as some servers will not handle - chunked mode properly in all cases. - - This method takes ownership of the data, which must not be used elsewhere. -*/ - - -/*! - \fn void BHttpRequest::SetUserName(const BString& userName) - \brief Set the user name for HTTP authentication. -*/ - - -/*! - \fn void BHttpRequest::SetPassword(const BString& password) - \brief Set the user password for HTTP authentication. -*/ diff --git a/docs/user/netservices/UrlProtocolAsynchronousListener.dox b/docs/user/netservices/UrlProtocolAsynchronousListener.dox deleted file mode 100644 index 9bbce7639e..0000000000 --- a/docs/user/netservices/UrlProtocolAsynchronousListener.dox +++ /dev/null @@ -1,70 +0,0 @@ -/* - * Copyright 2020 Haiku, Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Leorize, leorize+oss@disroot.org - * - * Corresponds to: - * headers/private/netservices/UrlProtocolAsynchronousListener.h hrev54923 - * src/kits/network/libnetapi/UrlProtocolAsynchronousListener.cpp hrev54923 - */ - - -/*! - \file UrlProtocolAsynchronousListener.h - \ingroup netservices - \brief Provides the BUrlProtocolAsynchronousListener interface. -*/ - - -/*! - \class BPrivate::Network::BUrlProtocolAsynchronousListener - \ingroup netservices - \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. -*/ diff --git a/docs/user/netservices/UrlProtocolListener.dox b/docs/user/netservices/UrlProtocolListener.dox deleted file mode 100644 index c857363b02..0000000000 --- a/docs/user/netservices/UrlProtocolListener.dox +++ /dev/null @@ -1,198 +0,0 @@ -/* - * Copyright 2020 Haiku, Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Leorize, leorize+oss@disroot.org - * - * Corresponds to: - * headers/private/netservices/UrlProtocolListener.h hrev54923 - * src/kits/network/libnetapi/UrlProtocolListener.cpp hrev54923 - */ - - -/*! - \file UrlProtocolListener.h - \ingroup netservices - \brief Provides the BUrlProtocolListener abstract interface. -*/ - - -/*! - \enum BPrivate::Network::BUrlProtocolDebugMessage - \brief The type of the debug message. -*/ - - -/*! - \var B_URL_PROTOCOL_DEBUG_TEXT - \brief Informational debug message. -*/ - - -/*! - \var B_URL_PROTOCOL_DEBUG_ERROR - \brief Error debug message. -*/ - - -/*! - \var B_URL_PROTOCOL_DEBUG_HEADER_IN - \brief Debug messages related to metadata received. -*/ - - -/*! - \var B_URL_PROTOCOL_DEBUG_HEADER_OUT - \brief Debug messages related to metadata sent. -*/ - - -/*! - \var B_URL_PROTOCOL_DEBUG_TRANSFER_IN - \brief Debug messages related to data received. -*/ - - -/*! - \var B_URL_PROTOCOL_DEBUG_TRANSFER_OUT - \brief Debug messages related to data sent. -*/ - - -/*! - \class BPrivate::Network::BUrlProtocolListener - \ingroup netservices - \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) - \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. -*/ - -/*! - \fn virtual void BUrlProtocolListener::BytesWritten(BUrlRequest* caller, - size_t size) - \brief Called each time a block of data is written. - - This callback is called whenever a block of data is written to the - BDataIO associated with the request. If no BDataIO is associated, the - callback will not be invoked. - - \b Frequency: Zero or more - - \param caller The BUrlRequest that invoked this callback. - \param size Size of the written data block. -*/ - -/*! - \fn virtual void BUrlProtocolListener::DownloadProgress(BUrlRequest* caller, - off_t bytesReceived, off_t bytesTotal) - \brief Called each time a block of data is downloaded. - - This callback might still be invoked even when no BDataIO is associated - with the request, as data can still be downloaded and discarded so that the - request can be completed and the socket can be reused. - - \b Frequency: Zero or more - - \param caller The BUrlRequest that invoked this callback. - \param bytesReceived Number of data bytes received. This is the number of - bytes received prior to any processing and can be smaller than the - size of the data block written to the output BDataIO as the transport - might be compressed. - \param bytesTotal Total number of data bytes expected. \c 0 will be passed - if the total number of data bytes is not available. -*/ - -/*! - \fn virtual void BUrlProtocolListener::UploadProgress(BUrlRequest* caller, - off_t bytesSent, off_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/docs/user/netservices/UrlProtocolRoster.dox b/docs/user/netservices/UrlProtocolRoster.dox deleted file mode 100644 index dd53e223ca..0000000000 --- a/docs/user/netservices/UrlProtocolRoster.dox +++ /dev/null @@ -1,44 +0,0 @@ -/* - * Copyright 2020 Haiku, Inc. All rights reserved. - * Distributed under the terms of the MIT License. - * - * Authors: - * Leorize, leorize+oss@disroot.org - * - * Corresponds to: - * headers/private/netservices/UrlProtocolRoster.h hrev54923 - * src/kits/network/libnetservices/UrlProtocolRoster.cpp hrev54923 - */ - - -/*! - \file UrlProtocolRoster.h - \ingroup netservices - \brief Provides the BUrlProtocolRoster interface. -*/ - - -/*! - \class BPrivate::Network::BUrlProtocolRoster - \ingroup netservices - \brief Interfaces for protocol-agnostic operations. -*/ - - -/*! - \fn static BUrlRequest* BUrlProtocolRoster::MakeRequest(const BUrl& url, - BDataIO* output, 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 output The BDataIO to output to - \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. -*/