url.h

Go to the documentation of this file.

/*
 * url.h
 *
 * Universal Resource Locator (for HTTP/HTML) class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-2002 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): ______________________________________.
 */

#ifndef PTLIB_PURL_H
#define PTLIB_PURL_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif


#if P_URL

#include <ptlib/pfactory.h>


class PURLScheme;
class PURLLegacyScheme;


// PURL

class PURL : public PObject
{
    PCLASSINFO_WITH_CLONE(PURL, PObject)
  public:
    PURL();
    PURL(
      const char * cstr,    
      const char * defaultScheme = "http" 
    );
    PURL(
      const PString & str,  
      const char * defaultScheme = "http" 
    );
    PURL(
      const PFilePath & path   
    );

    PURL(const PURL & other);
    PURL & operator=(const PURL & other);

    virtual Comparison Compare(
      const PObject & obj   
    ) const;

    virtual PINDEX HashFunction() const;

    virtual void PrintOn(
      ostream &strm   
    ) const;

    virtual void ReadFrom(
      istream &strm   
    );
 
    inline PBoolean Parse(
      const char * cstr,   
      const char * defaultScheme = NULL 
    ) { return InternalParse(cstr, defaultScheme); }
    inline PBoolean Parse(
      const PString & str, 
      const char * defaultScheme = NULL 
    ) { return InternalParse((const char *)str, defaultScheme); }

    enum UrlFormat {
      FullURL,       
      PathOnly,      
      LocationOnly,  
      RelativeOnly,  

      // for backward compatibility
      HostPortOnly = LocationOnly,
      URIOnly = RelativeOnly
    };

    PString AsString(
      UrlFormat fmt = FullURL   
    ) const;
    operator PString() const { return AsString(); }

    PFilePath AsFilePath() const;

    enum TranslationType {
      LoginTranslation,
      PathTranslation,
      QueryTranslation,
      ParameterTranslation,
      QuotedParameterTranslation
    };

    static PString TranslateString(
      const PString & str,    
      TranslationType type    
    );

    static PString UntranslateString(
      const PString & str,    
      TranslationType type    
    );

    static void SplitVars(
      const PString & str,    
      PStringToString & vars, 
      char sep1 = ';',        
      char sep2 = '=',        
      TranslationType type = ParameterTranslation 
    );

    static void SplitQueryVars(
      const PString & queryStr,   
      PStringToString & queryVars 
    ) { SplitVars(queryStr, queryVars, '&', '=', QueryTranslation); }

    static void OutputVars(
      ostream & strm,               
      const PStringToString & vars, 
      char sep0 = ';',              
      char sep1 = ';',              
      char sep2 = '=',              
      TranslationType type = ParameterTranslation 
    );


    static PCaselessString ExtractScheme(const char * str);

    const PCaselessString & GetScheme() const { return m_scheme; }

    bool SetScheme(const PString & scheme);

    const PString & GetUserName() const { return m_username; }

    void SetUserName(const PString & username);

    const PString & GetPassword() const { return m_password; }

    void SetPassword(const PString & password);

    const PCaselessString & GetHostName() const { return m_hostname; }

    void SetHostName(const PString & hostname);

    WORD GetPort() const { return m_port; }

    void SetPort(WORD newPort);
    
    PBoolean GetPortSupplied() const { return m_portSupplied; }

    PString GetHostPort() const;

    PBoolean GetRelativePath() const { return m_relativePath; }

    PString GetPathStr() const;

    void SetPathStr(const PString & pathStr);

    const PStringArray & GetPath() const { return m_path; }

    void SetPath(const PStringArray & path);

    void AppendPath(const PString & segment);

    void ChangePath(
      const PString & segment, 
      PINDEX idx = P_MAX_INDEX 
    );

    PString GetParameters() const;

    void SetParameters(const PString & parameters);

    const PStringOptions & GetParamVars() const { return m_paramVars; }

    void SetParamVars(
      const PStringToString & paramVars,
      bool merge = false
    );

    void SetParamVar(
      const PString & key,          
      const PString & data,         
      bool emptyDataDeletes = true  
    );

    const PString & GetFragment() const { return m_fragment; }

    PString GetQuery() const;

    void SetQuery(const PString & query);

    const PStringOptions & GetQueryVars() const { return m_queryVars; }

    void SetQueryVars(const PStringToString & queryVars);

    void SetQueryVar(const PString & key, const PString & data);

    const PString & GetContents() const { return m_contents; }

    void SetContents(const PString & str);

    PBoolean IsEmpty() const { return m_urlString.IsEmpty(); }


    struct LoadParams {
      LoadParams(
        const PString & requiredContentType = PString::Empty(),
        const PTimeInterval & timeout = PMaxTimeInterval
      ) : m_requiredContentType(requiredContentType)
        , m_timeout(timeout)
      {
      }

      PString       m_requiredContentType;
      PTimeInterval m_timeout;

      PString       m_username;     // Basic authentication
      PString       m_password;
#if P_SSL
      PString       m_authority;    // Directory, file or data
      PString       m_certificate;  // File or data
      PString       m_privateKey;   // File or data
#endif
      PStringOptions m_customOptions; // E.g. headers for http
    };
    bool LoadResource(
      PString & data,  
      const LoadParams & params = LoadParams()  
    ) const;
    bool LoadResource(
      PBYTEArray & data,  
      const LoadParams & params = LoadParams()  
    ) const;

