Represents a URL and has a bunch of useful functions to manipulate it. More...
Public Types | |
| typedef bool( | OpenStreamProgressCallback )(void *context, int bytesSent, int totalBytes) |
| This callback function can be used by the createInputStream() method. | |
Public Member Functions | |
| URL () | |
| Creates an empty URL. | |
| URL (const String &url) | |
| Creates a URL from a string. | |
| URL (const URL &other) | |
| Creates a copy of another URL. | |
| ~URL () | |
| Destructor. | |
| URL & | operator= (const URL &other) |
| Copies this URL from another one. | |
| String | toString (bool includeGetParameters) const |
| Returns a string version of the URL. | |
| bool | isWellFormed () const |
| True if it seems to be valid. | |
| String | getDomain () const |
| Returns just the domain part of the URL. | |
| String | getSubPath () const |
| Returns the path part of the URL. | |
| String | getScheme () const |
| Returns the scheme of the URL. | |
| const URL | withNewSubPath (const String &newPath) const |
| Returns a new version of this URL that uses a different sub-path. | |
| const URL | withParameter (const String ¶meterName, const String ¶meterValue) const |
| Returns a copy of this URL, with a GET or POST parameter added to the end. | |
| const URL | withFileToUpload (const String ¶meterName, const File &fileToUpload, const String &mimeType) const |
| Returns a copy of this URl, with a file-upload type parameter added to it. | |
| const StringPairArray & | getParameters () const |
| Returns a set of all the parameters encoded into the url. | |
| const StringPairArray & | getFilesToUpload () const |
| Returns the set of files that should be uploaded as part of a POST operation. | |
| const StringPairArray & | getMimeTypesOfUploadFiles () const |
| Returns the set of mime types associated with each of the upload files. | |
| const URL | withPOSTData (const String &postData) const |
| Returns a copy of this URL, with a block of data to send as the POST data. | |
| String | getPostData () const |
| Returns the data that was set using withPOSTData(). | |
| bool | launchInDefaultBrowser () const |
| Tries to launch the system's default browser to open the URL. | |
| InputStream * | createInputStream (bool usePostCommand, OpenStreamProgressCallback *progressCallback=nullptr, void *progressCallbackContext=nullptr, const String &extraHeaders=String::empty, int connectionTimeOutMs=0, StringPairArray *responseHeaders=nullptr) const |
| Attempts to open a stream that can read from this URL. | |
| bool | readEntireBinaryStream (MemoryBlock &destData, bool usePostCommand=false) const |
| Tries to download the entire contents of this URL into a binary data block. | |
| String | readEntireTextStream (bool usePostCommand=false) const |
| Tries to download the entire contents of this URL as a string. | |
| XmlElement * | readEntireXmlStream (bool usePostCommand=false) const |
| Tries to download the entire contents of this URL and parse it as XML. | |
Static Public Member Functions | |
| static bool | isProbablyAWebsiteURL (const String &possibleURL) |
| Takes a guess as to whether a string might be a valid website address. | |
| static bool | isProbablyAnEmailAddress (const String &possibleEmailAddress) |
| Takes a guess as to whether a string might be a valid email address. | |
| static String | addEscapeChars (const String &stringToAddEscapeCharsTo, bool isParameter) |
| Adds escape sequences to a string to encode any characters that aren't legal in a URL. | |
| static String | removeEscapeChars (const String &stringToRemoveEscapeCharsFrom) |
| Replaces any escape character sequences in a string with their original character codes. | |
Represents a URL and has a bunch of useful functions to manipulate it.
This class can be used to launch URLs in browsers, and also to create InputStreams that can read from remote http or ftp sources.
| typedef bool( URL::OpenStreamProgressCallback)(void *context, int bytesSent, int totalBytes) |
This callback function can be used by the createInputStream() method.
It allows your app to receive progress updates during a lengthy POST operation. If you want to continue the operation, this should return true, or false to abort.
| URL::URL | ( | ) |
Creates an empty URL.
| URL::~URL | ( | ) |
Destructor.
| String URL::toString | ( | bool | includeGetParameters ) | const |
Returns a string version of the URL.
If includeGetParameters is true and any parameters have been set with the withParameter() method, then the string will have these appended on the end and url-encoded.
| bool URL::isWellFormed | ( | ) | const |
True if it seems to be valid.
| String URL::getDomain | ( | ) | const |
Returns just the domain part of the URL.
E.g. for "http://www.xyz.com/foobar", this will return "www.xyz.com".
| String URL::getSubPath | ( | ) | const |
Returns the path part of the URL.
E.g. for "http://www.xyz.com/foo/bar?x=1", this will return "foo/bar".
| String URL::getScheme | ( | ) | const |
Returns the scheme of the URL.
E.g. for "http://www.xyz.com/foobar", this will return "http". (It won't include the colon).
Returns a copy of this URL, with a GET or POST parameter added to the end.
Any control characters in the value will be encoded.
e.g. calling "withParameter ("amount", "some fish") for the url "www.fish.com" would produce a new url whose toString(true) method would return "www.fish.com?amount=some+fish".
| const URL URL::withFileToUpload | ( | const String & | parameterName, |
| const File & | fileToUpload, | ||
| const String & | mimeType | ||
| ) | const |
Returns a copy of this URl, with a file-upload type parameter added to it.
When performing a POST where one of your parameters is a binary file, this lets you specify the file.
Note that the filename is stored, but the file itself won't actually be read until this URL is later used to create a network input stream.
| const StringPairArray& URL::getParameters | ( | ) | const |
Returns a set of all the parameters encoded into the url.
E.g. for the url "www.fish.com?type=haddock&amount=some+fish", this array would contain two pairs: "type" => "haddock" and "amount" => "some fish".
The values returned will have been cleaned up to remove any escape characters.
| const StringPairArray& URL::getFilesToUpload | ( | ) | const |
Returns the set of files that should be uploaded as part of a POST operation.
This is the set of files that were added to the URL with the withFileToUpload() method.
| const StringPairArray& URL::getMimeTypesOfUploadFiles | ( | ) | const |
Returns the set of mime types associated with each of the upload files.
Returns a copy of this URL, with a block of data to send as the POST data.
If you're setting the POST data, be careful not to have any parameters set as well, otherwise it'll all get thrown in together, and might not have the desired effect.
If the URL already contains some POST data, this will replace it, rather than being appended to it.
This data will only be used if you specify a post operation when you call createInputStream().
| String URL::getPostData | ( | ) | const |
Returns the data that was set using withPOSTData().
| bool URL::launchInDefaultBrowser | ( | ) | const |
Tries to launch the system's default browser to open the URL.
Returns true if this seems to have worked.
| static bool URL::isProbablyAWebsiteURL | ( | const String & | possibleURL ) | [static] |
Takes a guess as to whether a string might be a valid website address.
This isn't foolproof!
| static bool URL::isProbablyAnEmailAddress | ( | const String & | possibleEmailAddress ) | [static] |
Takes a guess as to whether a string might be a valid email address.
This isn't foolproof!
| InputStream* URL::createInputStream | ( | bool | usePostCommand, |
| OpenStreamProgressCallback * | progressCallback = nullptr, |
||
| void * | progressCallbackContext = nullptr, |
||
| const String & | extraHeaders = String::empty, |
||
| int | connectionTimeOutMs = 0, |
||
| StringPairArray * | responseHeaders = nullptr |
||
| ) | const |
Attempts to open a stream that can read from this URL.
| usePostCommand | if true, it will try to do use a http 'POST' to pass the paramters, otherwise it'll encode them into the URL and do a 'GET'. |
| progressCallback | if this is non-zero, it lets you supply a callback function to keep track of the operation's progress. This can be useful for lengthy POST operations, so that you can provide user feedback. |
| progressCallbackContext | if a callback is specified, this value will be passed to the function |
| extraHeaders | if not empty, this string is appended onto the headers that are used for the request. It must therefore be a valid set of HTML header directives, separated by newlines. |
| connectionTimeOutMs | if 0, this will use whatever default setting the OS chooses. If a negative number, it will be infinite. Otherwise it specifies a time in milliseconds. |
| responseHeaders | if this is non-zero, all the (key, value) pairs received as headers in the response will be stored in this array |
| bool URL::readEntireBinaryStream | ( | MemoryBlock & | destData, |
| bool | usePostCommand = false |
||
| ) | const |
Tries to download the entire contents of this URL into a binary data block.
If it succeeds, this will return true and append the data it read onto the end of the memory block.
| destData | the memory block to append the new data to |
| usePostCommand | whether to use a POST command to get the data (uses a GET command if this is false) |
| String URL::readEntireTextStream | ( | bool | usePostCommand = false ) |
const |
Tries to download the entire contents of this URL as a string.
If it fails, this will return an empty string, otherwise it will return the contents of the downloaded file. If you need to distinguish between a read operation that fails and one that returns an empty string, you'll need to use a different method, such as readEntireBinaryStream().
| usePostCommand | whether to use a POST command to get the data (uses a GET command if this is false) |
| XmlElement* URL::readEntireXmlStream | ( | bool | usePostCommand = false ) |
const |
Tries to download the entire contents of this URL and parse it as XML.
If it fails, or if the text that it reads can't be parsed as XML, this will return 0.
When it returns a valid XmlElement object, the caller is responsibile for deleting this object when no longer needed.
| usePostCommand | whether to use a POST command to get the data (uses a GET command if this is false) |
| static String URL::addEscapeChars | ( | const String & | stringToAddEscapeCharsTo, |
| bool | isParameter | ||
| ) | [static] |
Adds escape sequences to a string to encode any characters that aren't legal in a URL.
E.g. any spaces will be replaced with "%20".
This is the opposite of removeEscapeChars().
If isParameter is true, it means that the string is going to be used as a parameter, so it also encodes '$' and ',' (which would otherwise be legal in a URL.
Replaces any escape character sequences in a string with their original character codes.
E.g. any instances of "%20" will be replaced by a space.
This is the opposite of addEscapeChars().
