---
name: "ost_URLStream"
section: "3"
platform: "linux"
package: "libcommoncpp2-doc"
version: "1.8.1-10"
release: "Debian 11 (Bullseye)"
platforms: ["linux"]
url: "https://new.carta.tech/ost_URLStream"
---

# ost\_URLStream(3)

A URL processing version of TCPStream.

## NAME

ost::URLStream - A URL processing version of **TCPStream**.

## SYNOPSIS

`#include <url.h>`

Inherits **ost::TCPStream**.

### Public Types

enum **Error** { **errSuccess** = 0, **errUnreachable**, **errMissing**, **errDenied**, **errInvalid**, **errForbidden**, **errUnauthorized**, **errRelocated**, **errFailure**, **errTimeout**, **errInterface** }\
 Return error for url fetch.  enum **Authentication** { **authAnonymous** = 0, **authBasic** }\
 Type of authentication.  enum **Encoding** { **encodingBinary** = 0, **encodingChunked** }\
 Encoding used in transfer.  enum **Method** { **methodHttpGet**, **methodHttpPut**, **methodHttpPost**, **methodHttpPostMultipart**, **methodFtpGet**, **methodFtpPut**, **methodFileGet**, **methodFilePut** }\
 Type of fetch.  enum **Protocol** { **protocolHttp1\_0**, **protocolHttp1\_1** }\
 http protocol version

### 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**\

### Related Functions

(Note that these are not member functions.)  **\_\_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

## 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.*

## Member Function Documentation

### 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.*

**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.*

**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.*

### 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*

## Friends And Related Function Documentation

### \_\_EXPORT char \* b64Decode (char \* src, char \* dest = `NULL`)` [related]`

*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*

### \_\_EXPORT size\_t b64Decode (const char \* src, unsigned char \* dst, size\_t dstsize)` [related]`

*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*

### \_\_EXPORT String b64Decode (const String & src)` [related]`

*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*

### \_\_EXPORT size\_t b64Decode (const String & src, unsigned char \* dst, size\_t dstsize)` [related]`

*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*

### \_\_EXPORT char \* b64Encode (const char \* source, char \* dest, size\_t size)` [related]`

*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*

### \_\_EXPORT String b64Encode (const String & src)` [related]`

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

**Returns**

*base 64 encoded string*

**Parameters**

*src source string*

### \_\_EXPORT String b64Encode (const unsigned char \* src, size\_t srcsize)` [related]`

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

**Returns**

*base 64 encoded string*

**Parameters**

*src source buffer* \
 *srcsize source buffer size*

### \_\_EXPORT size\_t b64Encode (const unsigned char \* src, size\_t srcsize, char \* dst, size\_t dstsize)` [related]`

*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*

### \_\_EXPORT char \* urlDecode (char \* source, char \* dest = `NULL`)` [related]`

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

**Parameters**

*source string* \
 *dest destination buffer. If NULL source is used*

### \_\_EXPORT char \* urlEncode (const char \* source, char \* dest, size\_t size)` [related]`

*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]`

## Author

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