libzypp: zypp::url Namespace Reference

libzypp 17.38.6

zypp::url Namespace Reference

Url details namespace. More...

## Classes
class | SafeQuerystr
| Hide passwords embedded in a querystr,. More...
class | UrlBaseData
| Internal data used by UrlBase. More...
struct | ViewOption
| Url::asString() view options. More...
class | UrlBase
| Generic Url base class. More...
class | UrlException
| Base class for all URL exceptions. More...
class | UrlDecodingException
| Thrown if the encoded string contains a NUL byte (%00). More...
class | UrlParsingException
| Thrown if the url or a component can't be parsed at all. More...
class | UrlBadComponentException
| Thrown if a url component is invalid. More...
class | UrlNotAllowedException
| Thrown if scheme does not allow a component. More...
class | UrlNotSupportedException
| Thrown if a feature e.g. More...

## Typedefs
using | UrlConfig = std::map<std::string, std::string>
using | ViewOptions = ViewOption
| ViewOptions is just an alias for ViewOption.
using | UrlSchemes = std::vector<std::string>
| Vector of URL scheme names.
using | UrlRef = RWCOW_pointer<UrlBase>
| Copy-On-Write Url reference.
using | ParamVec = std::vector<std::string>
| A parameter vector container.
using | ParamMap = std::map<std::string, std::string>
| A parameter map container.

## Enumerations
enum | EEncoding { E_ENCODED , E_DECODED }
| Encoding flags. More...

## Functions
std::string | encode (const std::string &str, const std::string &safe="", EEncoding eflag=E_DECODED) ZYPP_API
| Encodes a string using URL percent encoding.
std::string | decode (const std::string &str, bool allowNUL=false) ZYPP_API
| Decodes a URL percent encoded string.
std::string | encode_octet (const unsigned char c) ZYPP_API
| Encode one character.
int | decode_octet (const char *hex) ZYPP_API
| Decode one character.
void | split (ParamVec &pvec, const std::string &pstr, const std::string &psep)
| Split into a parameter vector.
void | split (ParamMap &pmap, const std::string &pstr, const std::string &psep, const std::string &vsep, EEncoding eflag=E_ENCODED)
| Split into a parameter map.
std::string | join (const ParamVec &pvec, const std::string &psep)
| Join parameter vector to a string.
std::string | join (const ParamMap &pmap, const std::string &psep, const std::string &vsep, const std::string &safe, EEncoding eflag)
| Join parameter map to a string.

## Detailed Description

Url details namespace.

## Typedef Documentation

## ◆ UrlConfig

using zypp::url::UrlConfig = std::map<std::string, std::string>

Definition at line 110 of file UrlBase.cc.

## ◆ ViewOptions

using zypp::url::ViewOptions = ViewOption

ViewOptions is just an alias for ViewOption.

Definition at line 245 of file UrlBase.h.

## ◆ UrlSchemes

using zypp::url::UrlSchemes = std::vector<std::string>

Vector of URL scheme names.

Definition at line 252 of file UrlBase.h.

## ◆ UrlRef

using zypp::url::UrlRef = RWCOW_pointer<UrlBase>

Copy-On-Write Url reference.

Definition at line 1093 of file UrlBase.h.

## ◆ ParamVec

using zypp::url::ParamVec = std::vector<std::string>

A parameter vector container.

A string vector containing splited PathParam- or Query-String. Each string in the vector is allways URL percent encoded and usually contains a "key=value" pair.

Definition at line 40 of file UrlUtils.h.

## ◆ ParamMap

using zypp::url::ParamMap = std::map<std::string, std::string>

A parameter map container.

A map containing key and value pairs parsed from a PathParam- or Query-String.

Definition at line 47 of file UrlUtils.h.

## Enumeration Type Documentation

## ◆ EEncoding

enum zypp::url::EEncoding

Encoding flags.

Enumerator
E_ENCODED | Flag to request encoded string(s).
E_DECODED | Flag to request decoded string(s).

Definition at line 52 of file UrlUtils.h.

## Function Documentation

## ◆ encode()

std::string zypp::url::encode | ( | const std::string & | str,
|  | const std::string & | safe = "",
|  | EEncoding | eflag = E_DECODED )

Encodes a string using URL percent encoding.

By default, all characters except of "a-zA-Z0-9_.-" will be encoded. Additional characters from the set ":/?#[]@!$&'()*+,;=", that are safe for a URL compoent without encoding, can be specified in the `safe` argument.

If the `eflag` parameter is set to E_ENCODED, then already encoded substrings will be detected and not encoded a second time.

The following function call will encode the "@" character as "%40", but skip encoding of the "%" character, because the `eflag` is set to E_ENCODED and "%ba" is detected as a valid encoded character.

zypp::url::encode("foo%bar@localhost", "", E_ENCODED);
zypp::url::encode
std::string encode(const std::string &str, const std::string &safe, EEncoding eflag)
Encodes a string using URL percent encoding.
Definition UrlUtils.cc:32
zypp::url::E_ENCODED
@ E_ENCODED
Flag to request encoded string(s).
Definition UrlUtils.h:53

With `eflag` set to E_DECODED, the "%" character would be encoded as well. The complete encoded string would be "foo%25bar%40localhost".

Parameters

  str | A string to encode (binary data).
  safe | Characters safe to skip in encoding, e.g. "/" for path names.
  eflag | If to detect and skip already encoded substrings.

Returns
  A percent encoded string.

Definition at line 32 of file UrlUtils.cc.

## ◆ decode()

