Cross-Platform C++

ot::net
class URL

#include "ot/net/URL.h"

Represents a Uniform Resource Locator (URL). This class provides the capability to parse, manipulate and compare URL strings in addition to making a URL's resource available as an InputStream.

The following example opens an InputStream to read from a URL:-

    try {
        const URL url(OT_T("http://www.elcel.com"));
        RefPtr<InputStream> rpIS = url.openStream();
        // wrap the InputStream with an InputStreamReader to convert the
        // byte stream into Unicode characters
        RefPtr<InputStreamReader> rpReader(new InputStreamReader(rpIS.get());
        CharType ch;
        while( (ch = rpReader->read()) != Reader::EndOfFile) {
            // do something
        }
    }
    catch(Exception& e) {
        Console::cerr() << e.toString() << endl;
    }

The URL Format

A URL is a string representation of a resource that is available via the Internet. The format of URLs is formally defined in the IETF RFC 1738 which is available online at http://www.ietf.org/rfc/rfc1738.txt (which is itself a URL!)

The URL syntax is dependent upon the scheme. In general, absolute URL are written as follows:

<scheme>:<scheme-specific-part>

A URL contains the name of the scheme being used (<scheme>) followed by a colon and then a string (the <scheme-specific-part>) whose interpretation depends on the scheme.

The URL syntax does not require that the scheme-specific-part is common among all URL, however, many forms of URL do share a common syntax for representing hierarchical relationships. This "generic URL" syntax consists of a sequence of four main components:

<scheme>://<authority><path>?<query>

The scheme is often the name of a network protocol which can be used to retrieve the resource from the Internet. The words protocol and scheme are used interchangeably within this document.

The authority is comprised of three sub-components:

<userInfo@><host><:port>

The path is comprised of everything following the authority up to the query part. In contrast to the description in RFC 1738, this class includes the "/" separator between the authority part and the path as part of the path.

OpenTop supports URLs for the following schemes: file, http and ftp. However, it is possible to extend this by creating a custom URLStreamHandlerFactory.

URL strings can be either absolute or relative. A relative URL (described in RFC 1808)) is interpreted within the context of another absolute URL. For example, the URL:

rfc1808.txt

is a valid example of a relative URL, but it is meaningless unless it is resolved within the context of an absolute URL such as:

http://www.ietf.org/rfc/rfc1738.txt

In the above case, the relative URL resolves by replacing the filename from the context URL with rfc1808.txt.

The URL class represents an absolute URL. Constructors are available that facilitate the creation of an absolute URL from a relative URL, interpreted within the context of another absolute URL.




Constructor/Destructor Summary
URL()
         Default constructor..
URL(const String& spec)
         Constructs a URL by parsing the string spec.
URL(const URL& context, const String& spec)
         Constructs a URL by parsing the string spec within the context of an existing URL context.
URL(const String& protocol, const String& host, const String& file)
         Constructs a URL with the components set from the parameters provided.
URL(const String& protocol, const String& host, int port, const String& file)
         Constructs a URL with the components set from the parameters provided.
URL(const String& protocol, const String& host, int port, const String& file, URLStreamHandler* pHandler)
         Constructs a URL with the components set from the parameters provided.

Method Summary
 bool equals(const URL& rhs) const
         Compares this URL with rhs.
 const String& getAuthority() const
         Returns the authority part of the URL.
 String getFile() const
         Returns the file name for this URL.
 const String& getHost() const
         Returns the host name part of the URL.
 String getPassword() const
         Returns the password identifier part of the UserInfo part of this URL.
 const String& getPath() const
         Returns the path for this URL.
 int getPort() const
         Returns the port number from the URL or -1 if no port number is present.
 const String& getProtocol() const
         Returns the protocol name (scheme part) of this URL.
 const String& getQuery() const
        
 const String& getRef() const
         Returns the reference part of this URL.
 RefPtr< URLStreamHandler > getStreamHandler() const
         Returns the URLStreamHandler associated with this URL, or null if no protocol or stream handler has been provided.
 String getUserID() const
         Returns the user identifier part of the UserInfo part of this URL.
 const String& getUserInfo() const
         Returns the UserInfo part of this URL.
 RefPtr< URLConnection > openConnection() const
         Returns a URLConnection which is suitable for the communication protocol designated by this URL.
 RefPtr< InputStream > openStream() const
         A convenience method that opens a connection to the network resource identified by this URL and returns an InputStream for the resource content.
 bool operator!=(const URL& rhs) const
        
 bool operator==(const URL& rhs) const
        
 bool sameFile(const URL& rhs) const
         Tests this URL against other to see if they refer to the same file.
 String toExternalForm() const
         Converts this URL into a String in URL format.

Constructor/Destructor Detail

URL

 URL()
Default constructor..


URL

 URL(const String& spec)
Constructs a URL by parsing the string spec.

Exceptions:
MalformedURLException - if spec does not contain a supported protocol.

URL

 URL(const URL& context,
     const String& spec)
