PTLib  Version 2.10.10
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
url.h
Go to the documentation of this file.
1 /*
2  * url.h
3  *
4  * Universal Resource Locator (for HTTP/HTML) class.
5  *
6  * Portable Windows Library
7  *
8  * Copyright (c) 1993-2002 Equivalence Pty. Ltd.
9  *
10  * The contents of this file are subject to the Mozilla Public License
11  * Version 1.0 (the "License"); you may not use this file except in
12  * compliance with the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS"
16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17  * the License for the specific language governing rights and limitations
18  * under the License.
19  *
20  * The Original Code is Portable Windows Library.
21  *
22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
23  *
24  * Contributor(s): ______________________________________.
25  *
26  * $Revision: 27132 $
27  * $Author: rjongbloed $
28  * $Date: 2012-03-06 17:29:05 -0600 (Tue, 06 Mar 2012) $
29  */
30 
31 #ifndef PTLIB_PURL_H
32 #define PTLIB_PURL_H
33 
34 #ifdef P_USE_PRAGMA
35 #pragma interface
36 #endif
37 
38 
39 #if P_URL
40 
41 #include <ptlib/pfactory.h>
42 
43 
45 // PURL
46 
47 class PURLLegacyScheme;
48 
54 class PURL : public PObject
55 {
57  public:
59  PURL();
61  PURL(
62  const char * cstr,
63  const char * defaultScheme = "http"
64  );
66  PURL(
67  const PString & str,
68  const char * defaultScheme = "http"
69  );
71  PURL(
72  const PFilePath & path
73  );
74 
75  PURL(const PURL & other);
76  PURL & operator=(const PURL & other);
77 
86  virtual Comparison Compare(
87  const PObject & obj
88  ) const;
89 
101  virtual PINDEX HashFunction() const;
102 
105  virtual void PrintOn(
106  ostream &strm
107  ) const;
108 
112  virtual void ReadFrom(
113  istream &strm
114  );
116 
120  inline PBoolean Parse(
121  const char * cstr,
122  const char * defaultScheme = NULL
123  ) { return InternalParse(cstr, defaultScheme); }
125  inline PBoolean Parse(
126  const PString & str,
127  const char * defaultScheme = NULL
128  ) { return InternalParse((const char *)str, defaultScheme); }
129 
131  enum UrlFormat {
140  };
141 
149  UrlFormat fmt = FullURL
150  ) const;
151  operator PString() const { return AsString(); }
152 
156  PFilePath AsFilePath() const;
157 
170  };
171 
179  static PString TranslateString(
180  const PString & str,
181  TranslationType type
182  );
183 
191  static PString UntranslateString(
192  const PString & str,
193  TranslationType type
194  );
195 
197  static void SplitVars(
198  const PString & str,
199  PStringToString & vars,
200  char sep1 = ';',
201  char sep2 = '=',
203  );
204 
206  static void SplitQueryVars(
207  const PString & queryStr,
209  ) { SplitVars(queryStr, queryVars, '&', '=', QueryTranslation); }
210 
213  static void OutputVars(
214  ostream & strm,
215  const PStringToString & vars,
216  char sep0 = ';',
217  char sep1 = ';',
218  char sep2 = '=',
220  );
221 
222 
224  const PCaselessString & GetScheme() const { return scheme; }
225 
227  void SetScheme(const PString & scheme);
228 
230  const PString & GetUserName() const { return username; }
231 
233  void SetUserName(const PString & username);
234 
236  const PString & GetPassword() const { return password; }
237 
239  void SetPassword(const PString & password);
240 
242  const PCaselessString & GetHostName() const { return hostname; }
243 
245  void SetHostName(const PString & hostname);
246 
248  WORD GetPort() const { return port; }
249 
251  void SetPort(WORD newPort);
252 
255 
258 
260  PString GetPathStr() const;
261 
263  void SetPathStr(const PString & pathStr);
264 
266  const PStringArray & GetPath() const { return path; }
267 
269  void SetPath(const PStringArray & path);
270 
272  void AppendPath(const PString & segment);
273 
275  PString GetParameters() const;
276 
278  void SetParameters(const PString & parameters);
279 
282  const PStringOptions & GetParamVars() const { return paramVars; }
283 
286  void SetParamVars(const PStringToString & paramVars);
287 
290  void SetParamVar(
291  const PString & key,
292  const PString & data,
293  bool emptyDataDeletes = true
294  );
295 
297  const PString & GetFragment() const { return fragment; }
298 
300  PString GetQuery() const;
301 
304  void SetQuery(const PString & query);
305 
308  const PStringOptions & GetQueryVars() const { return queryVars; }
309 
312  void SetQueryVars(const PStringToString & queryVars);
313 
316  void SetQueryVar(const PString & key, const PString & data);
317 
319  const PString & GetContents() const { return m_contents; }
320 
322  void SetContents(const PString & str);
323 
325  PBoolean IsEmpty() const { return urlString.IsEmpty(); }
326 
327 
332  bool LoadResource(
333  PString & data,
334  const PString & requiredContentType = PString::Empty()
335  ) const;
336  bool LoadResource(
337  PBYTEArray & data,
338  const PString & requiredContentType = PString::Empty()
339  ) const;
340 
347  bool OpenBrowser() const { return OpenBrowser(AsString()); }
348  static bool OpenBrowser(
349  const PString & url
350  );
352 
353  PBoolean LegacyParse(const PString & url, const PURLLegacyScheme * schemeInfo);
354  PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme * schemeInfo) const;
355 
356  protected:
357  void CopyContents(const PURL & other);
358  virtual PBoolean InternalParse(
359  const char * cstr,
360  const char * defaultScheme
361  );
362  void Recalculate();
364 
369  WORD port;
376  PString m_contents; // Anything left after parsing other elements
377 };
378 
379 
381 // PURLScheme
382 
383 class PURLScheme : public PObject
384 {
385  PCLASSINFO(PURLScheme, PObject);
386  public:
387  virtual PString GetName() const = 0;
388  virtual PBoolean Parse(const PString & url, PURL & purl) const = 0;
389  virtual PString AsString(PURL::UrlFormat fmt, const PURL & purl) const = 0;
390 };
391 
393 
394 
396 // PURLLegacyScheme
397 
399 {
400  public:
402  const char * s,
403  bool user = false,
404  bool pass = false,
405  bool host = false,
406  bool def = false,
407  bool defhost = false,
408  bool query = false,
409  bool params = false,
410  bool frags = false,
411  bool path = false,
412  bool rel = false,
413  WORD port = 0
414  )
415  : scheme(s)
416  , hasUsername (user)
417  , hasPassword (pass)
418  , hasHostPort (host)
419  , defaultToUserIfNoAt (def)
420  , defaultHostToLocal (defhost)
421  , hasQuery (query)
422  , hasParameters (params)
423  , hasFragments (frags)
424  , hasPath (path)
425  , relativeImpliesScheme (rel)
426  , defaultPort (port)
427  { }
428 
429  PBoolean Parse(const PString & url, PURL & purl) const
430  { return purl.LegacyParse(url, this); }
431 
432  PString AsString(PURL::UrlFormat fmt, const PURL & purl) const
433  { return purl.LegacyAsString(fmt, this); }
434 
435  PString GetName() const
436  { return scheme; }
437 
444  bool hasQuery;
447  bool hasPath;
450 };
451 
452 #define PURL_LEGACY_SCHEME(schemeName, user, pass, host, def, defhost, query, params, frags, path, rel, port) \
453  class PURLLegacyScheme_##schemeName : public PURLLegacyScheme \
454  { \
455  public: \
456  PURLLegacyScheme_##schemeName() \
457  : PURLLegacyScheme(#schemeName, user, pass, host, def, defhost, query, params, frags, path, rel, port) \
458  { } \
459  }; \
460  static PURLSchemeFactory::Worker<PURLLegacyScheme_##schemeName> schemeName##Factory(#schemeName, true); \
461 
462 
463 
465 // PURLLoader
466 
467 class PURLLoader : public PObject
468 {
469  PCLASSINFO(PURLLoader, PObject);
470  public:
471  virtual bool Load(const PURL & url, PString & str, const PString & requiredContentType) = 0;
472  virtual bool Load(const PURL & url, PBYTEArray & data, const PString & requiredContentType) = 0;
473 };
474 
476 
477 
478 #endif // P_URL
479 
480 #endif // PTLIB_PURL_H
481 
482 
483 // End Of File ///////////////////////////////////////////////////////////////
Translate the path field for a URL.
Definition: url.h:163
virtual PBoolean InternalParse(const char *cstr, const char *defaultScheme)
WORD GetPort() const
Get the port field of the URL.
Definition: url.h:248
virtual void ReadFrom(istream &strm)
Input the contents of the URL from the stream.
bool defaultToUserIfNoAt
Definition: url.h:442
PStringOptions paramVars
Definition: url.h:373
static void SplitQueryVars(const PString &queryStr, PStringToString &queryVars)
Split a string in &amp;= form to a dictionary of names and values.
Definition: url.h:206
const PStringOptions & GetQueryVars() const
Get the Query (?) field of the URL as a string dictionary.
Definition: url.h:308
PFactory< PURLLoader > PURLLoaderFactory
Definition: url.h:475
PBoolean LegacyParse(const PString &url, const PURLLegacyScheme *schemeInfo)
void SetPathStr(const PString &pathStr)
Set the path field of the URL as a string.
Definition: url.h:398
PBoolean IsEmpty() const
Return true if the URL is an empty string.
Definition: url.h:325
Translate to a string as a full URL.
Definition: url.h:133
#define PCLASSINFO(cls, par)
Declare all the standard PTLib class information.
Definition: object.h:1049
PURLLegacyScheme(const char *s, 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)
Definition: url.h:401
PString m_contents
Definition: url.h:376
virtual Comparison Compare(const PObject &obj) const
Compare the two URLs and return their relative rank.
bool hasQuery
Definition: url.h:444
bool hasUsername
Definition: url.h:439
void SetHostName(const PString &hostname)
Set the hostname field of the URL.
PString scheme
Definition: url.h:438
PURL & operator=(const PURL &other)
TranslationType
Type for translation of strings to URL format,.
Definition: url.h:159
static void OutputVars(ostream &strm, const PStringToString &vars, char sep0= ';', char sep1= ';', char sep2= '=', TranslationType type=ParameterTranslation)
Construct string from a dictionary using separators.
PBoolean Parse(const char *cstr, const char *defaultScheme=NULL)
Parse the URL string into the fields in the object instance.
Definition: url.h:120
PString username
Definition: url.h:366
bool hasHostPort
Definition: url.h:441
Translate the parameter variables field for a URL.
Definition: url.h:167
void Recalculate()
bool LoadResource(PString &data, const PString &requiredContentType=PString::Empty()) const
Get the resource the URL is pointing at.
PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme *schemeInfo) const
This is a dictionary collection class of PString objects, keyed by another string.
Definition: pstring.h:2784
This class describes a full description for a file on the particular platform.
Definition: filepath.h:65
void SetUserName(const PString &username)
Set the username field of the URL.
Comparison
Result of the comparison operation performed by the Compare() function.
Definition: object.h:1184
PString fragment
Definition: url.h:374
This class is a variation of a string that ignores case.
Definition: pstring.h:1708
void SetParamVars(const PStringToString &paramVars)
Set the parameter (;) field(s) of the URL as a string dictionary.
PBoolean Parse(const PString &str, const char *defaultScheme=NULL)
Parse the URL string into the fields in the object instance.
Definition: url.h:125
void AppendPath(const PString &segment)
Append segment to the path field of the URL.
This is an array collection class of PString objects.
Definition: pstring.h:2024
void SetContents(const PString &str)
Set the contents of URL, data left after all elemetns are parsed out.
Translate the quoted parameter variables field for a URL.
Definition: url.h:169
PString password
Definition: url.h:367
static void SplitVars(const PString &str, PStringToString &vars, char sep1= ';', char sep2= '=', TranslationType type=ParameterTranslation)
Split a string to a dictionary of names and values.
Translate the query variable field for a URL.
Definition: url.h:165
void SetQueryVar(const PString &key, const PString &data)
Set the Query (?) field of the URL as a string dictionary.
const PStringOptions & GetParamVars() const
Get the parameter (;) field(s) of the URL as a string dictionary.
Definition: url.h:282
virtual PBoolean IsEmpty() const
Determine if the string is empty.
PBoolean GetPortSupplied() const
Get if explicit port is specified.
Definition: url.h:254
static PString UntranslateString(const PString &str, TranslationType type)
Untranslate a string from a form that was included into a URL into a normal string.
PURL()
Construct a new URL object from the URL string.
void SetPath(const PStringArray &path)
Set the path field of the URL as a string array.
virtual PString AsString(PURL::UrlFormat fmt, const PURL &purl) const =0
BOOL PBoolean
Definition: object.h:102
Translate to a string with scheme and host/port.
Definition: url.h:139
PString GetQuery() const
Get the Query (?) field of the URL as a string.
Array of unsigned characters.
Definition: array.h:670
PString GetPathStr() const
Get the path field of the URL as a string.
Specialised version of PStringToString to contain a dictionary of options/attributes.
Definition: pstring.h:2845
PString GetName() const
Definition: url.h:435
const PString & GetPassword() const
Get the password field of the URL.
Definition: url.h:236
const PCaselessString & GetHostName() const
Get the hostname field of the URL.
Definition: url.h:242
bool hasParameters
Definition: url.h:445
Definition: url.h:467
virtual PINDEX HashFunction() const
This function yields a hash value required by the PDictionary class.
void SetScheme(const PString &scheme)
Set the scheme field of the URL.
void SetPort(WORD newPort)
Set the port field in the URL.
Translate to a string as only path.
Definition: url.h:135
static PString TranslateString(const PString &str, TranslationType type)
Translate a string from general form to one that can be included into a URL.
PFactory< PURLScheme > PURLSchemeFactory
Definition: url.h:392
void SetQuery(const PString &query)
Set the Query (?) field of the URL as a string.
const PStringArray & GetPath() const
Get the path field of the URL as a string array.
Definition: url.h:266
virtual PString GetName() const =0
PCaselessString scheme
Definition: url.h:365
PBoolean portSupplied
Definition: url.h:370
PString urlString
Definition: url.h:363
The character string class.
Definition: pstring.h:108
PCaselessString hostname
Definition: url.h:368
virtual bool Load(const PURL &url, PString &str, const PString &requiredContentType)=0
virtual PBoolean Parse(const PString &url, PURL &purl) const =0
PFilePath AsFilePath() const
Get the &quot;file:&quot; URL as a file path.
static PString Empty()
Return an empty string.
PString GetParameters() const
Get the parameter (;) field of the URL.
bool hasPassword
Definition: url.h:440
Definition: url.h:383
const PCaselessString & GetScheme() const
Get the scheme field of the URL.
Definition: url.h:224
UrlFormat
Print/String output representation formats.
Definition: url.h:131
const PString & GetFragment() const
Get the fragment (#) field of the URL.
Definition: url.h:297
Template class for generic factories of an abstract class.
Definition: pfactory.h:144
bool OpenBrowser() const
Open the URL in a browser.
Definition: url.h:347
void SetParamVar(const PString &key, const PString &data, bool emptyDataDeletes=true)
Set the parameter (;) field of the URL as a string dictionary.
PStringOptions queryVars
Definition: url.h:375
Translate a username/password field for a URL.
Definition: url.h:161
bool hasFragments
Definition: url.h:446
const PString & GetUserName() const
Get the username field of the URL.
Definition: url.h:230
virtual void PrintOn(ostream &strm) const
Output the contents of the URL to the stream as a string.
bool hasPath
Definition: url.h:447
bool defaultHostToLocal
Definition: url.h:443
PString AsString(PURL::UrlFormat fmt, const PURL &purl) const
Definition: url.h:432
void SetPassword(const PString &password)
Set the password field of the URL.
const PString & GetContents() const
Get the contents of URL, data left after all elemetns are parsed out.
Definition: url.h:319
PBoolean relativePath
port was supplied in string input
Definition: url.h:371
WORD defaultPort
Definition: url.h:449
void SetParameters(const PString &parameters)
Set the parameter (;) field of the URL.
bool relativeImpliesScheme
Definition: url.h:448
PString AsString(UrlFormat fmt=FullURL) const
Convert the URL object into its string representation.
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
This class describes a Universal Resource Locator.
Definition: url.h:54
PBoolean GetRelativePath() const
Get if path is relative or absolute.
Definition: url.h:257
PBoolean Parse(const PString &url, PURL &purl) const
Definition: url.h:429
Translate to a string with no scheme or host.
Definition: url.h:137
void SetQueryVars(const PStringToString &queryVars)
Set the Query (?) field(s) of the URL as a string dictionary.
WORD port
Definition: url.h:369
PStringArray path
Definition: url.h:372
void CopyContents(const PURL &other)