Cross-Platform C++

ot::net
class URLConnection  (abstract)

#include "ot/net/URLConnection.h"

ot::ManagedObject ot::net::HttpURLConnection An abstract base class that represents a connection to a resource specified by a URL. Instances of URLConnection are created by classes derived from URLStreamHandler, which are themselves created by a URLStreamHandlerFactory.

When a URL is created, the protocol (or scheme) is used to request the URLStreamHandlerFactory for an instance of a URLStreamHandler that knows how to (a) parse URLs of for that protocol and (b) create instances of URLConnection that know how to connect to a resource using the protocol.

Many programs do not need to use a URLConnection directly, they can simply create a URL and ask it for an InputStream using getInputStream(). However, the URLConnection class gives the application greater control over how to connect to the resource and even allows the program to write to some types of resource via an OutputStream.

Programs that do need to deal with a URLConnection directly generally follow the following basic sequence:-

  1. Construct a URL object
  2. Obtain a URLConnection object by calling openConnection() on the URL
  3. Manipulate the URLConnection's parameters
  4. Connect to the remote resource by calling connect()
  5. Read header fields and/or the resource using getInputStream()
Here is a sample console application that connects to a URL and prints out the header details to the standard output.

#include "ot/io/Console.h"
#include "ot/net/URL.h"
#include "ot/net/URLConnection.h"

using namespace ot;
using namespace net;
using namespace io;

int main(int argc, char* argv[])
{
    // create a SystemMonitor to ensure clean library termination
    SystemMonitor monitor;

    if(argc != 2)
    {
        Console::cout() << OT_T("Enter a single URL") << endl;
        exit(1);
    }

    // convert the multi-byte input into a OpenTop (Unicode) string
    String urlSpec = StringUtils::FromNativeMBCS(argv[1]);

    try
    {
        URL url(urlSpec);

        RefPtr<URLConnection> rpUrlConn = url.openConnection();

        rpUrlConn->connect();

        for(int i=0; i<rpUrlConn->getHeaderFieldCount(); i++)
        {
            const String& hdr = rpUrlConn->getHeaderField(i);
            if(rpUrlConn->getHeaderFieldKey(i).empty())
                Console::cout() << OT_T("null");
            else
                Console::cout() << rpUrlConn->getHeaderFieldKey(i);

            Console::cout() << OT_T(": ") << hdr << endl;
        }
    }
    catch(Exception& e)
    {
        Console::err() << e.toString() << endl;
    }

    return 0;
}




Constructor/Destructor Summary
URLConnection(const URL& url)
         Constructs a URLConnection for the specified URL.

Method Summary
 virtual void connect()=0
        
 virtual String getContentEncoding()
         Returns the value of the "content-encoding" header field.
 virtual long getContentLength()
         Returns the length of the content for this URLConnection.
 virtual String getContentType()
         Returns the value of the "content-type" header field.
 virtual DateTime getDate()
         Returns the value of the "date" header field parsed into a DateTime object.
static bool GetDefaultUseCaches()
         Returns the default value for the UseCaches property that will be used for new instances of URLConnection.
 bool getDoInput() const
         Returns a boolean value indicating whether this URLConnection may be used for input operations.
 bool getDoOutput() const
         Returns a boolean value indicating whether this URLConnection may be used for output operations.
 virtual String getHeaderField(const String& name)=0
         Returns the value of a header field where the key is equal to name.
 virtual String getHeaderField(size_t index)=0
         Returns the value of a header field by index.
 virtual size_t getHeaderFieldCount()=0
         Returns the number of header fields.
 virtual DateTime getHeaderFieldDate(const String& name)
         Parse the specified header field as a Date and return as a DateTime.
 virtual String getHeaderFieldKey(size_t index)=0
         Returns the value of a header field key by index.
 virtual long getHeaderFieldLong(const String& name, long defaultValue)
         Parse the specified header field as a long integer.
 virtual RefPtr< InputStream > getInputStream()=0
         Returns an InputStream which reads bytes from the connection.
 virtual DateTime getLastModified()
         Returns the value of the "last-modified" header field parsed into a DateTime object.
 virtual RefPtr< OutputStream > getOutputStream()=0
         Returns an OutputStream which can be used to write bytes to the connection.
 virtual String getRequestProperty(const String& name) const
         Returns the value of the specified MIME header.
 virtual const URL& getURL() const
         Returns the URL for this URLConnection.
 bool getUseCaches() const
         Returns the value of the UseCaches property for this URLConnection.
 bool isConnected() const
         Returns the value of the connected property.