Constructs a URL by parsing the string spec within the context of an existing URL context.

Parameters:
context - a URL which provides a context for the interpretation of the String spec
spec - a String containing either a relative or absolute URL
Exceptions:
MalformedURLException - if spec is absolute and contains a protocol which is not supported or if context does not contain a valid protocol.

URL

 URL(const String& protocol,
     const String& host,
     const String& file)
Constructs a URL with the components set from the parameters provided.

Parameters:
protocol - the protocol of the URL. This must be a supported protocol
host - the name or dotted IP address of the network host
file - the filename
Exceptions:
MalformedURLException - if protocol is not supported

URL

 URL(const String& protocol,
     const String& host,
     int port,
     const String& file)
Constructs a URL with the components set from the parameters provided.

Parameters:
protocol - the protocol of the URL. This must be a supported protocol
host - the name or dotted IP address of the network host
port - the port number of the remote server
file - the filename
Exceptions:
MalformedURLException - if protocol is not supported

URL

 URL(const String& protocol,
     const String& host,
     int port,
     const String& file,
     URLStreamHandler* pHandler)
Constructs a URL with the components set from the parameters provided.

Parameters:
protocol - the protocol of the URL. This must be a supported protocol
host - the name or dotted IP address of the network host
port - the port number of the remote server
file - the filename
pHandler - the URLStreamHandler that understands how to create a URLConnection for the given protocol
Exceptions:
MalformedURLException - if protocol is not supported and pHandler is null

Method Detail

equals

bool equals(const URL& rhs) const
Compares this URL with rhs. Two URLs are considered equal if they refer to the same network file, which is determined by calling sameFile(), and they both have the same reference.

Returns:
true if rhs refers to the same file and reference as this URL.
See also:
sameFile() , getRef()

getAuthority

const StringgetAuthority() const
Returns the authority part of the URL.


getFile

String getFile() const
Returns the file name for this URL. The file name consists of the path plus the query (if present).

For example, the file name for the following URL is '/search?q=xml'.

http://www.google.com/search?q=xml

See also:
getPath()

getHost

const StringgetHost() const
Returns the host name part of the URL. Not all URLs contain a host name, but those that do specify the host as part of the authority segment which is contained between the '//' and the following '/' or '?' characters.

The host name is a sub-string of the authority part, with user and port number information removed.

For example, the following URL's host is www.elcel.com :-

http://user:password@www.elcel.com:80/index.html

See also:
getAuthority() , getUserInfo() , getPort()

getPassword

String getPassword() const
Returns the password identifier part of the UserInfo part of this URL. This method assumes that UserInfo is structured like this:

<userid>:<password>


getPath

const StringgetPath() const
Returns the path for this URL. The path consists of the file name part of the URL without any query information.

For example, the path for the following URL is '/search'.

http://www.google.com/search?q=xml

See also:
getFile()

getPort

int getPort() const
Returns the port number from the URL or -1 if no port number is present. The port number is usually contained within the authority part of the URL and is separated from the host by a colon character.

For example, the following URL has a port number of 81:-

http://www.acme.org:81

See also:
getAuthority()

getProtocol

const StringgetProtocol() const
Returns the protocol name (scheme part) of this URL.


getQuery

const StringgetQuery() const


getRef

const StringgetRef() const
Returns the reference part of this URL. The reference contains all characters following the '#' (if any).


getStreamHandler

RefPtr< URLStreamHandlergetStreamHandler() const
Returns the URLStreamHandler associated with this URL, or null if no protocol or stream handler has been provided.


getUserID

String getUserID() const
Returns the user identifier part of the UserInfo part of this URL. This method assumes that UserInfo is structured like this:

<userid>:<password>


getUserInfo

const StringgetUserInfo() const
Returns the UserInfo part of this URL.

See also:
getUserID() , getPassword()

openConnection

RefPtr< URLConnectionopenConnection() const
Returns a URLConnection which is suitable for the communication protocol designated by this URL.


openStream

RefPtr< InputStreamopenStream() const
A convenience method that opens a connection to the network resource identified by this URL and returns an InputStream for the resource content. This is exactly the same as coding the following:-

   openConnection()->getInputStream()

Note that the URLConnection object is not accessible once the InputStream has been returned. If you require access to the URLConnection use the openConnection() method.

Returns:
an InputStream for reading the URL's resource.
Exceptions:
IOException - if an error occurs connecting to the resource
See also:
openConnection() , URLConnection::getInputStream()

operator!=

bool operator!=(const URL& rhs) const


operator==

bool operator==(const URL& rhs) const


sameFile

bool sameFile(const URL& rhs) const
Tests this URL against other to see if they refer to the same file. The test is delegated to the URLStreamHandler for this URL.


toExternalForm

String toExternalForm() const
Converts this URL into a String in URL format. This might be useful if you have constructed a URL programatically and now wish to output it to another process.



Cross-Platform C++

Found a bug or missing feature? Please email us at support@elcel.com

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements