net/base/url_util.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef NET_BASE_URL_UTIL_H_
   6 #define NET_BASE_URL_UTIL_H_
   7
   8 #include <string>
   9
  10 #include "base/compiler_specific.h"
  11 #include "net/base/net_export.h"
  12 #include "url/url_parse.h"
  13
  14 class GURL;
  15
  16 namespace net {
  17
  18 // Returns a new GURL by appending the given query parameter name and the
  19 // value. Unsafe characters in the name and the value are escaped like
  20 // %XX%XX. The original query component is preserved if it's present.
  21 //
  22 // Examples:
  23 //
  24 // AppendQueryParameter(GURL("http://example.com"), "name", "value").spec()
  25 // => "http://example.com?name=value"
  26 // AppendQueryParameter(GURL("http://example.com?x=y"), "name", "value").spec()
  27 // => "http://example.com?x=y&name=value"
  28 NET_EXPORT GURL AppendQueryParameter(const GURL& url,
  29                                      const std::string& name,
  30                                      const std::string& value);
  31
  32 // Returns a new GURL by appending or replacing the given query parameter name
  33 // and the value. If |name| appears more than once, only the first name-value
  34 // pair is replaced. Unsafe characters in the name and the value are escaped
  35 // like %XX%XX. The original query component is preserved if it's present.
  36 //
  37 // Examples:
  38 //
  39 // AppendOrReplaceQueryParameter(
  40 //     GURL("http://example.com"), "name", "new").spec()
  41 // => "http://example.com?name=value"
  42 // AppendOrReplaceQueryParameter(
  43 //     GURL("http://example.com?x=y&name=old"), "name", "new").spec()
  44 // => "http://example.com?x=y&name=new"
  45 NET_EXPORT GURL AppendOrReplaceQueryParameter(const GURL& url,
  46                                               const std::string& name,
  47                                               const std::string& value);
  48
  49 // Iterates over the key-value pairs in the query portion of |url|.
  50 class NET_EXPORT QueryIterator {
  51  public:
  52   explicit QueryIterator(const GURL& url);
  53   ~QueryIterator();
  54
  55   std::string GetKey() const;
  56   std::string GetValue() const;
  57   const std::string& GetUnescapedValue();
  58
  59   bool IsAtEnd() const;
  60   void Advance();
  61
  62  private:
  63   const GURL& url_;
  64   url::Component query_;
  65   bool at_end_;
  66   url::Component key_;
  67   url::Component value_;
  68   std::string unescaped_value_;
  69
  70   DISALLOW_COPY_AND_ASSIGN(QueryIterator);
  71 };
  72
  73 // Looks for |search_key| in the query portion of |url|. Returns true if the
  74 // key is found and sets |out_value| to the unescaped value for the key.
  75 // Returns false if the key is not found.
  76 NET_EXPORT bool GetValueForKeyInQuery(const GURL& url,
  77                                       const std::string& search_key,
  78                                       std::string* out_value);
  79
  80 }  // namespace net
  81
  82 #endif  // NET_BASE_URL_UTIL_H_