All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Member Functions | Static Public Member Functions | List of all members
BUrl Class Reference

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 BUrloperator= (const BString &string)
 Undocumented public method.
 
const BUrloperator= (const BUrl &other)
 Undocumented public method.
 
const BUrloperator= (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.
 
BUrlSetUrlString (const BString &url)
 Parse a string and set the URL accordingly.
 
BUrlSetProtocol (const BString &scheme)
 Set the protocol.
 
BUrlSetUserName (const BString &user)
 Set the username in the authority component.
 
BUrlSetPassword (const BString &password)
 Set the password in the authority component.
 
void SetAuthority (const BString &authority)
 Replace the complete authority component.
 
BUrlSetHost (const BString &host)
 Sets the host part of the authority component.
 
BUrlSetPort (int port)
 Set the port of the authority component.
 
BUrlSetPath (const BString &path)
 Set the path of the URL.
 
BUrlSetRequest (const BString &request)
 Set the request part of the URL.
 
BUrlSetFragment (const BString &fragment)
 Set the fragment part of the URL.
 
const BStringUrlString () const
 Returns the string representation of the URL.
 
const BStringProtocol () const
 Returns the protocol used in the url.
 
const BStringUserName () const
 Returns the username.
 
const BStringPassword () const
 Returns the password.
 
const BStringUserInfo () const
 Returns the user information (username:password)
 
const BStringHost () const
 Returns the URL host component.
 
int Port () const
 Returns the URL port number.
 
const BStringAuthority () const
 Returns the authority url as a string.
 
const BStringPath () const
 Returns the url path.
 
const BStringRequest () const
 Returns the url-request.
 
const BStringFragment () 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 BArchivableInstantiate (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 BArchivableInstantiate (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
urlA 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
archiveAn 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
otherA 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
baseA BUrl object that holds base URL.
relativeA 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
pathThe 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
intoThe message you store your object in.
deepIf true, all children of this object should be archived as well.
Return values
B_OKThe archive operation was successful.
B_BAD_VALUENULL archive message.
B_ERRORThe 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
archiveUndocumented
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
onProblemAskUserUndocumented
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
otherUndocumented
Returns
Undocumented
Return values
<value>Undocumented
Since
Haiku R1

◆ operator=() [1/3]

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

Undocumented public method.

Parameters
stringUndocumented
Returns
Undocumented
Return values
<value>Undocumented
Since
Haiku R1

◆ operator=() [2/3]

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

Undocumented public method.

Parameters
otherUndocumented
Returns
Undocumented
Return values
<value>Undocumented
Since
Haiku R1

◆ operator=() [3/3]

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

Undocumented public method.

Parameters
stringUndocumented
Returns
Undocumented
Return values
<value>Undocumented
Since
Haiku R1

◆ operator==()

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

Undocumented public method.

Parameters
otherUndocumented
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
authorityThe 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
fragmentThe fragment to use.

◆ SetHost()

BUrl & BUrl::SetHost ( const BString host)

Sets the host part of the authority component.

Parameters
hostThe hostname or address to use.

◆ SetPassword()

BUrl & BUrl::SetPassword ( const BString password)

Set the password in the authority component.

Parameters
passwordThe password.

◆ SetPath()

BUrl & BUrl::SetPath ( const BString path)

Set the path of the URL.

Parameters
pathSet the path to use.

◆ SetPort()

BUrl & BUrl::SetPort ( int  port)

Set the port of the authority component.

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

◆ SetProtocol()

BUrl & BUrl::SetProtocol ( const BString scheme)

Set the protocol.

Parameters
schemeThe protocol to use.

◆ SetRequest()

BUrl & BUrl::SetRequest ( const BString request)

Set the request part of the URL.

Parameters
requestThe request string.

◆ SetUrlString()

BUrl & BUrl::SetUrlString ( const BString url)

Parse a string and set the URL accordingly.

Parameters
urlA string to parse as an absolute URL.

◆ SetUserName()

BUrl & BUrl::SetUserName ( const BString user)

Set the username in the authority component.

Parameters
userThe username.

◆ UrlDecode() [1/2]

void BUrl::UrlDecode ( bool  strict = false)

Undocumented public method.

Parameters
strictUndocumented
Since
Haiku R1

◆ UrlDecode() [2/2]

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

Undocumented public method.

Parameters
urlUndocumented
strictUndocumented
Returns
Undocumented
Return values
<value>Undocumented
Since
Haiku R1

◆ UrlEncode() [1/2]

void BUrl::UrlEncode ( bool  strict = false)

Undocumented public method.

Parameters
strictUndocumented
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
urlUndocumented
strictUndocumented
directoryUndocumented
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.