Arc::URL Class Reference

Class to hold general URLs. More...

#include <URL.h>

Inheritance diagram for Arc::URL:

Public Types
enum	Scope
Public Member Functions
	URL ()
	URL (const std::string &url)
virtual	~URL ()
const std::string &	Protocol () const
void	ChangeProtocol (const std::string &newprot)
bool	IsSecureProtocol () const
const std::string &	Username () const
const std::string &	Passwd () const
const std::string &	Host () const
void	ChangeHost (const std::string &newhost)
int	Port () const
void	ChangePort (int newport)
const std::string &	Path () const
std::string	FullPath () const
std::string	FullPathURIEncoded () const
void	ChangePath (const std::string &newpath)
void	ChangeFullPath (const std::string &newpath)
const std::map< std::string, std::string > &	HTTPOptions () const
const std::string &	HTTPOption (const std::string &option, const std::string &undefined="") const
bool	AddHTTPOption (const std::string &option, const std::string &value, bool overwrite=true)
void	RemoveHTTPOption (const std::string &option)
const std::list< std::string > &	LDAPAttributes () const
void	AddLDAPAttribute (const std::string &attribute)
Scope	LDAPScope () const
void	ChangeLDAPScope (const Scope newscope)
const std::string &	LDAPFilter () const
void	ChangeLDAPFilter (const std::string &newfilter)
const std::map< std::string, std::string > &	Options () const
const std::string &	Option (const std::string &option, const std::string &undefined="") const
const std::map< std::string, std::string > &	MetaDataOptions () const
const std::string &	MetaDataOption (const std::string &option, const std::string &undefined="") const
bool	AddOption (const std::string &option, const std::string &value, bool overwrite=true)
bool	AddOption (const std::string &option, bool overwrite=true)
void	AddMetaDataOption (const std::string &option, const std::string &value, bool overwrite=true)
void	AddLocation (const URLLocation &location)
const std::list< URLLocation > &	Locations () const
const std::map< std::string, std::string > &	CommonLocOptions () const
const std::string &	CommonLocOption (const std::string &option, const std::string &undefined="") const
void	RemoveOption (const std::string &option)
void	RemoveMetaDataOption (const std::string &option)
virtual std::string	str () const
virtual std::string	plainstr () const
virtual std::string	fullstr () const
virtual std::string	ConnectionURL () const
bool	operator< (const URL &url) const
bool	operator== (const URL &url) const
	operator bool () const
bool	StringMatches (const std::string &str) const
std::map< std::string, std::string >	ParseOptions (const std::string &optstring, char separator)
Static Public Member Functions
static std::string	OptionString (const std::map< std::string, std::string > &options, char separator)
Protected Member Functions
void	ParsePath (void)
Static Protected Member Functions
static std::string	BaseDN2Path (const std::string &)
static std::string	Path2BaseDN (const std::string &)
Protected Attributes
std::string	protocol
std::string	username
std::string	passwd
std::string	host
bool	ip6addr
int	port
std::string	path
std::map< std::string, std::string >	httpoptions
std::map< std::string, std::string >	metadataoptions
std::list< std::string >	ldapattributes
Scope	ldapscope
std::string	ldapfilter
std::map< std::string, std::string >	urloptions
std::list< URLLocation >	locations
std::map< std::string, std::string >	commonlocoptions
bool	valid
Friends
std::ostream &	operator<< (std::ostream &out, const URL &u)

---

Detailed Description

Class to hold general URLs.

The URL is split into protocol, hostname, port and path. This class tries to follow RFC 3986 for spliting URLs, at least for protocol + host part. It also accepts local file paths which are converted to file:path. The usual system dependent file paths are supported. Relative paths are converted to absolute paths by prepending them with current working directory path. A file path can't start from # symbol. If the string representation of URL starts from '@' then it is treated as path to a file containing a list of URLs.

A URL is parsed in the following way:

