nlib
nn::nlib::CurlInputStream Class Referencefinal

The stream class for downloading using libcurl. More...

#include "nn/nlib/CurlInputStream.h"

+ Inheritance diagram for nn::nlib::CurlInputStream:

Public Member Functions

CURL * GetEasyHandle () const noexcept
 Returns a libcurl easy_handle. More...
 
CURLcode GetCurlError () const noexcept
 Returns the error code that occurs in a function that takes a libcurl easy_handle as the argument. More...
 
CURLMcode GetCurlMultiError () const noexcept
 Returns the error code that occurs in a function that takes a libcurl multi_handle as the argument. More...
 
errno_t Init (BufferSize buffer_size) noexcept
 Initializes a stream. More...
 
errno_t Init () noexcept
 Executes Init(kBufferSize1x).
 
CURLcode SetUrl (const char *url) noexcept
 Sets the URL to be read. More...
 
bool StartDownload () noexcept
 
Basic Member Functions
constexpr CurlInputStream () noexcept
 Instantiates the object with default parameters (default constructor). The stream must be initialized with Init().
 
virtual ~CurlInputStream () noexcept override
 Destructor. More...
 
- Public Member Functions inherited from nn::nlib::InputStream
errno_t GetErrorValue () const noexcept
 Gets the error value. More...
 
size_t Pos () const noexcept
 Returns the current position in the stream. More...
 
uint64_t Pos64 () const noexcept
 Returns the current position in the stream as a 64-bit value. More...
 
bool IsEos () noexcept
 Returns true if the stream is finished being read through to the end. If the stream has not been read through to the end, or if an error occurs, the function returns false. More...
 
int Read () noexcept
 Reads one byte of data from the stream. More...
 
int Peek () noexcept
 Reads the next byte without consuming the stream. More...
 
size_t Skip (size_t nbytes) noexcept
 Skips over the number of bytes specified by nbytes. More...
 
size_t Read (void *ptr, size_t nbytes) noexcept
 Reads the number of bytes of data specified by nbytes into the memory region specified by ptr. More...
 
bool Close () noexcept
 Closes the stream. Returns true if successful. More...
 
 operator bool () const
 Returns true if no internal error has occurred.
 
constexpr InputStream () noexcept
 Instantiates the object. This function is called from the derived class.
 
virtual ~InputStream () noexcept
 Destructor. This function is called from the derived class.
 

Additional Inherited Members

- Protected Member Functions inherited from nn::nlib::InputStream
void ResetBuffer (void *p, size_t nbytes) noexcept
 Sets the buffer held by InputStream. More...
 
void SetError (errno_t e) const noexcept
 Sets an error to InputStream. More...
 

Detailed Description

The stream class for downloading using libcurl.

Description
By using this class, you can handle data obtained with libcurl through the InputStream interface. The following code is a common implementation for using the class.
if (nlib_is_error(stream.Init())) {
// ERROR
}
stream.SetUrl("http://www.nintendo.co.jp/");
if (nlib_is_error(stream.StartDownload())) {
// ERROR
}
int c;
while ((c = stream.Read()) != -1) {
// process data
....
}
if (nlib_is_error(s)) {
// ERROR
}
stream.Close(); // 'stream' is reusable after Close().
The transition of the object state.
The overview of the object state transitions is described below:
dot_inline_dotgraph_5.png

Definition at line 31 of file CurlInputStream.h.

Constructor & Destructor Documentation

◆ ~CurlInputStream()

nn::nlib::CurlInputStream::~CurlInputStream ( )
overridevirtualnoexcept

Destructor.

Description
curl_multi_cleanup() and curl_easy_cleanup() are executed internally.

Member Function Documentation

◆ GetCurlError()

nn::nlib::CurlInputStream::GetCurlError ( ) const
noexcept

Returns the error code that occurs in a function that takes a libcurl easy_handle as the argument.

Returns
The CURLcode type value.
Description
If the stream returns an error caused by libcurl, you can get the error code. For more information about the error code, see the libcurl manual.
See also
http://curl.haxx.se/libcurl/c/libcurl-errors.html#CURLcode

◆ GetCurlMultiError()

nn::nlib::CurlInputStream::GetCurlMultiError ( ) const
noexcept

Returns the error code that occurs in a function that takes a libcurl multi_handle as the argument.

Returns
The CURLMode type value.
Description
If the stream returns an error caused by libcurl, you can get the error code. For more information about the error code, see the libcurl manual.
See also
http://curl.haxx.se/libcurl/c/libcurl-errors.html#CURLMcode

◆ GetEasyHandle()

nn::nlib::CurlInputStream::GetEasyHandle ( ) const
noexcept

Returns a libcurl easy_handle.

Returns
A libcurl easy_handle.
Description
This must be used to set options after executing Init().
See also
http://curl.haxx.se/libcurl/c/curl_easy_setopt.html

◆ Init()

nn::nlib::CurlInputStream::Init ( BufferSize  buffer_size)
noexcept

Initializes a stream.

Parameters
[in]buffer_sizeThe buffer size retained by the stream.
Return values
0Success.
EALREADYAlready initialized.
ENOMEMMemory has failed to be allocated or the libcurl handle has failed to be initialized.
ENOTSUPAn option has failed to be set due to reasons such as an obsolete libcurl.
Description
Sets the buffer size for a stream with an argument.
buffer_size The buffer size of a stream.
kBufferSize1x CURL_MAX_WRITE_SIZE
kBufferSize2x CURL_MAX_WRITE_SIZE * 2
kBufferSize3x CURL_MAX_WRITE_SIZE * 3
kBufferSize4x CURL_MAX_WRITE_SIZE * 4
After allocating a stream buffer, the handle is initialized by curl_easy_init(), curl_multi_init(), and curl_multi_add_handle(). Then sets the following options with curl_easy_setopt().
Option Name Value
CURLOPT_WRITEFUNCTION The internal callback function of CurlInputStream
CURLOPT_WRITEDATA The internal region of CurlInputStream
CURLOPT_TIMEOUT 5
CURLOPT_LOW_SPEED_LIMIT 1024
CURLOPT_LOW_SPEED_TIME 5
CURLOPT_FOLLOWLOCATION 1
CURLOPT_MAXREDIRS 8
CURLOPT_ACCEPT_ENCODING "gzip,deflate"
After executing this function, you need to obtain easy_handle using GetEasyHandle() and set behavior options for URLs and others. However, never overwrite the CURLOPT_WRITEFUNCTION and CURLOPT_WRITEDATA settings.

◆ SetUrl()

nn::nlib::CurlInputStream::SetUrl ( const char *  url)
noexcept

Sets the URL to be read.

Parameters
[in]urlThe URL string.
Returns
The CURLcode type value.
Description
Using curl_easy_setopt()internally, sets the CURLOPT_URL option.

◆ StartDownload()

nn::nlib::CurlInputStream::StartDownload ( )
noexcept
Returns
Returns true when successful.
Description
Starts reading a stream by executing this function. Although you may read a stream using Read() instead of calling this function, the reading operation blocks until data has been received. You can use this function if you want to perform some processing after you have started reading a stream but before it is actually read.
If the stream has failed to be read, sets an error to the stream.

The documentation for this class was generated from the following files: