zypp/url/UrlUtils.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /**
  10  * \file zypp/url/UrlUtils.h
  11  */
  12 #ifndef   ZYPP_URL_URLUTILS_H
  13 #define   ZYPP_URL_URLUTILS_H
  14
  15 #include "zypp/url/UrlException.h"
  16
  17 #include <string>
  18 #include <vector>
  19 #include <map>
  20
  21 /** Characters that are safe for URL without percent-encoding. */
  22 #define URL_SAFE_CHARS ":/?#[]@!$&'()*+,;="
  23
  24 //////////////////////////////////////////////////////////////////////
  25 namespace zypp
  26 { ////////////////////////////////////////////////////////////////////
  27
  28   ////////////////////////////////////////////////////////////////////
  29   /** Url details namespace. */
  30   namespace url
  31   { //////////////////////////////////////////////////////////////////
  32
  33
  34     // ---------------------------------------------------------------
  35     /** A parameter vector container.
  36      * A string vector containing splited PathParam- or Query-String.
  37      * Each string in the vector is allways URL percent encoded and
  38      * usually contains a "key=value" pair.
  39      */
  40     typedef std::vector < std::string >             ParamVec;
  41
  42
  43     /** A parameter map container.
  44      * A map containing key and value pairs parsed from a PathParam-
  45      * or Query-String.
  46      */
  47     typedef std::map < std::string, std::string >   ParamMap;
  48
  49
  50     /** Encoding flags.
  51      */
  52     typedef enum {
  53         E_ENCODED, //!< Flag to request encoded string(s).
  54         E_DECODED  //!< Flag to request decoded string(s).
  55     } EEncoding;
  56
  57
  58     // ---------------------------------------------------------------
  59     /** Encodes a string using URL percent encoding.
  60      *
  61      * By default, all characters except of "a-zA-Z0-9_.-" will be encoded.
  62      * Additional characters from the set ":/?#[]@!$&'()*+,;=", that are
  63      * safe for a URL compoent without encoding, can be specified in the
  64      * \p safe argument.
  65      *
  66      * If the \p eflag parameter is set to E_ENCODED, then already encoded
  67      * substrings will be detected and not encoded a second time.
  68      *
  69      * The following function call will encode the "@" character as "%40",
  70      * but skip encoding of the "%" character, because the \p eflag is set
  71      * to E_ENCODED and "%ba" is detected as a valid encoded character.
  72      * \code
  73      *   zypp::url::encode("foo%bar@localhost", "", E_ENCODED);
  74      * \endcode
  75      * With \p eflag set to E_DECODED, the "%" character would be encoded
  76      * as well. The complete encoded string would be "foo%25bar%40localhost".
  77      *
  78      * \param str      A string to encode (binary data).
  79      * \param safe     Characters safe to skip in encoding,
  80      *                 e.g. "/" for path names.
  81      * \param eflag    If to detect and skip already encoded substrings.
  82      * \return A percent encoded string.
  83      */
  84     std::string
  85     encode(const std::string &str, const std::string &safe = "",
  86                                    EEncoding         eflag = E_DECODED);
  87
  88
  89     // ---------------------------------------------------------------
  90     /** Decodes a URL percent encoded string.
  91      * Replaces all occurences of \c "%<hex><hex>" in the \p str string
  92      * with the character encoded using the two hexadecimal digits that
  93      * follows the "%" character.
  94      *
  95      * For example, the encoded string "%40%3F%3D%26%25" will be decoded
  96      * to "@?=&%".
  97      *
  98      * \param str      A string to decode.
  99      * \param allowNUL A flag, if \c "%00" (encoded \c '\\0')
 100      *                 is allowed or not.
 101      * \return A decoded strig (may contain binary data).
 102      * \throws UrlDecodingException if \p allowNUL is false and
 103      *         a encoded NUL byte (\c "%00") was found in \p str.
 104      */
 105     std::string
 106     decode(const std::string &str, bool allowNUL = false);
 107
 108
 109     // ---------------------------------------------------------------
 110     /** Encode one character.
 111      *
 112      * Encode the specified character \p c into its \c "%<hex><hex>"
 113      * representation.
 114      *
 115      * \param c        A character to encode.
 116      * \return A percent encoded representation of the character,
 117      *         e.g. %20 for a ' ' (space).
 118      */
 119     std::string
 120     encode_octet(const unsigned char c);
 121
 122
 123     // ---------------------------------------------------------------
 124     /** Decode one character.
 125      *
 126      * Decode the \p hex parameter pointing to (at least) two hexadecimal
 127      * digits into its character value and return it.
 128      *
 129      * Example:
 130      * \code
 131      *   char *str = "%40";
 132      *   char *pct = strchr(str, '%');
 133      *   int   chr = pct ? decode_octet(pct+1) : -1;
 134      *      // chr is set to the '@' ASCII character now.
 135      * \endcode
 136      *
 137      * \param hex     Pointer to two hex characters representing
 138      *                the character value in percent-encoded strings.
 139      * \return The value (0-255) encoded in the \p hex characters or -1
 140      *         if \p hex does not point to two hexadecimal characters.
 141      */
 142     int
 143     decode_octet(const char *hex);
 144
 145
 146     // ---------------------------------------------------------------
 147     /** Split into a parameter vector.
 148      *
 149      * Splits a parameter string \p pstr into substrings using \p psep
 150      * as separator and appends the resulting substrings to \p pvec.
 151      *
 152      * Usual parameter separators are \c '&' for Query- and \c ',' for
 153      * PathParam-Strings.
 154      *
 155      * \param pvec    Reference to a result parameter vector.
 156      * \param pstr    Reference to the PathParam- or Query-String to split.
 157      * \param psep    Parameter separator character to split at.
 158      * \throws UrlNotSupportedException if \p psep separator is empty.
 159      */
 160     void
 161     split(ParamVec          &pvec,
 162           const std::string &pstr,
 163           const std::string &psep);
 164
 165
 166     // ---------------------------------------------------------------
 167     /** Split into a parameter map.
 168      *
 169      * Splits a parameter string \p pstr into substrings using \p psep as
 170      * separator and then, each substring into key and value pair using
 171      * \p vsep as separator between parameter key and value and adds them
 172      * to the parameter map \p pmap.
 173      *
 174      * If a parameter substring doesn't contain any value separator \p vsep,
 175      * the substring is used as a parameter key and value is set to an empty
 176      * string.
 177      *
 178      * Usual parameter separators are \c '&' for Query- and \c ',' for
 179      * PathParam-Strings. A usual parameter-value separator is \c '=' for
 180      * both, Query- and PathParam-Strings.
 181      *
 182      * If the encoding flag \p eflag is set to \p E_DECODED, then the key
 183      * and values are dedcoded before they are stored in the map.
 184      *
 185      * \param pmap    Reference to a result parameter map.
 186      * \param pstr    Reference to the PathParam- or Query-String to split.
 187      * \param psep    Separator character to split key-value pairs.
 188      * \param vsep    Separator character to split key and value.
 189      * \param eflag   Flag if the key and value strings should be URL percent
 190      *                decoded before they're stored in the map.
 191      * \throws UrlNotSupportedException if \p psep or \p vsep separator
 192      *         is empty.
 193      */
 194     void
 195     split(ParamMap          &pmap,
 196           const std::string &pstr,
 197           const std::string &psep,
 198           const std::string &vsep,
 199           EEncoding         eflag = E_ENCODED);
 200
 201
 202     // ---------------------------------------------------------------
 203     /** Join parameter vector to a string.
 204      *
 205      * Creates a string containing all substrings from the \p pvec separated
 206      * by \p psep separator character. The substrings in \p pvec should be
 207      * already URL percent encoded and should't contain \p psep characters.
 208      *
 209      * Usual parameter separators are \c '&' for Query- and \c ',' for
 210      * PathParam-Strings.
 211      *
 212      * \param pvec    Reference to encoded parameter vector.
 213      * \param psep    Parameter separator character to use.
 214      * \return A parameter string.
 215      */
 216     std::string
 217     join(const ParamVec     &pvec,
 218          const std::string  &psep);
 219
 220
 221     // ---------------------------------------------------------------
 222     /** Join parameter map to a string.
 223      *
 224      * Creates a string containing all parameter key-value pairs from the
 225      * parameter map \p pmap, that will be joined using the \p psep character
 226      * and the parameter key is separated from the parameter value using the
 227      * \p vsep character. Both, key and value will be automatically encoded.
 228      *
 229      * Usual parameter separators are \c '&' for Query- and \c ',' for
 230      * PathParam-Strings. A usual parameter-value separator is \c '=' for
 231      * both, Query- and PathParam-Strings.
 232      *
 233      * See encode() function from details about the \p safe characters.
 234      *
 235      * \param pmap    Reference to a parameter map.
 236      * \param psep    Separator character to use between key-value pairs.
 237      * \param vsep    Separator character to use between keys and values.
 238      * \param safe    List of characters to accept without encoding.
 239      * \return A URL percent-encoded parameter string.
 240      * \throws UrlNotSupportedException if \p psep or \p vsep separator
 241      *         is empty.
 242      */
 243     std::string
 244     join(const ParamMap     &pmap,
 245          const std::string  &psep,
 246          const std::string  &vsep,
 247          const std::string  &safe);
 248
 249
 250     //////////////////////////////////////////////////////////////////
 251   } // namespace url
 252   ////////////////////////////////////////////////////////////////////
 253
 254   ////////////////////////////////////////////////////////////////////
 255 } // namespace zypp
 256 //////////////////////////////////////////////////////////////////////
 257
 258 #endif /* ZYPP_URL_URLUTILS_H */
 259 /*
 260 ** vim: set ts=2 sts=2 sw=2 ai et:
 261 */