Represents and manipulates an URL (Uniform Resource Locator). More...

Inherits BArchivable.

Public Member Functions
virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive the object into a BMessage.

bool	HasPreferredApplication () const
	Undocumented public method.

status_t	IDNAToAscii ()
	Undocumented public method.

status_t	IDNAToUnicode ()
	Undocumented public method.

status_t	OpenWithPreferredApplication (bool onProblemAskUser=true) const
	Undocumented public method.

	operator const char * () const
	Undocumented public method.

bool	operator!= (BUrl &other) const
	Undocumented public method.

const BUrl &	operator= (const BString &string)
	Undocumented public method.

const BUrl &	operator= (const BUrl &other)
	Undocumented public method.

const BUrl &	operator= (const char *string)
	Undocumented public method.

bool	operator== (BUrl &other) const
	Undocumented public method.

BString	PreferredApplication () const
	Undocumented public method.

void	UrlDecode (bool strict=false)
	Undocumented public method.

void	UrlEncode (bool strict=false)
	Undocumented public method.


	BUrl (const char *url)
	Constructs a BUrl and fills it.

	BUrl (BMessage *archive)
	Restore an URL from archived data.

	BUrl (const BUrl &other)
	Copy constructor.

	BUrl (const BUrl &base, const BString &relative)
	Construct a BUrl using a known base and a string representing a relative URL.

	BUrl (const BPath &path)
	Constructs a BUrl identifying a local file.

	BUrl ()
	Constructs an empty BUrl.

virtual	~BUrl ()
	Destructor for BUrl.


BUrl &	SetUrlString (const BString &url)
	Parse a string and set the URL accordingly.

BUrl &	SetProtocol (const BString &scheme)
	Set the protocol.

BUrl &	SetUserName (const BString &user)
	Set the username in the authority component.

BUrl &	SetPassword (const BString &password)
	Set the password in the authority component.

void	SetAuthority (const BString &authority)
	Replace the complete authority component.

BUrl &	SetHost (const BString &host)
	Sets the host part of the authority component.

BUrl &	SetPort (int port)
	Set the port of the authority component.

BUrl &	SetPath (const BString &path)
	Set the path of the URL.

BUrl &	SetRequest (const BString &request)
	Set the request part of the URL.

BUrl &	SetFragment (const BString &fragment)
	Set the fragment part of the URL.


const BString &	UrlString () const
	Returns the string representation of the URL.

const BString &	Protocol () const
	Returns the protocol used in the url.

const BString &	UserName () const
	Returns the username.

const BString &	Password () const
	Returns the password.

const BString &	UserInfo () const
	Returns the user information (username:password)

const BString &	Host () const
	Returns the URL host component.

int	Port () const
	Returns the URL port number.

const BString &	Authority () const
	Returns the authority url as a string.

const BString &	Path () const
	Returns the url path.

const BString &	Request () const
	Returns the url-request.

const BString &	Fragment () const
	Returns the fragment of the url.


bool	IsValid () const
	Check if the URL is valid.

bool	HasProtocol () const
	Check wether the URL has a protocol.

bool	HasUserName () const
	Check wether the URL has an username.

bool	HasPassword () const
	Check wether the URL has a password.

bool	HasUserInfo () const
	Check wether the URL has user information.

bool	HasHost () const
	Check wether the URL has an host.

bool	HasPort () const
	Check wether the URL has a port.

bool	HasAuthority () const
	Check if the URL has an host or port.

bool	HasPath () const
	Check wether the URL has a path.

bool	HasRequest () const
	Check wether the URL has a request.

bool	HasFragment () const
	Check wether the URL has a fragment.

Public Member Functions inherited from BArchivable
	BArchivable ()
	Constructor. Does nothing.

	BArchivable (BMessage *from)
	Constructor. Does important behind-the-scenes work in the unarchiving process.

virtual	~BArchivable ()
	Destructor. Does nothing.

virtual status_t	AllArchived (BMessage *archive) const
	Method relating to the use of `BArchiver`.

virtual status_t	AllUnarchived (const BMessage *archive)
	Method relating to the use of `BUnarchiver`.

virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive the object into a BMessage.

virtual status_t	Perform (perform_code d, void *arg)
	Perform some action (Internal method defined for binary compatibility purposes).