[protocol:][//[username:passwd@][host][:port]][;urloptions[;...]][/path[?httpoption[&...]][:metadataoption[:...]]]

The 'protocol' and 'host' parts are treated as case-insensitive and to avoid confusion are converted to lowercase in constructor. Note that 'path' is always converted to absolute path in constructor. The meaning of 'absolute' may depend upon URL type. For generic URL and local POSIX file paths that means path starts from / like

/path/to/file

For Windows paths absolute path may look like

C:\path\to\file

It is important to note that path still can be empty. For referencing local file using absolute path on POSIX filesystem one may use either

file:///path/to/file or file:/path/to/file

Relative path will look like

file:to/file

For local Windows files possible URLs are

file:C:\path\to\file or file:to\file

URLs representing LDAP resources have different structure of options following 'path' part:

ldap://host[:port][;urloptions[;...]][/path[?attributes[?scope[?filter]]]]

For LDAP URLs paths are converted from /key1=value1/.../keyN=valueN notation to keyN=valueN,...,key1=value1 and hence path does not contain leading /. If LDAP URL initially had path in second notation leading / is treated as separator only and is stripped.

URLs of indexing services optionally may have locations specified before 'host' part

protocol://[location[;location[;...]]@][host][:port]...

The structure of 'location' element is protocol specific.

---

Member Enumeration Documentation

enum Arc::URL::Scope

Scope for LDAP URLs

---

Constructor & Destructor Documentation

Arc::URL::URL

(

)

Empty constructor. Necessary when the class is part of another class and the like.

Arc::URL::URL

(

const std::string &

url

)

Constructs a new URL from a string representation.

virtual Arc::URL::~URL

(

)

[virtual]

URL Destructor

---

Member Function Documentation

bool Arc::URL::AddHTTPOption	(	const std::string &	option,
		const std::string &	value,
		bool	overwrite = true
	)

Adds a HTP option with the given value. Returns false if overwrite is false and option already exists, true otherwise.

void Arc::URL::AddLDAPAttribute

(

const std::string &

attribute

)

Adds an LDAP attribute.

void Arc::URL::AddLocation

(

const URLLocation &

location

)

Adds a Location

void Arc::URL::AddMetaDataOption	(	const std::string &	option,
		const std::string &	value,
		bool	overwrite = true
	)

Adds a metadata option

bool Arc::URL::AddOption	(	const std::string &	option,
		bool	overwrite = true
	)

Adds a URL option where option has the format "name=value". Returns false if overwrite is true and option already exists or if option does not have the correct format. Returns true otherwise.

bool Arc::URL::AddOption	(	const std::string &	option,
		const std::string &	value,
		bool	overwrite = true
	)

Adds a URL option with the given value. Returns false if overwrite is false and option already exists, true otherwise. Note that some compilers may interpret AddOption("name", "value") as a call to AddOption(string, bool) so it is recommended to use explicit string types when calling this method.

static std::string Arc::URL::BaseDN2Path

(

const std::string &

)

[static, protected]

a private method that converts an ldap basedn to a path.

void Arc::URL::ChangeFullPath

(

const std::string &

newpath

)

Changes the path of the URL and all options attached.

void Arc::URL::ChangeHost

(

const std::string &

newhost

)

Changes the hostname of the URL.

void Arc::URL::ChangeLDAPFilter

(

const std::string &

newfilter

)

Changes the LDAP filter.

void Arc::URL::ChangeLDAPScope

(

const Scope

newscope

)

Changes the LDAP scope.

void Arc::URL::ChangePath

(

const std::string &

newpath

)

Changes the path of the URL.

void Arc::URL::ChangePort

(

int

newport

)

Changes the port of the URL.

void Arc::URL::ChangeProtocol

(

const std::string &

newprot

)

Changes the protocol of the URL.

const std::string& Arc::URL::CommonLocOption	(	const std::string &	option,
		const std::string &	undefined = ""
	)			const

Returns the value of a common location option.

Parameters:

	option	The option whose value is returned.
	undefined	This value is returned if the common location option is not defined.

const std::map<std::string, std::string>& Arc::URL::CommonLocOptions

(

)

const

Returns the common location options if any.

virtual std::string Arc::URL::ConnectionURL

(

)

const [virtual]

Returns a string representation with protocol, host and port only

std::string Arc::URL::FullPath

(

)

const

Returns the path of the URL with all options attached.

std::string Arc::URL::FullPathURIEncoded

(

)

const

Returns the path and all options, URI-encoded according to RFC 3986. Forward slashes ('/') in the path are not encoded but are encoded in the options.

virtual std::string Arc::URL::fullstr

(

)

const [virtual]

Returns a string representation including options and locations

Reimplemented in Arc::URLLocation.

const std::string& Arc::URL::Host

(

)

const

Returns the hostname of the URL.

const std::string& Arc::URL::HTTPOption	(	const std::string &	option,
		const std::string &	undefined = ""
	)			const

Returns the value of an HTTP option.

Parameters:

	option	The option whose value is returned.
	undefined	This value is returned if the HTTP option is not defined.

const std::map<std::string, std::string>& Arc::URL::HTTPOptions

(

)

const

Returns HTTP options if any.

bool Arc::URL::IsSecureProtocol

(

)

const

Indicates whether the protocol is secure or not.

const std::list<std::string>& Arc::URL::LDAPAttributes

(

)

const

Returns the LDAP attributes if any.

const std::string& Arc::URL::LDAPFilter

(

)

const

Returns the LDAP filter.

Scope Arc::URL::LDAPScope

(

)

const

Returns the LDAP scope.

const std::list<URLLocation>& Arc::URL::Locations

(

)

const

Returns the locations if any.

const std::string& Arc::URL::MetaDataOption	(	const std::string &	option,
		const std::string &	undefined = ""
	)			const

Returns the value of a metadata option.

Parameters:

	option	The option whose value is returned.
	undefined	This value is returned if the metadata option is not defined.

const std::map<std::string, std::string>& Arc::URL::MetaDataOptions

(

)

const

Returns metadata options if any.

Arc::URL::operator bool

(

)

const

Check if instance holds valid URL

bool Arc::URL::operator<

(

const URL &

url

)

const

Compares one URL to another

bool Arc::URL::operator==

(

const URL &

url

)

const

Is one URL equal to another?

const std::string& Arc::URL::Option	(	const std::string &	option,
		const std::string &	undefined = ""
	)			const

Returns the value of a URL option.

Parameters:

	option	The option whose value is returned.
	undefined	This value is returned if the URL option is not defined.

const std::map<std::string, std::string>& Arc::URL::Options

(

)

const

Returns URL options if any.

static std::string Arc::URL::OptionString	(	const std::map< std::string, std::string > &	options,
		char	separator
	)			[static]

Returns a string representation of the options given in the options map

std::map<std::string, std::string> Arc::URL::ParseOptions	(	const std::string &	optstring,
		char	separator
	)

Parse a string of options separated by separator into an attribute->value map

void Arc::URL::ParsePath

(

void

)

[protected]

Convenience method for spliting schema specific part into path and options

const std::string& Arc::URL::Passwd

(

)

const

Returns the password of the URL.

const std::string& Arc::URL::Path

(

)

const

Returns the path of the URL.

static std::string Arc::URL::Path2BaseDN

(

const std::string &

)

[static, protected]

a private method that converts an ldap path to a basedn.

virtual std::string Arc::URL::plainstr

(

)

const [virtual]

Returns a string representation of the URL without any options

int Arc::URL::Port

(

)

const

Returns the port of the URL.

const std::string& Arc::URL::Protocol

(

)

const

Returns the protocol of the URL.

void Arc::URL::RemoveHTTPOption

(

const std::string &

option

)

Removes a HTTP option if exists.

Parameters:

option

The option to remove.

void Arc::URL::RemoveMetaDataOption

(

const std::string &

option

)

Remove a metadata option if exits.

Parameters:

option

The option to remove.

void Arc::URL::RemoveOption

(

const std::string &

option

)

Removes a URL option if exists.

Parameters:

option

The option to remove.

virtual std::string Arc::URL::str

(

)

const [virtual]

Returns a string representation of the URL including meta-options.

Reimplemented in Arc::URLLocation.

const std::string& Arc::URL::Username

(

)

const

Returns the username of the URL.

---

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	out,
		const URL &	u
	)			[friend]