protected  void resetHeaderFields()
        
protected  void setConnected(bool bConnected)
         Sets the connected property to bConnected.
static void SetDefaultUseCaches(bool bUseCaches)
         Static method to set the default value for the UseCaches property for new instances of URLConnection.
 void setDoInput(bool bEnable)
         Enables this URLConnection for input processing.
 void setDoOutput(bool bEnable)
         Enables this URLConnection for output processing.
 virtual void setRequestProperty(const String& name, const String& value)
         Sets a request MIME header value.
protected  void setURL(const URL& url)
         Sets the URL for this URLConnection.
 void setUseCaches(bool bUseCaches)
         Sets the value of the UseCaches property for this URLConnection instance.

Methods inherited from class ot::ManagedObject
addRef, getRefCount, onFinalRelease, operator=, release

Constructor/Destructor Detail

URLConnection

 URLConnection(const URL& url)
Constructs a URLConnection for the specified URL. No attempt is made to connect to the URL resource at this stage.


Method Detail

connect

virtual void connect()=0


getContentEncoding

virtual String getContentEncoding()
Returns the value of the "content-encoding" header field.


getContentLength

virtual long getContentLength()
Returns the length of the content for this URLConnection. For http URLs this is the value returned in the content-length header field (if present). For URLs that use the file: protocol the file length is read directly from the file system.

When using HTTP 1.1, the content length is not always available. In this case the resource will be transmitted using the "Chunked" encoding method.

Returns:
the length of the content or -1 if the content length is not known.

getContentType

virtual String getContentType()
Returns the value of the "content-type" header field.


getDate

virtual DateTime getDate()
Returns the value of the "date" header field parsed into a DateTime object. If the header field does not exist an invalid DateTime object is returned.

See also:
DateTime::isValid()

GetDefaultUseCaches

static bool GetDefaultUseCaches()
Returns the default value for the UseCaches property that will be used for new instances of URLConnection.


getDoInput

bool getDoInput() const
Returns a boolean value indicating whether this URLConnection may be used for input operations. A URLConnection may be used for input, output or both depending on the protocol and the settings of the doInput/doOutput flags.

The default value is true, unless this URLConnection has been explicitly enabled for output operations, in which case the default is false.

See also:
setDoInput() , setDoOutput()

getDoOutput

bool getDoOutput() const
Returns a boolean value indicating whether this URLConnection may be used for output operations. A URLConnection may be used for input, output or both depending on the protocol and the settings of the doInput/doOutput flags.

The default value is false..

See also:
setDoOutput()

getHeaderField

virtual String getHeaderField(const String& name)=0
Returns the value of a header field where the key is equal to name. If the key is not found in the collection an empty String is returned. Key comparison is performed without regard to case.

Parameters:
name - the name of the header.
Note:
This function may attempt to connect to the URL resource if it is not already connected.

getHeaderField

virtual String getHeaderField(size_t index)=0
Returns the value of a header field by index. If index exceeds the number of entries in the list an empty String is returned.

Parameters:
index - a 0-based index into the header sequence.
Note:
This function may attempt to connect to the URL resource if it is not already connected.

getHeaderFieldCount

virtual size_t getHeaderFieldCount()=0
Returns the number of header fields.

Note:
This function may attempt to connect to the URL resource if it is not already connected.

getHeaderFieldDate

virtual DateTime getHeaderFieldDate(const String& name)
Parse the specified header field as a Date and return as a DateTime.

