---
name: "URLStream"
section: "3cc"
platform: "linux"
package: "libcommoncpp2-dev"
version: "1.0.13-5"
release: "Debian 3.1 (Sarge)"
platforms: ["linux"]
url: "https://new.carta.tech/URLStream"
---

# URLStream(3cc)

A URL processing version of TCPStream. C++ url processing stream class.

## NAME

URLStream - A URL processing version of **TCPStream**. C++ url processing stream class.

## SYNOPSIS

`#include <url.h>`

Inherits **TCPStream**.

### Public Types

enum **Error** { **errSuccess** =  0, **errUnreachable**, **errMissing**, **errDenied**, **errInvalid**, **errForbidden**, **errUnauthorized**, **errRelocated**, **errFailure**, **errTimeout** }\
 *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**, **methodFtpGet**, **methodFtpPut**, **methodFileGet**, **methodFilePut** }\
 *Type of fetch.* enum **Protocol** { **protocolHttp1\_0**, **protocolHttp1\_1** }\
 *http protocol version*

### Public Methods

**URLStream** (**timeout\_t** to=0)\
 *Construct an instance of URL stream.* URLStream & **getline** (char \*buffer, size\_t len)\
 *Line parsing with conversion.* **Error** **get** (const char \*url, int buffer=512)\
 *Get URL data from a named stream of a known buffer size.* **Error** **submit** (const char \*url, const char \*\*vars, int buffer=512)\
 *Submit URL with vars passed as argument array.* **Error** **post** (const char \*url, const char \*\*vars, int buffer=512)\
 *Post URL vars with post method.* **Error** **head** (const char \*url, int 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 **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 **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 Methods

**Error** **sendHTTPHeader** (const char \*url, const char \*\*vars, int **bufsize**)\
 int **underflow** (void)\
 virtual int **aRead** (char \*buffer, size\_t len, **timeout\_t** **timeout**)\
 virtual int **aWrite** (char \*buffer, size\_t len, **timeout\_t** **timeout**)\
 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.*

### Related Functions

(Note that these are not member functions.) **CCXX\_EXPORT**(char \*) urlDecode(char \*source\
 *Decode an url parameter (ie '%20' -\> ' ').* **CCXX\_EXPORT**(char \*) urlEncode(const char \*source\
 *Encode an url parameter (ie ' ' -\> '+').* **CCXX\_EXPORT**(size\_t) b64Encode(const unsigned char \*src\
 *Encode a octet stream using base64 coding.*

## DETAILED DESCRIPTION

A URL processing version of **TCPStream**. C++ url processing stream class.

**Author:**  David Sugar \<dyfet@ostel.com\>

## MEMBER ENUMERATION DOCUMENTATION

### enum URLStream::Authentication

Type of authentication.

**Enumeration values:**

- *authAnonymous*

  - *authBasic*

  ### enum URLStream::Encoding

*Encoding used in transfer.*

**Enumeration values:**

- *encodingBinary*

  - *encodingChunked*

  ### enum URLStream::Error

*Return error for url fetch.*

**Enumeration values:**

- *errSuccess*

  - *errUnreachable*

  - *errMissing*

  - *errDenied*

  - *errInvalid*

  - *errForbidden*

  - *errUnauthorized*

  - *errRelocated*

  - *errFailure*

  - *errTimeout*

  *Reimplemented from* **Socket***.*

### enum URLStream::Method

*Type of fetch.*

**Enumeration values:**

- *methodHttpGet*

  - *methodHttpPut*

  - *methodHttpPost*

  - *methodFtpGet*

  - *methodFtpPut*

  - *methodFileGet*

  - *methodFilePut*

  ### enum URLStream::Protocol

*http protocol version*

**Enumeration values:**

- *protocolHttp1\_0*

  - *protocolHttp1\_1*

  ## CONSTRUCTOR & DESTRUCTOR DOCUMENTATION

### URLStream::URLStream (timeout\_t to = 0)

*Construct an instance of URL stream.*

**Parameters:**

- *to*

  *default timeout.*

## MEMBER FUNCTION DOCUMENTATION

### virtual int URLStream::aRead (char \* buffer, size\_t len, timeout\_t timeout)` [inline, protected, virtual]`

### virtual int URLStream::aWrite (char \* buffer, size\_t len, timeout\_t timeout)` [inline, protected, virtual]`

### void URLStream::close ()

*Close the URL stream for a new connection.*

### virtual char\*\* URLStream::extraHeader (void)` [inline, protected, virtual]`

*A virtual to insert additional header info into the request.*

**Returns:**  *array of header attributes to add.*

### Error URLStream::get (const char \* url, int 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.*

### URLStream& URLStream::getline (char \* buffer, size\_t len)

*Line parsing with conversion.*

**Returns:**  *URLStream object.*

**Parameters:**

- *buffer*

  *to store.*

- *len*

  *maximum buffer size.*

### Method URLStream::getMethod (void)` [inline]`

*Get url method (and protocol) employed.*

**Returns:**  *url method in effect.*

### Error URLStream::head (const char \* url, int 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 URLStream::httpHeader (const char \* header, const char \* value)` [inline, protected, virtual]`

*Derived method to receive and parse http 'headers'.*

**Parameters:**

- *header*

  *keyword.*

- *value*

  *header keyword value.*

### Error URLStream::post (const char \* url, const char \*\* vars, int buffer = 512)

*Post URL vars with post method.*

**Returns:**  *url error code.*

**Parameters:**

- *url*

  *name of resource.*

- *vars*

  *to set.*

- *buffer*

  *size of buffer.*

### Error URLStream::sendHTTPHeader (const char \* url, const char \*\* vars, int bufsize)` [protected]`

### void URLStream::setAgent (const char \* str)` [inline]`

*Set the agent.*

**Parameters:**

- *str*

  *agent value.*

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

*Set authentication type for the url.*

**Parameters:**

- *a*

  *authentication.*

- *str*

  *string.*

### void URLStream::setCookie (const char \* str)` [inline]`

*Set the cookie to pass.*

**Parameters:**

- *str*

  *cookie string.*

### void URLStream::setFollow (bool enable)` [inline]`

*Specify url following.*

*Set to false to disable following of relocation requests.*

**Parameters:**

- *enable*

  *true to enable following.*

### void URLStream::setLocalInterface (const char \* intf)` [inline]`

*Specify local interface to use.*

**Parameters:**

- *intf*

  *Local interface name*

### void URLStream::setPassword (const char \* str)` [inline]`

*Set password for the url.*

**Parameters:**

- *str*

  *password.*

### void URLStream::setPragma (const char \* str)` [inline]`

*Set the pragmas.*

**Parameters:**

- *str*

  *pragma setting.*

### void URLStream::setProtocol (Protocol pro)` [inline]`

*Specify http protocol level being used.*

**Parameters:**

- *pro*

  *protocol level.*

### void URLStream::setProxy (const char \* host, tpport\_t port)

*Set the proxy server used.*

**Parameters:**

- *host*

  *proxy host.*

- *port*

  *proxy port.*

### void URLStream::setReferer (const char \* str)

*Set the referer url.*

**Parameters:**

- *str*

  *referer string.*

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

*Reimplemented from* **TCPStream***.*

### void URLStream::setUser (const char \* str)` [inline]`

*Set user id for the url.*

**Parameters:**

- *str*

  *user id.*

### Error URLStream::submit (const char \* url, const char \*\* vars, int 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 URLStream::underflow (void)` [protected]`

*Reimplemented from* **TCPStream***.*

## FRIENDS AND RELATED FUNCTION DOCUMENTATION

### CCXX\_EXPORT(size\_t) const` [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*

### CCXX\_EXPORT(char \*) const` [related]`

*Encode an url parameter (ie ' ' -\> '+').*

**Parameters:**

- *source*

  *string*

- *dest*

  *destination buffer. Do not overlap with source*

- *size*

  *destination buffer size.*

### CCXX\_EXPORT(char \*)` [related]`

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

**Parameters:**

- *source*

  *string*

- *dest*

  *destination buffer. If NULL source is used*

## AUTHOR

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