ost::URLStream(3)

📦 version 1.8.1, in ubuntu jammy

💖 ost::URLStream(3) — Library Functions Manual 💖

okay bestie, gather round, because today we're learning about ost::URLStream, and it's genuinely such a slay little class. it lives in section 3 of the manual (that's the library functions girlies), and it is, no cap, a URL processing version of TCPStream. that's the whole vibe. periodt. ✨

✨ NAME ✨

ost::URLStream — a URL processing version of TCPStream. 💅

🌸 SYNOPSIS 🌸

#include <url.h>

Inherits ost::TCPStream. yes she's got lineage, she's a nepo baby and we love that for her 🫶

🌈 Public Types 🌈

  • enum Error — return error for url fetch. values: errSuccess = 0, errUnreachable, errMissing, errDenied, errInvalid, errForbidden, errUnauthorized, errRelocated, errFailure, errTimeout, errInterface
  • enum Authentication — type of authentication. values: authAnonymous = 0, authBasic
  • enum Encoding — encoding used in transfer. values: encodingBinary = 0, encodingChunked
  • enum Method — type of fetch. values: methodHttpGet, methodHttpPut, methodHttpPost, methodHttpPostMultipart, methodFtpGet, methodFtpPut, methodFileGet, methodFilePut
  • enum Protocol — http protocol version. values: protocolHttp1_0, protocolHttp1_1

🦋 Public Member Functions 🦋

  • URLStream (Family family=IPV4, timeout_t timer=0) — construct an instance of URL stream.
  • URLStream & getline (char *buffer, size_t len) — line parsing with conversion.
  • Error get (const char *url, size_t buffer=512) — get URL data from a named stream of a known buffer size.
  • Error get (size_t buffer=512) — get URL data from a named stream of a known buffer size.
  • Error submit (const char *url, const char **vars, size_t buffer=512) — submit URL with vars passed as argument array.
  • Error post (const char *url, const char **vars, size_t buffer=512) — post URL vars with post method.
  • Error post (const char *url, MIMEMultipartForm &form, size_t buffer=512) — post URL with MIME multipart form.
  • Error head (const char *url, size_t buffer=512) — used to fetch header information for a resource.
  • void close () — close the URL stream for a new connection.
  • void setReferer (const char *str) — set the referer url.
  • void setHost (const char *str) — set the host for the url.
  • void setAddress (const char *str) — set the address for the url.
  • void setCookie (const char *str) — set the cookie to pass.
  • void setUser (const char *str) — set user id for the url.
  • void setPassword (const char *str) — set password for the url.
  • void setAuthentication (Authentication a, const char *str=NULL) — set authentication type for the url.
  • void setProxyUser (const char *str) — set proxy user id for the url.
  • void setProxyPassword (const char *str) — set proxy password for the url.
  • void setProxyAuthentication (Authentication a, const char *str=NULL) — set proxy authentication type for the url.
  • void setPragma (const char *str) — set the pragmas.
  • void setProxy (const char *host, tpport_t port) — set the proxy server used.
  • void setAgent (const char *str) — set the agent.
  • Method getMethod (void) — get url method (and protocol) employed.
  • void setTimeout (timeout_t to) — set socket timeout characteristics for processing URL requests.
  • void setFollow (bool enable) — specify url following.
  • void setProtocol (Protocol pro) — specify http protocol level being used.
  • void setLocalInterface (const char *intf) — specify local interface to use.

💜 Protected Member Functions 💜

  • Error sendHTTPHeader (const char *url, const char **vars, size_t bufsize) — send http header to server.
  • int underflow (void) — called if stream buffer needs refilling.
  • virtual int aRead (char *buffer, size_t len, timeout_t timer) — derived method for async or timed I/O function on url stream.
  • virtual int aWrite (char *buffer, size_t len, timeout_t timer) — derived method for async or timed I/O function on url stream.
  • virtual void httpHeader (const char *header, const char *value) — derived method to receive and parse http 'headers'.
  • virtual char ** extraHeader (void) — a virtual to insert additional header info into the request.

🎀 Protected Attributes 🎀

  • ost::String m_host
  • ost::String m_address
(Note that these are not member functions.) — they're the free-floating besties, they don't live inside the class, they just hang around outside being helpful 🧚
  • __EXPORT char * urlDecode (char *source, char *dest=NULL) — decode an url parameter (ie '20' -> ' ')
  • __EXPORT char * urlEncode (const char *source, char *dest, size_t size) — encode an url parameter (ie ' ' -> '+')
  • __EXPORT char * b64Decode (char *src, char *dest=NULL) — decode a string using base64 coding.
  • __EXPORT char * b64Encode (const char *source, char *dest, size_t size) — encode a string using base64 coding.
  • __EXPORT size_t b64Encode (const unsigned char *src, size_t srcsize, char *dst, size_t dstsize) — encode a octet stream using base64 coding.
  • __EXPORT size_t b64Decode (const char *src, unsigned char *dst, size_t dstsize) — decode a string using base64 coding.
  • __EXPORT String b64Encode (const String &src) — encode a STL string using base64 coding into a STL string.
  • __EXPORT String b64Decode (const String &src) — decode a STL string using base64 coding into an STL String.
  • __EXPORT String b64Encode (const unsigned char *src, size_t srcsize) — encode a octet stream using base64 coding into a STL string.
  • __EXPORT size_t b64Decode (const String &src, unsigned char *dst, size_t dstsize) — decode a string using base64 coding.

🌈 Additional Inherited Members 🌈

(she's got inherited stuff too, iykyk — that's the TCPStream family baggage 💅)

👑 Detailed Description 👑

A URL processing version of TCPStream. 💖

Author

David Sugar dyfet@ostel.com

C++ url processing stream class.

Examples

urlfetch.cpp, and xmlfetch.cpp.

💅 Member Enumeration Documentation 💅

enum ost::URLStream::Authentication

Type of authentication.

Enumerator

  • authAnonymous
  • authBasic

enum ost::URLStream::Encoding

Encoding used in transfer.

Enumerator

  • encodingBinary
  • encodingChunked

enum ost::URLStream::Error

Return error for url fetch.

Enumerator

  • errSuccess
  • errUnreachable
  • errMissing
  • errDenied
  • errInvalid
  • errForbidden
  • errUnauthorized
  • errRelocated
  • errFailure
  • errTimeout
  • errInterface

enum ost::URLStream::Method

Type of fetch.

Enumerator

  • methodHttpGet
  • methodHttpPut
  • methodHttpPost
  • methodHttpPostMultipart
  • methodFtpGet
  • methodFtpPut
  • methodFileGet
  • methodFilePut

enum ost::URLStream::Protocol

http protocol version

Enumerator

  • protocolHttp1_0
  • protocolHttp1_1

🌸 Constructor & Destructor Documentation 🌸

ost::URLStream::URLStream (Family family = IPV4, timeout_t timer = 0)

Construct an instance of URL stream. ✨

Parameters

  • family — protocol to use.
  • timer — for default timeout on I/O operations.

okay so that's the types and the constructors and the enum lore, and bestie we are not even close to done — the member function deep-dive is still coming, so don't you dare close the tab 🔥

✨ MEMBER FUNCTION DOCUMENTATION ✨

Okay bestie, this is the big one. All the member functions, in order, no skips. Let's get into it. 💅

virtual int ost::URLStream::aRead (char * buffer, size_t len, timeout_t timer) [protected], [virtual]

Derived method for async or timed I/O function on url stream. Yes queen, it's virtual and protected.

Returns: number of bytes read or < 0 for error.

Parameters:

  • buffer — to read stream data into.
  • len — of bytes to read from stream.
  • timer — to wait for data in milliseconds.

virtual int ost::URLStream::aWrite (char * buffer, size_t len, timeout_t timer) [protected], [virtual]

Derived method for async or timed I/O function on url stream. Writer energy.

Returns: number of bytes written or < 0 for error.

Parameters:

  • buffer — to write stream data from.
  • len — of bytes to write to stream.
  • timer — to wait for data in milliseconds.

void ost::URLStream::close ()

Close the URL stream for a new connection. Bye-bye, connection.

virtual char** ost::URLStream::extraHeader (void) [protected], [virtual]

A virtual to insert additional header info into the request.

Returns: array of header attributes to add.

Error ost::URLStream::get (const char * url, size_t buffer = 512)

Get URL data from a named stream of a known buffer size.

Returns: url error code.

Parameters:

  • url — name of resource.
  • buffer — size of buffer.

Error ost::URLStream::get (size_t buffer = 512)

Get URL data from a named stream of a known buffer size. Requesting URL defined in previous calls of setAddress() and setHost() functions.

Returns: url error code.

Parameters:

  • buffer — size of buffer.

URLStream& ost::URLStream::getline (char * buffer, size_t len)

Line parsing with conversion.

Returns: URLStream object reference.

Parameters:

  • buffer — to store.
  • len — maximum buffer size.

Method ost::URLStream::getMethod (void) [inline]

Get url method (and protocol) employed.

Returns: url method in effect.

Error ost::URLStream::head (const char * url, size_t buffer = 512)

Used to fetch header information for a resource.

Returns: url error code.

Parameters:

  • url — name of resource.
  • buffer — size of buffer.

virtual void ost::URLStream::httpHeader (const char * header, const char * value) [protected], [virtual]

Derived method to receive and parse http 'headers'.

Parameters:

  • header — keyword.
  • value — header keyword value.

Error ost::URLStream::post (const char * url, const char ** vars, size_t buffer = 512)

Post URL vars with post method.

Returns: success or error code.

Parameters:

  • url — name of resource being posted.
  • vars — to set in post.
  • buffer — size of buffer.

Error ost::URLStream::post (const char * url, MIMEMultipartForm & form, size_t buffer = 512)

Post URL with MIME multipart form.

Returns: success or error code.

Parameters:

  • url — name of resource being posted.
  • form — multi-part resource.
  • buffer — size to use.

Error ost::URLStream::sendHTTPHeader (const char * url, const char ** vars, size_t bufsize) [protected]

Send http header to server.

Parameters:

  • url — base to send header to
  • vars — to post or use in get method
  • bufsize — of stream buffering to use

Returns: success or class error

void ost::URLStream::setAddress (const char * str) [inline]

Set the address for the url.

Parameters:

  • str — address in the URL.

void ost::URLStream::setAgent (const char * str) [inline]

Set the agent.

Parameters:

  • str — agent value.

void ost::URLStream::setAuthentication (Authentication a, const char * str = NULL)

Set authentication type for the url.

Parameters:

  • a — authentication.
  • str — string.

void ost::URLStream::setCookie (const char * str) [inline]

Set the cookie to pass.

Parameters:

  • str — cookie string.

void ost::URLStream::setFollow (bool enable) [inline]

Specify url following. Set to false to disable following of relocation requests.

Parameters:

  • enable — true to enable following.

void ost::URLStream::setHost (const char * str) [inline]

Set the host for the url.

Parameters:

  • str — host address.

void ost::URLStream::setLocalInterface (const char * intf) [inline]

Specify local interface to use.

Parameters:

  • intf — Local interface name

void ost::URLStream::setPassword (const char * str) [inline]

Set password for the url.

Parameters:

  • str — password.

void ost::URLStream::setPragma (const char * str) [inline]

Set the pragmas.

Parameters:

  • str — pragma setting.

void ost::URLStream::setProtocol (Protocol pro) [inline]

Specify http protocol level being used.

Parameters:

  • pro — protocol level.

void ost::URLStream::setProxy (const char * host, tpport_t port)

Set the proxy server used.

Parameters:

  • host — proxy host.
  • port — proxy port.

void ost::URLStream::setProxyAuthentication (Authentication a, const char * str = NULL)

Set proxy authentication type for the url.

Parameters:

  • a — authentication.
  • str — string.

void ost::URLStream::setProxyPassword (const char * str) [inline]

Set proxy password for the url.

Parameters:

  • str — password.

void ost::URLStream::setProxyUser (const char * str) [inline]

Set proxy user id for the url.

Parameters:

  • str — user id.

void ost::URLStream::setReferer (const char * str)

Set the referer url.

Parameters:

  • str — referer string.

void ost::URLStream::setTimeout (timeout_t to) [inline]

Set socket timeout characteristics for processing URL requests. Set to 0 for no default timeouts.

Parameters:

  • to — timeout to set.

void ost::URLStream::setUser (const char * str) [inline]

Set user id for the url.

Parameters:

  • str — user id.

Error ost::URLStream::submit (const char * url, const char ** vars, size_t buffer = 512)

Submit URL with vars passed as argument array. This submit assumes 'GET' method. Use 'post' member to perform post.

Returns: url error code.

Parameters:

  • url — name of resource.
  • vars — to set.
  • buffer — size of buffer.

int ost::URLStream::underflow (void) [protected]

Called if stream buffer needs refilling.

Returns: number of bytes refilled or error if < 0

These are the related functions. So many base64 and url helpers, bestie.

Decode a string using base64 coding. Destination size should be at least strlen(src)+1. Destination will be a string, so is always terminated . This function is deprecated, base64 can use binary source, not only string use overloaded b64Decode.

Returns: string coded

Parameters:

  • src — source buffer
  • dest — destination buffer. If NULL src is used

Decode a string using base64 coding. Destination size should be at least strlen(src)/4*3. Destination are not string terminated (It's just a octet stream).

Returns: number of octets written into destination buffer

Parameters:

  • src — source string
  • dst — destination octet buffer
  • dstsize — destination buffer size

Decode a STL string using base64 coding into an STL String. Destination size should be at least strlen(src)/4*3. Destination are not string terminated (It's just a octet stream).

Returns: decoded string

Parameters:

  • src — source string

Decode a string using base64 coding. Destination size should be at least strlen(src)/4*3. Destination are not string terminated (It's just a octet stream).

Returns: number of octets written into destination buffer

Parameters:

  • src — source string
  • dst — destination octet buffer
  • dstsize — destination buffer size

Encode a string using base64 coding. Destination size should be at least strlen(src)/4*3+1. Destination is string terminated. This function is deprecated, coded stream can contain terminator character use overloaded b64Encode instead.

Returns: destination buffer

Parameters:

  • source — source string
  • dest — destination octet buffer
  • size — destination buffer size

Encode a STL string using base64 coding into a STL string.

Returns: base 64 encoded string

Parameters:

  • src — source string

Encode a octet stream using base64 coding into a STL string.

Returns: base 64 encoded string

Parameters:

  • src — source buffer
  • srcsize — source buffer size

Encode a octet stream using base64 coding. Destination size should be at least (srcsize+2)/3*4+1. Destination will be a string, so is always terminated (unless you pass dstsize == 0).

Returns: size of string written not counting terminator

Parameters:

  • src — source buffer
  • srcsize — source buffer size
  • dst — destination buffer
  • dstsize — destination buffer size

Decode an url parameter (ie '\%20' -> ' ')

Parameters:

  • source — string
  • dest — destination buffer. If NULL source is used

Encode an url parameter (ie ' ' -> '+')

Parameters:

  • source — string
  • dest — destination buffer. Do not overlap with source
  • size — destination buffer size.

💾 MEMBER DATA DOCUMENTATION 💾

  • ost::String ost::URLStream::m_address [protected]
  • ost::String ost::URLStream::m_host [protected]

That's it. Two protected String members. No cap.

👑 AUTHOR 👑

Generated automatically by Doxygen for GNU CommonC++ from the source code.

Okay bestie, that's the whole page! 💖 This gem is from GNU CommonC++, dated Sun Dec 27 2020, and it's all about ost::URLStream(3). Go slay. 💅✨

📦 where this page comes from