Overloaded operator << to print a URL.

---

Field Documentation

std::map<std::string, std::string> Arc::URL::commonlocoptions [protected]

common location options for index server URLs.

std::string Arc::URL::host [protected]

hostname of the url.

std::map<std::string, std::string> Arc::URL::httpoptions [protected]

HTTP options of the url.

bool Arc::URL::ip6addr [protected]

if host is IPv6 numerical address notation.

std::list<std::string> Arc::URL::ldapattributes [protected]

LDAP attributes of the url.

std::string Arc::URL::ldapfilter [protected]

LDAP filter of the url.

Scope Arc::URL::ldapscope [protected]

LDAP scope of the url.

std::list<URLLocation> Arc::URL::locations [protected]

locations for index server URLs.

std::map<std::string, std::string> Arc::URL::metadataoptions [protected]

Meta data options

std::string Arc::URL::passwd [protected]

password of the url.

std::string Arc::URL::path [protected]

the url path.

int Arc::URL::port [protected]

portnumber of the url.

std::string Arc::URL::protocol [protected]

the url protocol.

std::map<std::string, std::string> Arc::URL::urloptions [protected]

options of the url.

std::string Arc::URL::username [protected]

username of the url.

bool Arc::URL::valid [protected]

flag to describe validity of URL

---

The documentation for this class was generated from the following file:

• URL.h