Static Public Member Functions
static BArchivable *	Instantiate (BMessage *archive)
	Undocumented public method.

static BString	UrlDecode (const BString &url, bool strict=false)
	Undocumented public method.

static BString	UrlEncode (const BString &url, bool strict=false, bool directory=false)
	Undocumented public method.

Static Public Member Functions inherited from BArchivable
static BArchivable *	Instantiate (BMessage *archive)
	Static member to restore objects from messages.

Detailed Description

Represents and manipulates an URL (Uniform Resource Locator).

Since: Haiku R1

An "Uniform Resource Locator" identifies a place where a resource can be found. It specifies both a location and a mechanism to retrieve the data. For example, http://www.example.com/index.html indicates a protocol (http), a hostname (www.example.com), and a file name (index.html).

Every URL consists of a sequence of up to five components: protocol, authority (consisting of login and password, hostname and port) path, request and fragment.

The format is provided in RFC3986 (URI generic syntax), Appendix B as a regular expression: ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?

This regular expression makes it possible to parse any string as an URL (if there are no special characters to spearate the fields, everything will end up in the path compopent). However, some characters are not allowed: space, newlines, tabs, <, > and ". If any of these is present in the URL string, the parsing results in an empty URL.

The protocols (http, https, ftp, irc, etc) identifies which way the resource can be accessed.

Authority consists of userinfo such as username and password, a host subcomponent consisting of IP address or hostname and a port subcomponent.

The path component locates the resource inside the authority's hierarchy, and can have different formats (for example, directory names separated by slashes) depending on the protocol in use.

The request component (preceeded by a question mark) contains a query string of non-hierarchial data.

The fragment contains a fragment identifier providing direction to a secondary resource, usually an identifier for a specific element into the resource such as a paragraph in a text.

Constructor & Destructor Documentation

◆ BUrl() [1/5]

BUrl::BUrl ( const char * url )

Constructs a BUrl and fills it.

Parameters

url	A string to parse and populate the URL fields from.

Call InitCheck() to verify that the string was succesfully parsed and resulted in a valid URL.

◆ BUrl() [2/5]

BUrl::BUrl ( BMessage * archive )

Restore an URL from archived data.

Parameters

archive An archived BUrl (using BArchive()).

Usually, archived messages are restored using BArchivable::Unarchive() which will automatically instanciate the correct class.

◆ BUrl() [3/5]

BUrl::BUrl ( const BUrl & other )

Copy constructor.

Parameters

other A BUrl object to copy.

◆ BUrl() [4/5]

BUrl::BUrl	(	const BUrl &	base,
		const BString &	relative
	)

Construct a BUrl using a known base and a string representing a relative URL.

Parameters

base	A BUrl object that holds base URL.
relative	A path relative to the base URL.

URLs can sometimes be represented in relative form. For example, links in a webpage may refer to only a path, assuming the same protocol and authority are the same as the current page. This constructor applies the required resolution process to construct a complete, standalone URL from such a string.

For example, the following:

BUrl base("http://example.org/path/page.html"); BUrl relative(base, "sudirectory/otherpage.html");

results in:

"http://example.org/path/subdirectory/otherpage.hhtml"

The relative URL can override any of the fields from the original one. The algorithm for resolution is documented in RFC3986 section 5.

◆ BUrl() [5/5]

BUrl::BUrl ( const BPath & path )

Constructs a BUrl identifying a local file.

Parameters

path	The path to convert into an URL

The generated URL uses the file protocol, and its path component is the path given as a parameter.

Member Function Documentation

◆ Archive()

virtual status_t BUrl::Archive	(	BMessage *	into,
		bool	deep = `true`
	)		const

virtual

Archive the object into a BMessage.

You should call this method from your derived implementation as it adds the data needed to instantiate your object to the message.

Parameters

into	The message you store your object in.
deep	If `true`, all children of this object should be archived as well.

Return values

B_OK	The archive operation was successful.
B_BAD_VALUE	`NULL` archive message.
B_ERROR	The archive operation failed.

Since: BeOS R3

Reimplemented from BArchivable.

◆ Authority()

const BString & BUrl::Authority ( ) const

Returns the authority url as a string.

Returns: The authority url as a string.

The authority is of the form username:password@host:port.

◆ Fragment()

const BString & BUrl::Fragment ( ) const

Returns the fragment of the url.

Returns: The fragment of the url as a string.

