folly/Uri.h

   1 /*
   2  * Copyright 2014 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef FOLLY_URI_H_
  18 #define FOLLY_URI_H_
  19
  20 #include "folly/String.h"
  21
  22 namespace folly {
  23
  24 /**
  25  * Class representing a URI.
  26  *
  27  * Consider http://www.facebook.com/foo/bar?key=foo#anchor
  28  *
  29  * The URI is broken down into its parts: scheme ("http"), authority
  30  * (ie. host and port, in most cases: "www.facebook.com"), path
  31  * ("/foo/bar"), query ("key=foo") and fragment ("anchor").  The scheme is
  32  * lower-cased.
  33  *
  34  * If this Uri represents a URL, note that, to prevent ambiguity, the component
  35  * parts are NOT percent-decoded; you should do this yourself with
  36  * uriUnescape() (for the authority and path) and uriUnescape(...,
  37  * UriEscapeMode::QUERY) (for the query, but probably only after splitting at
  38  * '&' to identify the individual parameters).
  39  */
  40 class Uri {
  41  public:
  42   /**
  43    * Parse a Uri from a string.  Throws std::invalid_argument on parse error.
  44    */
  45   explicit Uri(StringPiece str);
  46
  47   const fbstring& scheme() const { return scheme_; }
  48   const fbstring& username() const { return username_; }
  49   const fbstring& password() const { return password_; }
  50   /**
  51    * Get host part of URI. If host is an IPv6 address, square brackets will be
  52    * returned, for example: "[::1]".
  53    */
  54   const fbstring& host() const { return host_; }
  55   /**
  56    * Get host part of URI. If host is an IPv6 address, square brackets will not
  57    * be returned, for exmaple "::1"; otherwise it returns the same thing as
  58    * host().
  59    *
  60    * hostname() is what one needs to call if passing the host to any other tool
  61    * or API that connects to that host/port; e.g. getaddrinfo() only understands
  62    * IPv6 host without square brackets
  63    */
  64   fbstring hostname() const;
  65   uint16_t port() const { return port_; }
  66   const fbstring& path() const { return path_; }
  67   const fbstring& query() const { return query_; }
  68   const fbstring& fragment() const { return fragment_; }
  69
  70   fbstring authority() const;
  71
  72   template <class String>
  73   String toString() const;
  74
  75   std::string str() const { return toString<std::string>(); }
  76   fbstring fbstr() const { return toString<fbstring>(); }
  77
  78   void setPort(uint16_t port) {port_ = port;}
  79
  80  private:
  81   fbstring scheme_;
  82   fbstring username_;
  83   fbstring password_;
  84   fbstring host_;
  85   uint16_t port_;
  86   fbstring path_;
  87   fbstring query_;
  88   fbstring fragment_;
  89 };
  90
  91 }  // namespace folly
  92
  93 #include "folly/Uri-inl.h"
  94
  95 #endif /* FOLLY_URI_H_ */