davix/utils/davix_uri.hpp

0001 /*
0002  * This File is part of Davix, The IO library for HTTP based protocols
0003  * Copyright (C) CERN 2013
0004  * Author: Adrien Devresse <adrien.devresse@cern.ch>
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General Public
0017  * License along with this library; if not, write to the Free Software
0018  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
0019  *
0020 */
0021
0022 #pragma once
0023 #ifndef DAVIX_DAVIXURI_HPP
0024 #define DAVIX_DAVIXURI_HPP
0025
0026 #include <string>
0027 #include <utils/davix_types.hpp>
0028 #include <status/davixstatusrequest.hpp>
0029
0030
0031
0032 /**
0033   @file davix_uri.hpp
0034   @author Devresse Adrien
0035   @brief URI utilities functions for davix
0036  */
0037
0038 #ifndef __DAVIX_INSIDE__
0039 #error "Only davix.h or davix.hpp should be included."
0040 #endif
0041
0042
0043 namespace Davix {
0044
0045 struct UriPrivate;
0046
0047 /// @class Uri
0048 /// @brief Uri parser
0049 ///
0050 /// convenience class for uri parsing
0051 ///
0052 /// @snippet example_code_snippets.cpp Uri example
0053
0054 class DAVIX_EXPORT Uri
0055 {
0056 public:
0057     /// Construct an empty invalid Uri
0058     Uri();
0059     /// construct a new Davix Uri from a string URL
0060     Uri(const std::string & uri_string);
0061     /// Copy constructor
0062     Uri(const Uri & uri);
0063     ///
0064     /// \brief assignment operator
0065     /// \param orig
0066     /// \return
0067     ///
0068     Uri & operator=(const Uri & orig);
0069     virtual ~Uri();
0070
0071     /// append a query parameter to the uri
0072     /// @param key : parameter key, not escaped
0073     /// @param value : parameter value, not escaped
0074     void addQueryParam(const std::string & key, const std::string & value);
0075
0076     /// append a fragment parameter to the uri
0077     /// @param key : key
0078     /// @param value : value
0079     void addFragmentParam(const std::string & key, const std::string & value);
0080
0081     /// append a path segment to the uri
0082     /// @param seg : the segment to add
0083     void addPathSegment(const std::string & seg);
0084
0085     /// ensure that the path ends with a trailing slash
0086     void ensureTrailingSlash();
0087
0088     /// remove the path's trailing slash, if it exists
0089     void removeTrailingSlash();
0090
0091     /// check if the given query parameter exists
0092     bool queryParamExists(const std::string &param) const;
0093
0094     /// check if the given fragment parameter exists
0095     bool fragmentParamExists(const std::string &param) const;
0096
0097     /// get the value of a fragment parameter
0098     const std::string getFragmentParam(const std::string &param) const;
0099
0100     /// get a string representation of the full uri
0101     /// @return return the path or an empty string if error
0102     const std::string & getString() const;
0103
0104     /// get the port number
0105     /// @return return the prot number of 0 if unspecified
0106     int getPort() const;
0107
0108     /// get the protocol scheme
0109     ///  @return return the protocol scheme or an empty string if error
0110     const std::string & getProtocol() const;
0111
0112     /// get the host name
0113     /// @return return the hostname or an empty string if error
0114     const std::string & getHost() const;
0115
0116     /// get the path part of the Uri
0117     /// @return return the path of the Uri or an empty string if error
0118     const std::string & getPath()const;
0119
0120     // set the path part of the Uri
0121     void setPath(const std::string & path);
0122
0123     // change the protocol of the Uri
0124     void setProtocol(const std::string & protocol);
0125
0126     // change the protocol to either http or https, whichever is appropriate
0127     void httpizeProtocol();
0128
0129     /// gextract user information from the URI
0130     /// @return return the path of the Uri or an empty string if error
0131     const std::string & getUserInfo() const;
0132
0133     /// get a concatenation of the path and the query argument of the URI
0134     /// @return return a path + query arguments concatenation or an empty string if error
0135     const std::string & getPathAndQuery() const;
0136
0137     /// get the fragment part of the uri
0138     /// @return return the fragment part or an empty string if it does not exist
0139     const std::string & getFragment() const;
0140
0141     /// get the query argument part of the uri
0142     /// @return return the query path string or an empty string if not exist or if error
0143     const std::string & getQuery() const;
0144
0145     // get the query argument part of the uri as a vector
0146     // @return return a vector with all query parameters
0147     ParamVec getQueryVec() const;
0148
0149     /// Status of the Uri
0150     /// see StatusCode::Code
0151     /// @return StatusCode::OK if success or StatusCode::UriParsingError if error
0152     StatusCode::Code getStatus() const;
0153
0154     ///
0155     /// \brief test if two URI are equals
0156     /// \param u1
0157     /// \return true if equal, else false
0158     ///
0159     bool equal(const Uri & u1) const;
0160
0161     ///
0162     /// \brief compare oepration
0163     /// \param u2
0164     /// \return true if u2 == current uri
0165     ///
0166     bool operator==(const Uri & u2) const;
0167
0168     ///
0169     /// \brief Join two paths
0170     /// \param left URL or filesystem path
0171     //  \param right Directory chunk, unescaped
0172     /// \return The join of left and right, correctly escaped if left is a URL
0173     //          and not a filesystem path
0174     ///
0175     static std::string join(const std::string &left, const std::string &right);
0176
0177     ///
0178     /// \brief Escape string
0179     /// \param str URL to escape
0180     /// \return encoded string
0181     ///
0182     static std::string escapeString(const std::string & str);
0183
0184     ///
0185     /// \brief Unescape urI
0186     /// \param str URL to escape
0187     /// \return unencoded string
0188     ///
0189     static std::string unescapeString(const std::string & str);
0190
0191     ///
0192     /// \brief Escape query parameter
0193     /// \param str to escape
0194     /// \return encoded string
0195
0196     static std::string queryParamEscape(const std::string & str);
0197
0198     ///
0199     /// \brief create a new Uri from URI and a relative associated path
0200     /// \param uri original URI
0201     /// \param relPath relative path
0202     /// \return new URI from this path
0203     ///
0204     static Uri fromRelativePath(const Uri & uri, const std::string & relPath);
0205
0206
0207 private:
0208     UriPrivate* d_ptr;
0209     void _init();
0210 };
0211
0212
0213 ///
0214 /// check the validity of a Davix::Uri
0215 /// @param uri : davix uri
0216 /// @param err : Davix Error report object
0217 /// @return true if the uri is valid, or false and setup err with a string expression
0218 bool DAVIX_EXPORT uriCheckError(const Uri & uri, DavixError ** err);
0219
0220
0221 /// return associated std port for this request
0222 /// return default http port or default SSL port if not precised
0223 unsigned int DAVIX_EXPORT httpUriGetPort(const Uri & uri);
0224
0225
0226 std::ostream& operator<< (std::ostream& stream, const Davix::Uri & _u);
0227
0228 } // namespace Davix
0229
0230
0231 #endif // DAVIX_DAVIXURI_HPP