◆ HasAuthority()

bool BUrl::HasAuthority ( ) const

Check if the URL has an host or port.

Returns: True if the URL has an host or port.

◆ HasFragment()

bool BUrl::HasFragment ( ) const

Check wether the URL has a fragment.

Returns: True if the URL has a fragment.

◆ HasHost()

bool BUrl::HasHost ( ) const

Check wether the URL has an host.

Returns: True if the URL has an host.

◆ HasPassword()

bool BUrl::HasPassword ( ) const

Check wether the URL has a password.

Returns: True if the URL has a password.

◆ HasPath()

bool BUrl::HasPath ( ) const

Check wether the URL has a path.

Returns: True if the URL has a path.

◆ HasPort()

bool BUrl::HasPort ( ) const

Check wether the URL has a port.

Returns: True if the URL has a port.

◆ HasPreferredApplication()

bool BUrl::HasPreferredApplication ( ) const

Undocumented public method.

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ HasProtocol()

bool BUrl::HasProtocol ( ) const

Check wether the URL has a protocol.

Returns: True if the URL has a protocol.

◆ HasRequest()

bool BUrl::HasRequest ( ) const

Check wether the URL has a request.

Returns: True if the URL has a request.

◆ HasUserInfo()

bool BUrl::HasUserInfo ( ) const

Check wether the URL has user information.

Returns: True if the URL has an username or password.

◆ HasUserName()

bool BUrl::HasUserName ( ) const

Check wether the URL has an username.

Returns: True if the URL has an username.

◆ Host()

const BString & BUrl::Host ( ) const

Returns the URL host component.

Returns: The URL host.

◆ IDNAToAscii()

status_t BUrl::IDNAToAscii ( )

Undocumented public method.

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ IDNAToUnicode()

status_t BUrl::IDNAToUnicode ( )

Undocumented public method.

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ Instantiate()

static static BArchivable * BUrl::Instantiate ( BMessage * archive )

static

Undocumented public method.

Parameters

archive Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ IsValid()

bool BUrl::IsValid ( ) const

Check if the URL is valid.

Returns: true if the URL is valid.

This function verifies that the mandatory fields are present and perform some other sanity checks on the URL.

An URL is valid if:

It has a protocol, starting with an alphabetic character and folowed by alphanumeric or +, -, or . characters exclusively,
If the protocol requires one, there is a valid host,
If the protocol requires one, there is a path.
If there is a host, it is either an IPv4 address or valid DNS name, or an IPv6 address enclosed in brackets

An invalid URL can still be modified using the various setters to turn it into a valid one.

◆ OpenWithPreferredApplication()

status_t BUrl::OpenWithPreferredApplication ( bool onProblemAskUser = true ) const

Undocumented public method.

Parameters

onProblemAskUser Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ operator const char *()

BUrl::operator const char * ( ) const

Undocumented public method.

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ operator!=()

bool BUrl::operator!= ( BUrl & other ) const

Undocumented public method.

Parameters

other Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ operator=() [1/3]

const BUrl & BUrl::operator= ( const BString & string )

Undocumented public method.

Parameters

string Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ operator=() [2/3]

const BUrl & BUrl::operator= ( const BUrl & other )

Undocumented public method.

Parameters

other Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ operator=() [3/3]

const BUrl & BUrl::operator= ( const char * string )

Undocumented public method.

Parameters

string Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ operator==()

bool BUrl::operator== ( BUrl & other ) const

Undocumented public method.

Parameters

other Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ Password()

const BString & BUrl::Password ( ) const

Returns the password.

Returns: The password.

◆ Path()

const BString & BUrl::Path ( ) const

Returns the url path.

Returns: The url-path.

◆ Port()

int BUrl::Port ( ) const

Returns the URL port number.

Returns: The URL port number.

-1 is returned if no port is set.

◆ PreferredApplication()

BString BUrl::PreferredApplication ( ) const

Undocumented public method.

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ Protocol()

const BString & BUrl::Protocol ( ) const

Returns the protocol used in the url.

Returns: The URL protocol.

◆ Request()

const BString & BUrl::Request ( ) const

Returns the url-request.

Returns: The url-request as a string.

◆ SetAuthority()

void BUrl::SetAuthority ( const BString & authority )

Replace the complete authority component.

Parameters

authority The authority component.

The username, password, host and port fields are replaced. The authority can be of the form username:password@host:port

