PTLib Version 2.12.9

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- File List
- File Members

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: 29661 $
27 * $Author: rjongbloed $
28 * $Date: 2013-05-08 15:02:01 +1000 (Wed, 08 May 2013) $
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
44 class PURLScheme;
45 class PURLLegacyScheme;
46
47
49 // PURL
50
60 class PURL : public PObject
61 {
62 PCLASSINFO(PURL, PObject)
63 public:
65 PURL();
67 PURL(
68 const char * cstr,
69 const char * defaultScheme = "http"
70 );
72 PURL(
73 const PString & str,
74 const char * defaultScheme = "http"
75 );
77 PURL(
78 const PFilePath & path
79 );
80
81 PURL(const PURL & other);
82 PURL & operator=(const PURL & other);
83
92 virtual Comparison Compare(
93 const PObject & obj
94 ) const;
95
107 virtual PINDEX HashFunction() const;
108
111 virtual void PrintOn(
112 ostream &strm
113 ) const;
114
118 virtual void ReadFrom(
119 istream &strm
120 );
122
126 inline PBoolean Parse(
127 const char * cstr,
128 const char * defaultScheme = NULL
129 ) { return InternalParse(cstr, defaultScheme); }
131 inline PBoolean Parse(
132 const PString & str,
133 const char * defaultScheme = NULL
134 ) { return InternalParse((const char *)str, defaultScheme); }
135
137 enum UrlFormat {
138 FullURL,
139 PathOnly,
140 LocationOnly,
141 RelativeOnly,
142
143 // for backward compatibility
144 HostPortOnly = LocationOnly,
145 URIOnly = RelativeOnly
146 };
147
154 PString AsString(
155 UrlFormat fmt = FullURL
156 ) const;
157 operator PString() const { return AsString(); }
158
162 PFilePath AsFilePath() const;
163
165 enum TranslationType {
167 LoginTranslation,
169 PathTranslation,
171 QueryTranslation,
173 ParameterTranslation,
175 QuotedParameterTranslation
176 };
177
185 static PString TranslateString(
186 const PString & str,
187 TranslationType type
188 );
189
197 static PString UntranslateString(
198 const PString & str,
199 TranslationType type
200 );
201
203 static void SplitVars(
204 const PString & str,
205 PStringToString & vars,
206 char sep1 = ';',
207 char sep2 = '=',
208 TranslationType type = ParameterTranslation
209 );
210
212 static void SplitQueryVars(
213 const PString & queryStr,
214 PStringToString & queryVars
215 ) { SplitVars(queryStr, queryVars, '&', '=', QueryTranslation); }
216
219 static void OutputVars(
220 ostream & strm,
221 const PStringToString & vars,
222 char sep0 = ';',
223 char sep1 = ';',
224 char sep2 = '=',
225 TranslationType type = ParameterTranslation
226 );
227
228
230 const PCaselessString & GetScheme() const { return scheme; }
231
233 bool SetScheme(const PString & scheme);
234
236 const PString & GetUserName() const { return username; }
237
239 void SetUserName(const PString & username);
240
242 const PString & GetPassword() const { return password; }
243
245 void SetPassword(const PString & password);
246
248 const PCaselessString & GetHostName() const { return hostname; }
249
251 void SetHostName(const PString & hostname);
252
254 WORD GetPort() const { return port; }
255
257 void SetPort(WORD newPort);
258
260 PBoolean GetPortSupplied() const { return portSupplied; }
261
263 PString GetHostPort() const;
264
266 PBoolean GetRelativePath() const { return relativePath; }
267
269 PString GetPathStr() const;
270
272 void SetPathStr(const PString & pathStr);
273
275 const PStringArray & GetPath() const { return path; }
276
278 void SetPath(const PStringArray & path);
279
281 void AppendPath(const PString & segment);
282
284 void ChangePath(
285 const PString & segment,
286 PINDEX idx = P_MAX_INDEX
287 );
288
290 PString GetParameters() const;
291
293 void SetParameters(const PString & parameters);
294
297 const PStringOptions & GetParamVars() const { return paramVars; }
298
301 void SetParamVars(const PStringToString & paramVars);
302
305 void SetParamVar(
306 const PString & key,
307 const PString & data,
308 bool emptyDataDeletes = true
309 );
310
312 const PString & GetFragment() const { return fragment; }
313
315 PString GetQuery() const;
316
319 void SetQuery(const PString & query);
320
323 const PStringOptions & GetQueryVars() const { return queryVars; }
324
327 void SetQueryVars(const PStringToString & queryVars);
328
331 void SetQueryVar(const PString & key, const PString & data);
332
334 const PString & GetContents() const { return m_contents; }
335
337 void SetContents(const PString & str);
338
340 PBoolean IsEmpty() const { return urlString.IsEmpty(); }
341
342
343 struct LoadParams {
344 LoadParams(
345 const PString & requiredContentType = PString::Empty(),
346 const PTimeInterval & timeout = PMaxTimeInterval
347 ) : m_requiredContentType(requiredContentType)
348 , m_timeout(timeout)
349 {
350 }
351
352 PString m_requiredContentType;
353 PTimeInterval m_timeout;
354
355 PString m_username; // Basic authentication
356 PString m_password;
357 #if P_SSL
358 PString m_authority; // Directory, file or data
359 PString m_certificate; // File or data
360 PString m_privateKey; // File or data
361 #endif
362 };
367 bool LoadResource(
368 PString & data,
369 const LoadParams & params = LoadParams()
370 ) const;
371 bool LoadResource(
372 PBYTEArray & data,
373 const LoadParams & params = LoadParams()
374 ) const;
375
376 // For backward compatibility
377 template <class T>
378 bool LoadResource(
379 T & data,
380 const PString & requiredContentType = PString::Empty(),
381 const PTimeInterval & timeout = PMaxTimeInterval
382 ) const { return LoadResource(data, LoadParams(requiredContentType, timeout)); }
383
390 bool OpenBrowser() const { return OpenBrowser(AsString()); }
391 static bool OpenBrowser(
392 const PString & url
393 );
395
396 bool LegacyParse(const char * str, const PURLLegacyScheme * schemeInfo);
397 PString LegacyAsString(PURL::UrlFormat fmt, const PURLLegacyScheme * schemeInfo) const;
398
399 protected:
400 void CopyContents(const PURL & other);
401 virtual PBoolean InternalParse(
402 const char * cstr,
403 const char * defaultScheme
404 );
405 void Recalculate();
406
407 const PURLScheme * schemeInfo;
408 PString urlString;
409
410 PCaselessString scheme;
411 PString username;
412 PString password;
413 PCaselessString hostname;
414 WORD port;
415 bool portSupplied;
416 bool relativePath;
417 PStringArray path;
418 PStringOptions paramVars;
419 PString fragment;
420 PStringOptions queryVars;
421 PString m_contents; // Anything left after parsing other elements
422 };
423
424
426 // PURLScheme
427
428 class PURLScheme : public PObject
429 {
430 PCLASSINFO(PURLScheme, PObject);
431 public:
432 virtual bool Parse(const char * cstr, PURL & url) const = 0;
433 virtual PString AsString(PURL::UrlFormat fmt, const PURL & purl) const = 0;
434 virtual WORD GetDefaultPort() const { return 0; }
435 };
436
437 typedef PFactory<PURLScheme> PURLSchemeFactory;
438
439
441 // PURLLegacyScheme
442
443 class PURLLegacyScheme : public PURLScheme
444 {
445 public:
446 PURLLegacyScheme(
447 bool user = false,
448 bool pass = false,
449 bool host = false,
450 bool def = false,
451 bool defhost = false,
452 bool query = false,
453 bool params = false,
454 bool frags = false,
455 bool path = false,
456 bool rel = false,
457 WORD port = 0
458 )
459 : hasUsername (user)
460 , hasPassword (pass)
461 , hasHostPort (host)
462 , defaultToUserIfNoAt (def)
463 , defaultHostToLocal (defhost)
464 , hasQuery (query)
465 , hasParameters (params)
466 , hasFragments (frags)
467 , hasPath (path)
468 , relativeImpliesScheme (rel)
469 , defaultPort (port)
470 { }
471
472 bool Parse(const char * cstr, PURL & url) const
473 {
474 return url.LegacyParse(cstr, this);
475 }
476
477 PString AsString(PURL::UrlFormat fmt, const PURL & url) const
478 {
479 return url.LegacyAsString(fmt, this);
480 }
481
482 virtual WORD GetDefaultPort() const { return defaultPort; }
483
484 bool hasUsername;
485 bool hasPassword;
486 bool hasHostPort;
487 bool defaultToUserIfNoAt;
488 bool defaultHostToLocal;
489 bool hasQuery;
490 bool hasParameters;
491 bool hasFragments;
492 bool hasPath;
493 bool relativeImpliesScheme;
494 WORD defaultPort;
495 };
496
503 #define PURL_LEGACY_SCHEME(schemeName, \
504 hasUsername, /* URL scheme has a ysername */ \
505 hasPassword, /* URL scheme has a password */ \
506 hasHostPort, /* URL scheme has a host:port */ \
507 defaultToUserIfNoAt, /* URL scheme is username if no @, otherwise host:port */ \
508 defaultHostToLocal, /* URL scheme defaults to PIPSocket::GetHostName() if not present */ \
509 hasQuery, /* URL scheme has a query secton */ \
510 hasParameters, /* URL scheme has a parameter section */ \
511 hasFragments, /* URL scheme has a fragment section */ \
512 hasPath, /* URL scheme has a path */ \
513 relativeImpliesScheme, /* URL scheme has relative path (no //) then scheme: is not output */ \
514 defaultPort) /* URL scheme default port if not specified in host:port */ \
515 class PURLLegacyScheme_##schemeName : public PURLLegacyScheme \
516 { \
517 public: \
518 PURLLegacyScheme_##schemeName() \
519 : PURLLegacyScheme(hasUsername, \
520 hasPassword, \
521 hasHostPort, \
522 defaultToUserIfNoAt, \
523 defaultHostToLocal, \
524 hasQuery, \
525 hasParameters, \
526 hasFragments, \
527 hasPath, \
528 relativeImpliesScheme, \
529 defaultPort) \
530 { } \
531 }; \
532 static PURLSchemeFactory::Worker<PURLLegacyScheme_##schemeName> schemeName##Factory(#schemeName, true); \
533
534
535
537 // PURLLoader
538
539 class PURLLoader : public PObject
540 {
541 PCLASSINFO(PURLLoader, PObject);
542 public:
543 virtual bool Load(PString & str, const PURL & url, const PURL::LoadParams & params) const = 0;
544 virtual bool Load(PBYTEArray & data, const PURL & url, const PURL::LoadParams & params) const = 0;
545 };
546
547 typedef PFactory<PURLLoader> PURLLoaderFactory;
548
549 #if P_HTTP
550 PFACTORY_LOAD(PURL_HttpLoader);
551 #endif // P_HTTP
552 #if P_FTP
553 PFACTORY_LOAD(PURL_FtpLoader);
554 #endif // P_HTTP
555
556
557 #endif // P_URL
558
559 #endif // PTLIB_PURL_H
560
561
562 // End Of File ///////////////////////////////////////////////////////////////