std::string zypp::url::decode | ( | const std::string & | str,
|  | bool | allowNUL = false )

Decodes a URL percent encoded string.

Replaces all occurences of `"%<hex><hex>"` in the `str` string with the character encoded using the two hexadecimal digits that follows the "%" character.

For example, the encoded string "%40%3F%3D%26%25" will be decoded to "@?=&%".

Parameters

  str | A string to decode.
  allowNUL | A flag, if `"%00"` (encoded `'\0'`) is allowed or not.

Returns
  A decoded strig (may contain binary data).

Exceptions

  UrlDecodingException | if `allowNUL` is false and a encoded NUL byte (`"%00"`) was found in `str`.

Definition at line 87 of file UrlUtils.cc.

## ◆ encode_octet()

std::string zypp::url::encode_octet | ( | const unsigned char | c | ) |

Encode one character.

Encode the specified character `c` into its `"%<hex><hex>"` representation.

Parameters

  c | A character to encode.

Returns
  A percent encoded representation of the character, e.g. %20 for a ' ' (space).

Definition at line 132 of file UrlUtils.cc.

## ◆ decode_octet()

int zypp::url::decode_octet | ( | const char * | hex | ) |

Decode one character.

Decode the `hex` parameter pointing to (at least) two hexadecimal digits into its character value and return it.

Example:

char *str = "%40";
char *pct = strchr(str, '%');
int chr = pct ? decode_octet(pct+1) : -1;
// chr is set to the '@' ASCII character now.
str
String related utilities and Regular expression matching.
zypp::url::decode_octet
int decode_octet(const char *hex)
Decode one character.
Definition UrlUtils.cc:148

Parameters

  hex | Pointer to two hex characters representing the character value in percent-encoded strings.

Returns
  The value (0-255) encoded in the `hex` characters or -1 if `hex` does not point to two hexadecimal characters.

Definition at line 148 of file UrlUtils.cc.

## ◆ split() [1/2]

void zypp::url::split | ( | ParamVec & | pvec,
|  | const std::string & | pstr,
|  | const std::string & | psep )

Split into a parameter vector.

Splits a parameter string `pstr` into substrings using `psep` as separator and appends the resulting substrings to `pvec`.

Usual parameter separators are `'&'` for Query- and `'`,' for PathParam-Strings.

Parameters

  pvec | Reference to a result parameter vector.
  pstr | Reference to the PathParam- or Query-String to split.
  psep | Parameter separator character to split at.

Exceptions

  UrlNotSupportedException | if `psep` separator is empty.

Definition at line 164 of file UrlUtils.cc.

## ◆ split() [2/2]

void zypp::url::split | ( | ParamMap & | pmap,
|  | const std::string & | pstr,
|  | const std::string & | psep,
|  | const std::string & | vsep,
|  | EEncoding | eflag = E_ENCODED )

Split into a parameter map.

Splits a parameter string `pstr` into substrings using `psep` as separator and then, each substring into key and value pair using `vsep` as separator between parameter key and value and adds them to the parameter map `pmap`.

If a parameter substring doesn't contain any value separator `vsep`, the substring is used as a parameter key and value is set to an empty string.

Usual parameter separators are `'&'` for Query- and `'`,' for PathParam-Strings. A usual parameter-value separator is `'='` for both, Query- and PathParam-Strings.

If the encoding flag `eflag` is set to `E_DECODED`, then the key and values are dedcoded before they are stored in the map.

Parameters

  pmap | Reference to a result parameter map.
  pstr | Reference to the PathParam- or Query-String to split.
  psep | Separator character to split key-value pairs.
  vsep | Separator character to split key and value.
  eflag | Flag if the key and value strings should be URL percent decoded before they're stored in the map.

Exceptions

  UrlNotSupportedException | if `psep` or `vsep` separator is empty.

Definition at line 198 of file UrlUtils.cc.

## ◆ join() [1/2]

std::string zypp::url::join | ( | const ParamVec & | pvec,
|  | const std::string & | psep )

Join parameter vector to a string.

Creates a string containing all substrings from the `pvec` separated by `psep` separator character. The substrings in `pvec` should be already URL percent encoded and should't contain `psep` characters.

Usual parameter separators are `'&'` for Query- and `'`,' for PathParam-Strings.

Parameters

  pvec | Reference to encoded parameter vector.
  psep | Parameter separator character to use.

Returns
  A parameter string.

Definition at line 252 of file UrlUtils.cc.

## ◆ join() [2/2]

std::string zypp::url::join | ( | const ParamMap & | pmap,
|  | const std::string & | psep,
|  | const std::string & | vsep,
|  | const std::string & | safe,
|  | EEncoding | eflag )

Join parameter map to a string.

Creates a string containing all parameter key-value pairs from the parameter map `pmap`, that will be joined using the `psep` character and the parameter key is separated from the parameter value using the `vsep` character. Both, key and value will be automatically encoded.

Usual parameter separators are `'&'` for Query- and `'`,' for PathParam-Strings. A usual parameter-value separator is `'='` for both, Query- and PathParam-Strings.

See encode() function from details about the `safe` characters.

Parameters

  pmap | Reference to a parameter map.
  psep | Separator character to use between key-value pairs.
  vsep | Separator character to use between keys and values.
  safe | List of characters to accept without encoding.
  eflag | Tells whether keys and values in pmap are already encoded or decoded.

Returns
  A URL percent-encoded parameter string.

Exceptions

  UrlNotSupportedException | if `psep` or `vsep` separator is empty.

Definition at line 273 of file UrlUtils.cc.