◆ SetFragment()

BUrl & BUrl::SetFragment ( const BString & fragment )

Set the fragment part of the URL.

Parameters

fragment The fragment to use.

◆ SetHost()

BUrl & BUrl::SetHost ( const BString & host )

Sets the host part of the authority component.

Parameters

host	The hostname or address to use.

◆ SetPassword()

BUrl & BUrl::SetPassword ( const BString & password )

Set the password in the authority component.

Parameters

password The password.

◆ SetPath()

BUrl & BUrl::SetPath ( const BString & path )

Set the path of the URL.

Parameters

path	Set the path to use.

◆ SetPort()

BUrl & BUrl::SetPort ( int port )

Set the port of the authority component.

Parameters

port	The port number to use (usually a TCP or UDP port).

◆ SetProtocol()

BUrl & BUrl::SetProtocol ( const BString & scheme )

Set the protocol.

Parameters

scheme The protocol to use.

◆ SetRequest()

BUrl & BUrl::SetRequest ( const BString & request )

Set the request part of the URL.

Parameters

request The request string.

◆ SetUrlString()

BUrl & BUrl::SetUrlString ( const BString & url )

Parse a string and set the URL accordingly.

Parameters

url	A string to parse as an absolute URL.

◆ SetUserName()

BUrl & BUrl::SetUserName ( const BString & user )

Set the username in the authority component.

Parameters

user	The username.

◆ UrlDecode() [1/2]

void BUrl::UrlDecode ( bool strict = false )

Undocumented public method.

Parameters

strict Undocumented

Since: Haiku R1

◆ UrlDecode() [2/2]

static static BString BUrl::UrlDecode	(	const BString &	url,
		bool	strict = `false`
	)

static

Undocumented public method.

Parameters

url	Undocumented
strict	Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ UrlEncode() [1/2]

void BUrl::UrlEncode ( bool strict = false )

Undocumented public method.

Parameters

strict Undocumented

Since: Haiku R1

◆ UrlEncode() [2/2]

static static BString BUrl::UrlEncode	(	const BString &	url,
		bool	strict = `false`,
		bool	directory = `false`
	)

static

Undocumented public method.

Parameters

url	Undocumented
strict	Undocumented
directory	Undocumented

Returns: Undocumented

Return values

<value> Undocumented

Since: Haiku R1

◆ UrlString()

const BString & BUrl::UrlString ( ) const

Returns the string representation of the URL.

Returns: the string representation of the URL.

A complete URL string is of the form protocol://username:passord@host:port/path?request::fragment . All the fields are optional, for example a file URL will have only a protocol and a path.

◆ UserInfo()

const BString & BUrl::UserInfo ( ) const

Returns the user information (username:password)

Returns: The username and password.

If there is no password, the username alone is returned. If there is no username, a string of the form ":password" is returned.

◆ UserName()

const BString & BUrl::UserName ( ) const

Returns the username.

Returns: The username.

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BUrl() [1/5]

◆ BUrl() [2/5]

◆ BUrl() [3/5]

◆ BUrl() [4/5]

◆ BUrl() [5/5]

Member Function Documentation

◆ Archive()

◆ Authority()

◆ Fragment()

◆ HasAuthority()

◆ HasFragment()

◆ HasHost()

◆ HasPassword()

◆ HasPath()

◆ HasPort()

◆ HasPreferredApplication()

◆ HasProtocol()

◆ HasRequest()

◆ HasUserInfo()

◆ HasUserName()

◆ Host()

◆ IDNAToAscii()

◆ IDNAToUnicode()

◆ Instantiate()

◆ IsValid()

◆ OpenWithPreferredApplication()

◆ operator const char *()

◆ operator!=()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator==()

◆ Password()

◆ Path()

◆ Port()

◆ PreferredApplication()

◆ Protocol()

◆ Request()

◆ SetAuthority()

◆ SetFragment()

◆ SetHost()

◆ SetPassword()

◆ SetPath()

◆ SetPort()

◆ SetProtocol()

◆ SetRequest()

◆ SetUrlString()

◆ SetUserName()

◆ UrlDecode() [1/2]

◆ UrlDecode() [2/2]

◆ UrlEncode() [1/2]

◆ UrlEncode() [2/2]

◆ UrlString()

◆ UserInfo()

◆ UserName()