    // For backward compatibility
    template <class T>
    bool LoadResource(
      T & data,  
      const PString & requiredContentType = PString::Empty(), 
      const PTimeInterval & timeout = PMaxTimeInterval        
    ) const { return LoadResource(data, LoadParams(requiredContentType, timeout)); }

    bool OpenBrowser() const { return OpenBrowser(AsString()); }
    static bool OpenBrowser(
      const PString & url   
    );

    bool LegacyParse(const char * str, const PURLLegacyScheme * schemeInfo);
    PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme * schemeInfo) const;

  protected:
    void CopyContents(const PURL & other);
    virtual PBoolean InternalParse(
      const char * cstr,         
      const char * defaultScheme 
    );
    void Recalculate();

    const PURLScheme * m_schemeInfo;
    PString            m_urlString;

    PCaselessString m_scheme;
    PString         m_username;
    PString         m_password;
    PCaselessString m_hostname;
    WORD            m_port;
    bool            m_portSupplied;          
    bool            m_relativePath;
    PStringArray    m_path;
    PStringOptions  m_paramVars;
    PString         m_fragment;
    PStringOptions  m_queryVars;
    PString         m_contents;  // Anything left after parsing other elements
};


// PURLScheme

class PURLScheme : public PObject
{
  PCLASSINFO(PURLScheme, PObject);
  public:
    virtual bool Parse(const char * cstr, PURL & url) const = 0;
    virtual PString AsString(PURL::UrlFormat fmt, const PURL & purl) const = 0;
    virtual WORD GetDefaultPort() const { return 0; }
};

typedef PFactory<PURLScheme> PURLSchemeFactory;


// PURLLegacyScheme

class PURLLegacyScheme : public PURLScheme
{
  public:
    PURLLegacyScheme(
      bool user    = false,
      bool pass    = false,
      bool host    = false,
      bool def     = false,
      bool defhost = false,
      bool query   = false,
      bool params  = false,
      bool frags   = false,
      bool path    = false,
      bool rel     = false,
      WORD port    = 0
    )
      : hasUsername           (user)
      , hasPassword           (pass)
      , hasHostPort           (host)
      , defaultToUserIfNoAt   (def)
      , defaultHostToLocal    (defhost)
      , hasQuery              (query)
      , hasParameters         (params)
      , hasFragments          (frags)
      , hasPath               (path)
      , relativeImpliesScheme (rel)
      , defaultPort           (port)
    { }

    bool Parse(const char * cstr, PURL & url) const
    {
      return url.LegacyParse(cstr, this);
    }

    PString AsString(PURL::UrlFormat fmt, const PURL & url) const
    {
      return url.LegacyAsString(fmt, this);
    }

    virtual WORD GetDefaultPort() const { return defaultPort; }

    bool hasUsername;
    bool hasPassword;
    bool hasHostPort;
    bool defaultToUserIfNoAt;
    bool defaultHostToLocal;
    bool hasQuery;
    bool hasParameters;
    bool hasFragments;
    bool hasPath;
    bool relativeImpliesScheme;
    WORD defaultPort;
};

#define PURL_LEGACY_SCHEME(schemeName, \
                           hasUsername,           /* URL scheme has a username */ \
                           hasPassword,           /* URL scheme has a password */ \
                           hasHostPort,           /* URL scheme has a host:port */ \
                           defaultToUserIfNoAt,   /* URL scheme is username if no @, otherwise host:port */ \
                           defaultHostToLocal,    /* URL scheme defaults to PIPSocket::GetHostName() if not present */ \
                           hasQuery,              /* URL scheme has a query section */ \
                           hasParameters,         /* URL scheme has a parameter section */ \
                           hasFragments,          /* URL scheme has a fragment section */ \
                           hasPath,               /* URL scheme has a path */ \
                           relativeImpliesScheme, /* URL scheme has relative path (no //) then scheme: is not output */ \
                           defaultPort)           /* URL scheme default port if not specified in host:port */ \
  class PURLLegacyScheme_##schemeName : public PURLLegacyScheme \
  { \
    public: \
      PURLLegacyScheme_##schemeName() \
        : PURLLegacyScheme(hasUsername, \
                           hasPassword, \
                           hasHostPort, \
                           defaultToUserIfNoAt, \
                           defaultHostToLocal, \
                           hasQuery, \
                           hasParameters, \
                           hasFragments, \
                           hasPath, \
                           relativeImpliesScheme, \
                           defaultPort) \
        { } \
  }; \
  PFACTORY_CREATE(PURLSchemeFactory, PURLLegacyScheme_##schemeName, #schemeName, true)



// PURLLoader

class PURLLoader : public PObject
{
  PCLASSINFO(PURLLoader, PObject);
  public:
    virtual bool Load(PString & str, const PURL & url, const PURL::LoadParams & params) const = 0;
    virtual bool Load(PBYTEArray & data, const PURL & url, const PURL::LoadParams & params) const = 0;
};

typedef PFactory<PURLLoader> PURLLoaderFactory;

#if P_HTTP
  PFACTORY_LOAD(PURL_HttpLoader);
#endif // P_HTTP
#if P_FTP
  PFACTORY_LOAD(PURL_FtpLoader);
#endif // P_HTTP


#endif // P_URL

#endif // PTLIB_PURL_H


// End Of File ///////////////////////////////////////////////////////////////