Returns:
a DateTime object representing the name header field. If the header field does not exist, or is not a valid Date an invalid DateTime is returned.

getHeaderFieldKey

virtual String getHeaderFieldKey(size_t index)=0
Returns the value of a header field key by index. If index exceeds the number of entries in the list an empty String is returned

Parameters:
index - a 0-based index into the header sequence.
Note:
This function may attempt to connect to the URL resource if it is not already connected.

getHeaderFieldLong

virtual long getHeaderFieldLong(const String& name,
                                long defaultValue)
Parse the specified header field as a long integer. If the header is not present then return the passed default value.

Parameters:
name - the header field key
defaultValue - the value to return if the specified header field is not present

getInputStream

virtual RefPtr< InputStreamgetInputStream()=0
Returns an InputStream which reads bytes from the connection. Calling getInputStream() will automatically call connect() to connect to the resource if it is not already connected.

Exceptions:
IOException - if an error occurs while connecting or reading from the connection

getLastModified

virtual DateTime getLastModified()
Returns the value of the "last-modified" header field parsed into a DateTime object. If the header field does not exist an invalid DateTime object is returned.


getOutputStream

virtual RefPtr< OutputStreamgetOutputStream()=0
Returns an OutputStream which can be used to write bytes to the connection. Calling getOutputStream() does not necessarily mean that a connection will be established to the resource specified by the URL. For some protocols, the connection will only become established once getInputStream() or connect() is called.

Exceptions:
IOException - if an error occurs
IllegalStateException - if a connection has already been established and the protocol requires the output stream to obtained prior to connecting (as is the case with HTTP).
ProtocolException - if the URLConnection has not been made ready for output operations using setDoOutput()

getRequestProperty

virtual String getRequestProperty(const String& name) const
Returns the value of the specified MIME header.

Parameters:
name - the name by which the property is known.
Returns:
the requested header value, or an empty string if a header with the supplied name does not exist.
See also:
setRequestProperty()

getURL

virtual const URLgetURL() const
Returns the URL for this URLConnection.


getUseCaches

bool getUseCaches() const
Returns the value of the UseCaches property for this URLConnection.


isConnected

bool isConnected() const
Returns the value of the connected property.

Returns:
true if this URLConnection is connected to the resource; false otherwise

resetHeaderFields

protected void resetHeaderFields()


setConnected

protected void setConnected(bool bConnected)
Sets the connected property to bConnected.


SetDefaultUseCaches

static void SetDefaultUseCaches(bool bUseCaches)
Static method to set the default value for the UseCaches property for new instances of URLConnection.


setDoInput

void setDoInput(bool bEnable)
Enables this URLConnection for input processing.

Exceptions:
IllegalStateException - if this URLConnection is already connected.
See also:
getDoInput() , getInputStream() , setDoOutput()

setDoOutput

void setDoOutput(bool bEnable)
Enables this URLConnection for output processing. Enabling output processing will disable input processing unless input processing is explicitly enabled using setDoInput().

Exceptions:
IllegalStateException - if this URLConnection is already connected.
See also:
getDoOutput() , getOutputStream() , setDoInput()

setRequestProperty

virtual void setRequestProperty(const String& name,
                                const String& value)
Sets a request MIME header value. If a MIME header with the specified name already exists, its value is replaced with the supplied value.

Parameters:
name - the name by which the property is known.
value - the value to be associated with the named property.
Exceptions:
ProtocolException - if the header is not supported or cannot be set at this time.
See also:
getRequestProperty()

setURL

protected void setURL(const URL& url)
Sets the URL for this URLConnection. Called by derived classes when a URL needs to be updated - such as during HTTP redirection.

See also:
getURL()

setUseCaches

void setUseCaches(bool bUseCaches)
Sets the value of the UseCaches property for this URLConnection instance. When set to true, the URLConnection will permit the use of cached resources.



Cross-Platform C++

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

Copyright © 2000-2003 ElCel Technology   Trademark Acknowledgements