This object is used to access files from the Internet. NOTE: This version supports only the HTTP protocol, i.e. any URL starting with "http". An SPInternet object is created using the Net.SPInternet method.
Property: contentBinary
Returns an array of bytes containing the downloaded data without any conversion of any kind.
SPArray contentBinary();
If any error occurs, an exception is generated. To avoid generating an exception, use "wait" to wait for the operation to complete, or for a "Done" event to occur, before using this call.
If the file download is not yet complete, this call will wait until it is complete or an error occurs before returning.
Property: contentLength
Returns the length of the file in bytes, as provided by the server in the HTTP header. If the header has not yet been received at the time of this call, this will not return until the header has been received or an error has been detected. NOTE: Not all servers transmit this information, it is possible to get a value of zero even if the file exists and has a non-zero length. In this case, all you can do is read the file and see how many bytes you get!
int contentLength();
Property: contentText
Returns a string containing the contents of the current download converted to text.
String contentText();
If any error occurs, an exception is generated. To avoid generating an exception, use "wait" to wait for the operation to complete, or for a "Done" event to occur, before using this call.
If the file download is not yet complete, this call will wait until it is complete or an error occurs before returning.
Property: contentType
Returns a standard HTTP string containing the MIME type of the file content.
String contentType();
It is beyond the scope of this documentation to describe all the MIME types. Some common ones include:
Property: done
Returns true if the last operation is complete.
bool = done
This read-only property is true if the connection is idle, i.e. either no operation has ever been started, or the last one either completed successfully or terminated with an error.
Event: name_Done
An event generated when the file has been completely loaded.
void Done();
Event: name_Error
An event generated when the request has been terminated due to an error.
void Error(errorString);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| errorString | String | An error message describing the error. |
Event: name_Found
An event generated when a positive response is received from the server. I.e. the file has been found, although it hasn't been completely loaded yet.
void Found();
Method: getFormURL
Starts the process of loading a file from a given "http" URL using the HTTP "GET" method, supplying the given arguments as if they were user-entered elements on an HTML form.
bool getFormURL(urlString, name1, value1);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| urlString | String | A complete URL. Must start with "http://" |
| name1 | String | The name of the first form element. |
| value1 | String | The value of the first form element. |
Any number of additional form elements can be specified by providing additional name/value argument pairs. See other comments under getURL.
Method: getURL
Starts the process of loading a file from a given "http" URL.
bool getURL(urlString);
bool getURL(urlString, referrer);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| urlString | String | A complete URL. Must start with "http://" |
| referrer | String | Optional referrer string sent with the request |
If a return value is assigned from this method, it returns true if the URL is found, i.e. if the HTTP header is loaded OK. If no return value is assigned, this method returns immediately. You can then use the "Error" event to request a callback on error or periodically check the "done" and "lastError" properties.
Once this method has returned true, you can check the header properties such as contentLen, contentType, rawHeaders, etc. This does not guarantee that the whole file has, or can be, loaded.
Property: lastError
Returns the internal error code of the last operation. This will be zero if no error
int lastError();
Property: lastErrorString
Returns a human-readable string describing any error from the last operation. This will be empty if no error.
String lastErrorString();
Method: postFormURL
Starts the process of loading a file from a given "http" URL using the HTTP "POST" method, supplying the given arguments as if they were user-entered elements on an HTML form.
bool postFormURL(urlString, name1, value1);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| urlString | String | A complete URL. Must start with "http://" |
| name1 | String | The name of the first form element. |
| value1 | String | The value of the first form element. |
Any number of additional form elements can be specified by providing additional name/value argument pairs. See other comments under getURL.
Method: postURL
Starts the process of loading a file from a given "http" URL using the HTTP "POST" method.
bool postURL(urlString, extraData, contentType);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| urlString | String | A complete URL. Must start with "http://" |
| extraData | String | Any optional PUT data required by the server. |
| contentType | String | The MIME type of the extra data. |
See other comments under getURL.
Event: name_Progress
An event generated each time an increment of progress has been made in requesting and downloading the file.
void Progress(message, current, outOf);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| message | String | A string describing the current status of the request. |
| current | int | The number of bytes that has been downloaded. |
| outOf | int | The total number of bytes to be done. This value depends on the server and may not be available. Most servers return a correct value, but it may be -1. |
Method: putURL
Starts the process of loading a file from a given "http" URL using the HTTP "PUT" method.
bool putURL(urlString, extraData, contentType);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| urlString | String | A complete URL. Must start with "http://" |
| extraData | String | Any optional PUT data required by the server. |
| contentType | String | The MIME type of the extra data. |
See other comments under getURL.
Property: rawHeaders
Returns a string containing the raw headers that preceeded the current download.
String rawHeaders();
Method: wait
Waits for the operation to finish, an error to occur, or the given amount of time to elapse, whichever comes first.
bool wait();
bool wait(millis);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| millis | int | The maximum number of milliseconds to wait. If this is not specified, the call waits forever. |
Returns true if the operation completed without any error in the given amount of time.
Method: waitProgress
Version added: 1.2
Waits for the operation to finish, an error to occur, or the given amount of time to elapse with no response from the server, whichever comes first.
bool waitProgress(millis);
| Parameters | ||
|---|---|---|
| Name | Expected Type | Description |
| millis | int | The maximum number of milliseconds to wait. If more than this amount of time elapses between responses from the server, the call terminates. |
Returns true if the operation completed without any error.
This method provides an alternative to wait for cases where the size of the file is not known and no reasonable guess can be made about how long the operation might take. This call allows the operation to keep waiting as long as some progress is being made.