Class

# URLConnection

<div class="rst-class">

forsearch

</div>

REST

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

## Description

Used to send and receive data using the HTTP 1.1+ protocol.

## Properties

<div class="rst-class">

table-centered_columns_3_and_4

</div>

| Name                                                                   | Type                               | Read-Only | Shared |
|------------------------------------------------------------------------|------------------------------------|-----------|--------|
| `AllowCertificateValidation<urlconnection.allowcertificatevalidation>` | `Boolean</api/data_types/boolean>` |           |        |
| `FollowRedirects<urlconnection.followredirects>`                       | `Boolean</api/data_types/boolean>` |           |        |
| `HTTPStatusCode<urlconnection.httpstatuscode>`                         | `Integer</api/data_types/integer>` | ✓         |        |
| `Password<urlconnection.password>`                                     | `String</api/data_types/string>`   |           |        |
| `UserName<urlconnection.username>`                                     | `String</api/data_types/string>`   |           |        |

## Methods

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                     | Parameters                                                                                                                                                                           | Returns                            | Shared |
|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|--------|
| `ClearRequestHeaders<urlconnection.clearrequestheaders>` |                                                                                                                                                                                      |                                    |        |
| `Disconnect<urlconnection.disconnect>`                   |                                                                                                                                                                                      |                                    |        |
| `RequestHeader<urlconnection.requestheader>`             | name As `String</api/data_types/string>`                                                                                                                                             | `String</api/data_types/string>`   |        |
|                                                          | name As `String</api/data_types/string>`, `Assigns</api/language/assigns>` value As `String</api/data_types/string>`                                                                 |                                    |        |
| `ResponseHeader<urlconnection.responseheader>`           | name As `String</api/data_types/string>`                                                                                                                                             | `String</api/data_types/string>`   |        |
| `ResponseHeaders<urlconnection.responseheaders>`         |                                                                                                                                                                                      | `Iterator</api/language/iterator>` |        |
| `Send<urlconnection.send>`                               | method As `String</api/data_types/string>`, URL As `String</api/data_types/string>`, file As `FolderItem</api/files/folderitem>`, timeout As `Integer</api/data_types/integer>` = 60 |                                    |        |
|                                                          | method As `String</api/data_types/string>`, URL As `String</api/data_types/string>`, timeout As `Integer</api/data_types/integer>` = 60                                              |                                    |        |
| `SendSync<urlconnection.sendsync>`                       | method As `String</api/data_types/string>`, URL As `String</api/data_types/string>`, file As `FolderItem</api/files/folderitem>`, timeout As `Integer</api/data_types/integer>` = 0  |                                    |        |
|                                                          | method As `String</api/data_types/string>`, URL As `String</api/data_types/string>`, timeout As `Integer</api/data_types/integer>` = 0                                               | `String</api/data_types/string>`   |        |
| `SetRequestContent<urlconnection.setrequestcontent>`     | content As `String</api/data_types/string>`, mimeType As `String</api/data_types/string>`                                                                                            |                                    |        |

## Events

<div class="rst-class">

table-centered_column_4

</div>

| Name                                                             | Parameters                                                                                                                                                                                  | Returns                            |
|------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| `AuthenticationRequested<urlconnection.authenticationrequested>` | realm As `String</api/data_types/string>`, `ByRef</api/language/byref>` name As `String</api/data_types/string>`, `ByRef</api/language/byref>` password As `String</api/data_types/string>` | `Boolean</api/data_types/boolean>` |
| `ContentReceived<urlconnection.contentreceived>`                 | URL As `String</api/data_types/string>`, HTTPStatus As `Integer</api/data_types/integer>`, content As `String</api/data_types/string>`                                                      |                                    |
| `Error<urlconnection.error>`                                     | err As `RuntimeException</api/exceptions/runtimeexception>`                                                                                                                                 |                                    |
| `FileReceived<urlconnection.filereceived>`                       | URL As `String</api/data_types/string>`, HTTPStatus As `Integer</api/data_types/integer>`, file As `FolderItem</api/files/folderitem>`                                                      |                                    |
| `HeadersReceived<urlconnection.headersreceived>`                 | URL As `String</api/data_types/string>`, HTTPStatus As `Integer</api/data_types/integer>`                                                                                                   |                                    |
| `ReceivingProgressed<urlconnection.receivingprogressed>`         | bytesReceived As `Int64</api/data_types/additional_types/int64>`, totalBytes As `Int64</api/data_types/additional_types/int64>`, newData As `String</api/data_types/string>`                |                                    |
| `SendingProgressed<urlconnection.sendingprogressed>`             | bytesSent As `Int64</api/data_types/additional_types/int64>`, bytesLeft As `Int64</api/data_types/additional_types/int64>`                                                                  |                                    |

## Property descriptions

<div id="urlconnection.allowcertificatevalidation">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.AllowCertificateValidation

**AllowCertificateValidation** As `Boolean</api/data_types/boolean>`

> When set to `True</api/language/true>`, the connection requires that the server's certificate is valid. The Error event is called if the certificate is not valid. The default value is `True</api/language/true>`.

<div id="urlconnection.followredirects">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.FollowRedirects

**FollowRedirects** As `Boolean</api/data_types/boolean>`

> When set to `True</api/language/true>`, the request will follow redirects. When `False</api/language/false>` it will not. The default value is `True</api/language/true>`.

<div id="urlconnection.httpstatuscode">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.HTTPStatusCode

**HTTPStatusCode** As `Integer</api/data_types/integer>`

> The HTTP status code when using the SendSync methods.
>
> This property is read-only.
>
> This code reads the HTTP status code after a synchronous request:
>
> ``` xojo
> Var content As String
> content = MyConnection.SendSync("GET", "http://127.0.0.1:8080/GetData", 30)
> Var status As Integer = MyConnection.HTTPStatusCode
> ```

<div id="urlconnection.password">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.Password

**Password** As `String</api/data_types/string>`

> The password to be used to authentication.
>
> Unlike other supported operating systems where user authentication is done via the `AuthenticationRequested<urlconnection.authenticationrequested>` event, on Android, the `UserName<urlconnection.username>` and *Password* must be provided (via properties) before sending the request.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This property is only supported for Android.
>
> </div>

<div id="urlconnection.username">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.UserName

**UserName** As `String</api/data_types/string>`

> The username to be used to authentication.
>
> Unlike other supported operating systems where user authentication is done via the `AuthenticationRequested<urlconnection.authenticationrequested>` event, on Android, the *UserName* and `Password<urlconnection.password>` must be provided (via properties) before sending the request.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This property is only supported for Android.
>
> </div>

## Method descriptions

<div id="urlconnection.clearrequestheaders">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.ClearRequestHeaders

**ClearRequestHeaders**

> Clears all of the request headers, which is useful if you are using the socket to send a different request.
>
> ``` xojo
> mySocket.ClearRequestHeaders
> ```

<div id="urlconnection.disconnect">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.Disconnect

**Disconnect**

> Disconnects the socket.
>
> A disconnected socket is not set to Nil and may be reused.

<div id="urlconnection.requestheader">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.RequestHeader

**RequestHeader**(name As `String</api/data_types/string>`) As `String</api/data_types/string>`

> Gets the request header with the key of name. The Name parameter's encoding is converted to ASCII. If the header does not exist in the request headers, an empty String is returned. Raises a RuntimeException if the encoding could not be converted to ASCII.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<div class="rst-class">

forsearch

</div>

URLConnection.RequestHeader

**RequestHeader**(name As `String</api/data_types/string>`, `Assigns</api/language/assigns>` value As `String</api/data_types/string>`)

> Sets the request header with the key of name. The Name parameter's encoding is converted to ASCII.
>
> The parameter `name` is the name of the key to get or set and `value` ist the value for the key.
>
> Sets an API key as a token in the request header:
>
> ``` xojo
> Self.RequestHeader("Authorization") = "MyAPIKey"
> mySocket.Send("GET", "http://www.webservice.com/GetData")
> ```

<div id="urlconnection.responseheader">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.ResponseHeader

**ResponseHeader**(name As `String</api/data_types/string>`) As `String</api/data_types/string>`

> Gets a response header.

<div id="urlconnection.responseheaders">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.ResponseHeaders

**ResponseHeaders** As `Iterator</api/language/iterator>`

> Used to iterate over all response headers.
>
> ``` xojo
> Var connection As New URLConnection
> Var headers() As Pair
>
> For Each header As Pair In connection.ResponseHeaders
>     headers.AddRow(header.Left : header.Right)
> Next
> ```

<div id="urlconnection.send">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.Send

**Send**(method As `String</api/data_types/string>`, URL As `String</api/data_types/string>`, file As `FolderItem</api/files/folderitem>`, timeout As `Integer</api/data_types/integer>` = 60)

> Asynchronously sends a request using an HTTP method such as GET or POST. Send can be used to send both standard "http" and secure "https" requests. The *timeout* is in seconds.
>
> If you pass "GET" as the *method*, the `FileReceived<urlconnection.filereceived>` event will be called with the file received from the server passed to it.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<div class="rst-class">

forsearch

</div>

URLConnection.Send

**Send**(method As `String</api/data_types/string>`, URL As `String</api/data_types/string>`, timeout As `Integer</api/data_types/integer>` = 60)

> Asynchronously sends a request using an HTTP method such as GET or POST. Send can be used to send both standard "http" and secure "https" requests. The *timeout* is in seconds.
>
> If you pass "GET" as the *method*, or use the Send *method* to communicate with the server, the `ContentReceived<urlconnection.contentreceived>` event will be called with the content received from the server passed to it.
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> The timeout is in seconds and currently can be a maximum of 60 seconds (75 on macOS). A connection that times out will raise the Error event. You can view the timeout length on macOS with this Terminal command: `sysctl net.inet.tcp.keepinit`. You can change it using this command (specify the value in milliseconds): `sysctl net.inet.tcp.keepinit=30000`.
>
> </div>
>
> This example sends a request. The ContentReceived event is called with the response:
>
> ``` xojo
> MyConnection.Send("GET", "http://127.0.0.1:8080/GetData")
> ```
>
> Sends a GET request, saving (downloading) the response to a file sent to the FileReceived event:
>
> ``` xojo
> Var outputFile As FolderItem = SpecialFolder.Documents.Child("data.json")
> MyConnection.Send("GET", "http://127.0.0.1:8080/GetData", outputFile)
> ```
>
> To make a secure request, use "https" in the URL:
>
> ``` xojo
> Var outputFile As FolderItem = SpecialFolder.Documents.Child("data.json")
> MyConnection.Send("GET", "https://www.mydomain.com/GetData", outputFile)
> ```

<div id="urlconnection.sendsync">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.SendSync

**SendSync**(method As `String</api/data_types/string>`, URL As `String</api/data_types/string>`, file As `FolderItem</api/files/folderitem>`, timeout As `Integer</api/data_types/integer>` = 0)

> Synchronously sends a request using an HTTP method such as GET or POST and returns the output in file. The results are saved to the supplied *file*. Send can be used to send both standard http and secure https requests. The *timeout* is in seconds.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

<div class="rst-class">

forsearch

</div>

URLConnection.SendSync

**SendSync**(method As `String</api/data_types/string>`, URL As `String</api/data_types/string>`, timeout As `Integer</api/data_types/integer>` = 0) As `String</api/data_types/string>`

> Synchronously sends a request using an HTTP method such as GET or POST. Results are returned as a String. Send can be used to send both standard http and secure https requests. The *timeout* is in seconds.
>
> <div class="note">
>
> <div class="title">
>
> Note
>
> </div>
>
> Be aware that calling SendSync can cause your app's UI to "freeze" while it waits for the result. For normal processing you may want to use the asynchronous Send method instead, which calls the ContentReceived or FileReceived events when data is received.
>
> </div>
>
> This method raises a `RuntimeException</api/exceptions/runtimeexception>` if an App Transport Security error occurs on macOS due to using a non-secure URL without the appropriate entry in the plist.
>
> ``` xojo
> Var content As String
> content = MyConnection.SendSync("GET", "http://127.0.0.1:8080/GetData", 30)
> ```
>
> Sends a GET request, saving the response to a file:
>
> ``` xojo
> Var outputFile As FolderItem = SpecialFolder.Documents.Child("data.json")
> MyConnection.SendSync("GET", "http://127.0.0.1:8080/GetData", outputFile, 30)
> ```
>
> To make a secure request, use "https" in the URL:
>
> ``` xojo
> Var outputFile As FolderItem = SpecialFolder.Documents.Child("data.json")
> MyConnection.SendSync("GET", "https://www.mydomain.com/GetData", outputFile, 30)
> ```

<div id="urlconnection.setrequestcontent">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.SetRequestContent

**SetRequestContent**(content As `String</api/data_types/string>`, mimeType As `String</api/data_types/string>`)

> Sets the *content* data and content *type* to be sent to the server.
>
> Sends a POST request with \`JSON\`:
>
> ``` xojo
> Var json As New JSONItem
> json.Value("ID") = 123456
>
> mySocket.SetRequestContent(json.ToString, "application/json")
> mySocket.Send("POST", "http://127.0.0.1:8080/GetCustomer")
> ```
>
> To send form information, you build the String yourself:
>
> ``` xojo
> ' Build form String
> Var formText As String = "firstName=Bob&lastName=Roberts"
>
> ' POST it
> mySocket.SetRequestContent(formText, "application/x-www-form-urlencoded")
> mySocket.Send("POST", "http://www.webserviceurl.com")
> ```

## Event descriptions

<div id="urlconnection.authenticationrequested">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.AuthenticationRequested

**AuthenticationRequested**(realm As `String</api/data_types/string>`, `ByRef</api/language/byref>` name As `String</api/data_types/string>`, `ByRef</api/language/byref>` password As `String</api/data_types/string>`) As `Boolean</api/data_types/boolean>`

> Called when the connection requires HTTP basic authentication. Set the name and password and return `True</api/language/true>`.
>
> <div class="important">
>
> <div class="title">
>
> Important
>
> </div>
>
> This event is not supported for Android. The `UserName<urlconnection.username>` and `Password<urlconnection.password>` properties must be populated before the connection is made.
>
> </div>
>
> Specify a name and password:
>
> ``` xojo
> name = "MyUserName"
> password = "MyPassword"
> Return True
> ```

<div id="urlconnection.contentreceived">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.ContentReceived

**ContentReceived**(URL As `String</api/data_types/string>`, HTTPStatus As `Integer</api/data_types/integer>`, content As `String</api/data_types/string>`)

> Called when a new page has been retrieved from the server as a result of calling Send.
>
> The encoding of *content* is set to the content-type encoding (charset) of the incoming content.

<div id="urlconnection.error">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.Error

**Error**(err As `RuntimeException</api/exceptions/runtimeexception>`)

> Called when an HTTP error occurs. When the error is a network-level failure (such as a connection timeout, SSL certificate error, or lost connection), *err* will be a `NetworkException</api/exceptions/networkexception>`.
>
> The `ErrorNumber` values in the *err* exception vary by platform.
>
> **macOS**
>
> | Value | Constant                                               | Description                                                                                   |
> |-------|--------------------------------------------------------|-----------------------------------------------------------------------------------------------|
> | -1    | NSURLErrorUnknown                                      | An unknown error occurred.                                                                    |
> | -999  | NSURLErrorCancelled                                    | The connection was cancelled.                                                                 |
> | -1000 | NSURLErrorBadURL                                       | A malformed URL prevented the connection from being initiated.                                |
> | -1001 | NSURLErrorTimedOut                                     | The connection timed out.                                                                     |
> | -1002 | NSURLErrorUnsupportedURL                               | The URL scheme is not supported.                                                              |
> | -1003 | NSURLErrorCannotFindHost                               | The host name could not be found.                                                             |
> | -1004 | NSURLErrorCannotConnectToHost                          | A connection could not be established to the host.                                            |
> | -1005 | NSURLErrorNetworkConnectionLost                        | The network connection was lost.                                                              |
> | -1006 | NSURLErrorDNSLookupFailed                              | The DNS lookup for the host failed.                                                           |
> | -1007 | NSURLErrorHTTPTooManyRedirects                         | The request was redirected too many times.                                                    |
> | -1008 | NSURLErrorResourceUnavailable                          | The requested resource could not be retrieved.                                                |
> | -1009 | NSURLErrorNotConnectedToInternet                       | The device is not connected to the internet.                                                  |
> | -1010 | NSURLErrorRedirectToNonExistentLocation                | The connection was redirected to a non-existent location.                                     |
> | -1011 | NSURLErrorBadServerResponse                            | The server returned an invalid response.                                                      |
> | -1012 | NSURLErrorUserCancelledAuthentication                  | The connection was cancelled by the user during authentication.                               |
> | -1013 | NSURLErrorUserAuthenticationRequired                   | Authentication is required to access the resource.                                            |
> | -1014 | NSURLErrorZeroByteResource                             | The server reported the resource as having zero length.                                       |
> | -1015 | NSURLErrorCannotDecodeRawData                          | The raw data could not be decoded.                                                            |
> | -1016 | NSURLErrorCannotDecodeContentData                      | The content data could not be decoded.                                                        |
> | -1017 | NSURLErrorCannotParseResponse                          | The response could not be parsed.                                                             |
> | -1018 | NSURLErrorInternationalRoamingOff                      | The connection failed because international roaming is disabled.                              |
> | -1019 | NSURLErrorCallIsActive                                 | The connection failed because a call is active.                                               |
> | -1020 | NSURLErrorDataNotAllowed                               | The cellular network disallowed the connection.                                               |
> | -1021 | NSURLErrorRequestBodyStreamExhausted                   | The request body stream was exhausted.                                                        |
> | -1022 | NSURLErrorAppTransportSecurityRequiresSecureConnection | App Transport Security disallowed the connection because it does not use a secure connection. |
> | -1100 | NSURLErrorFileDoesNotExist                             | The file does not exist.                                                                      |
> | -1101 | NSURLErrorFileIsDirectory                              | The requested resource is a directory.                                                        |
> | -1102 | NSURLErrorNoPermissionsToReadFile                      | The file could not be read due to insufficient permissions.                                   |
> | -1103 | NSURLErrorDataLengthExceedsMaximum                     | The data length exceeds the maximum allowed.                                                  |
> | -1201 | NSURLErrorSecureConnectionFailed                       | An attempt to establish a secure connection failed.                                           |
> | -1202 | NSURLErrorServerCertificateHasBadDate                  | The server certificate has an invalid date.                                                   |
> | -1203 | NSURLErrorServerCertificateUntrusted                   | The server certificate is not trusted.                                                        |
> | -1204 | NSURLErrorServerCertificateHasUnknownRoot              | The server certificate is not signed by a known certificate authority.                        |
> | -1205 | NSURLErrorServerCertificateNotYetValid                 | The server certificate is not yet valid.                                                      |
> | -1206 | NSURLErrorClientCertificateRejected                    | The server rejected the client certificate.                                                   |
> | -1207 | NSURLErrorClientCertificateRequired                    | The server requires a client certificate.                                                     |
> | -2000 | NSURLErrorCannotLoadFromNetwork                        | The resource can only be loaded over the network but the network is unavailable.              |
> | -3000 | NSURLErrorCannotCreateFile                             | A downloaded file could not be created.                                                       |
> | -3001 | NSURLErrorCannotOpenFile                               | A downloaded file could not be opened.                                                        |
> | -3002 | NSURLErrorCannotCloseFile                              | A downloaded file could not be closed.                                                        |
> | -3003 | NSURLErrorCannotWriteToFile                            | A downloaded file could not be written to.                                                    |
> | -3004 | NSURLErrorCannotRemoveFile                             | A downloaded file could not be removed.                                                       |
> | -3005 | NSURLErrorCannotMoveFile                               | A downloaded file could not be moved.                                                         |
> | -3006 | NSURLErrorDownloadDecodingFailedMidStream              | Decoding of the downloaded data failed mid-stream.                                            |
> | -3007 | NSURLErrorDownloadDecodingFailedToComplete             | Decoding of the downloaded data failed to complete.                                           |
>
> **Windows**
>
> | Value | Constant                                | Description                                                                               |
> |-------|-----------------------------------------|-------------------------------------------------------------------------------------------|
> | 12001 | ERROR_INTERNET_OUT_OF_HANDLES           | No more handles could be generated.                                                       |
> | 12002 | ERROR_INTERNET_TIMEOUT                  | The request timed out.                                                                    |
> | 12003 | ERROR_INTERNET_EXTENDED_ERROR           | An extended error was returned from the server.                                           |
> | 12004 | ERROR_INTERNET_INTERNAL_ERROR           | An internal error occurred.                                                               |
> | 12005 | ERROR_INTERNET_INVALID_URL              | The URL is invalid.                                                                       |
> | 12006 | ERROR_INTERNET_UNRECOGNIZED_SCHEME      | The URL scheme could not be recognized or is not supported.                               |
> | 12007 | ERROR_INTERNET_NAME_NOT_RESOLVED        | The server name could not be resolved.                                                    |
> | 12008 | ERROR_INTERNET_PROTOCOL_NOT_FOUND       | The requested protocol could not be located.                                              |
> | 12012 | ERROR_INTERNET_SHUTDOWN                 | WinINet is being shut down or unloaded.                                                   |
> | 12017 | ERROR_INTERNET_OPERATION_CANCELLED      | The operation was cancelled because the handle was closed before the operation completed. |
> | 12029 | ERROR_INTERNET_CANNOT_CONNECT           | The attempt to connect to the server failed.                                              |
> | 12030 | ERROR_INTERNET_CONNECTION_ABORTED       | The connection with the server was terminated.                                            |
> | 12031 | ERROR_INTERNET_CONNECTION_RESET         | The connection with the server was reset.                                                 |
> | 12037 | ERROR_INTERNET_SEC_CERT_DATE_INVALID    | The SSL certificate has an invalid date. The certificate may be expired.                  |
> | 12038 | ERROR_INTERNET_SEC_CERT_CN_INVALID      | The SSL certificate common name (host name) does not match the server.                    |
> | 12044 | ERROR_INTERNET_CLIENT_AUTH_CERT_NEEDED  | The server requires client authentication.                                                |
> | 12045 | ERROR_INTERNET_INVALID_CA               | The Certificate Authority that generated the server certificate is unknown.               |
> | 12055 | ERROR_INTERNET_SEC_CERT_ERRORS          | The SSL certificate contains errors.                                                      |
> | 12056 | ERROR_INTERNET_SEC_CERT_NO_REV          | The SSL certificate has no revocation information.                                        |
> | 12057 | ERROR_INTERNET_SEC_CERT_REV_FAILED      | Revocation of the SSL certificate failed.                                                 |
> | 12150 | ERROR_HTTP_HEADER_NOT_FOUND             | The requested header could not be located.                                                |
> | 12151 | ERROR_HTTP_DOWNLEVEL_SERVER             | The server did not return any headers.                                                    |
> | 12152 | ERROR_HTTP_INVALID_SERVER_RESPONSE      | The server response could not be parsed.                                                  |
> | 12153 | ERROR_HTTP_INVALID_HEADER               | The supplied header is invalid.                                                           |
> | 12155 | ERROR_HTTP_HEADER_ALREADY_EXISTS        | The header could not be added because it already exists.                                  |
> | 12156 | ERROR_HTTP_REDIRECT_FAILED              | The redirection failed because the scheme changed or all redirect attempts failed.        |
> | 12157 | ERROR_INTERNET_SECURITY_CHANNEL_ERROR   | An internal error occurred while loading the SSL libraries.                               |
> | 12163 | ERROR_INTERNET_DISCONNECTED             | The internet connection has been lost.                                                    |
> | 12164 | ERROR_INTERNET_SERVER_UNREACHABLE       | The server is unreachable.                                                                |
> | 12165 | ERROR_INTERNET_PROXY_SERVER_UNREACHABLE | The designated proxy server cannot be reached.                                            |
> | 12169 | ERROR_INTERNET_SEC_INVALID_CERT         | The SSL certificate is invalid.                                                           |
> | 12170 | ERROR_INTERNET_SEC_CERT_REVOKED         | The SSL certificate was revoked.                                                          |
>
> **Linux**
>
> | Value | Constant                                  | Description                                                                                  |
> |-------|-------------------------------------------|----------------------------------------------------------------------------------------------|
> | 0     | SOUP_STATUS_NONE                          | No status available. The request has not completed or failed before a response was received. |
> | 400   | SOUP_STATUS_BAD_REQUEST                   | Bad Request.                                                                                 |
> | 401   | SOUP_STATUS_UNAUTHORIZED                  | Unauthorized.                                                                                |
> | 403   | SOUP_STATUS_FORBIDDEN                     | Forbidden.                                                                                   |
> | 404   | SOUP_STATUS_NOT_FOUND                     | Not Found.                                                                                   |
> | 405   | SOUP_STATUS_METHOD_NOT_ALLOWED            | Method Not Allowed.                                                                          |
> | 407   | SOUP_STATUS_PROXY_AUTHENTICATION_REQUIRED | Proxy Authentication Required.                                                               |
> | 408   | SOUP_STATUS_REQUEST_TIMEOUT               | Request Timeout.                                                                             |
> | 409   | SOUP_STATUS_CONFLICT                      | Conflict.                                                                                    |
> | 410   | SOUP_STATUS_GONE                          | Gone.                                                                                        |
> | 500   | SOUP_STATUS_INTERNAL_SERVER_ERROR         | Internal Server Error.                                                                       |
> | 501   | SOUP_STATUS_NOT_IMPLEMENTED               | Not Implemented.                                                                             |
> | 502   | SOUP_STATUS_BAD_GATEWAY                   | Bad Gateway.                                                                                 |
> | 503   | SOUP_STATUS_SERVICE_UNAVAILABLE           | Service Unavailable.                                                                         |
> | 504   | SOUP_STATUS_GATEWAY_TIMEOUT               | Gateway Timeout.                                                                             |
> | 505   | SOUP_STATUS_HTTP_VERSION_NOT_SUPPORTED    | HTTP Version Not Supported.                                                                  |
>
> Display information about the error:
>
> ``` xojo
> ErrorLabel.Text = e.Reason
> ```

<div id="urlconnection.filereceived">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.FileReceived

**FileReceived**(URL As `String</api/data_types/string>`, HTTPStatus As `Integer</api/data_types/integer>`, file As `FolderItem</api/files/folderitem>`)

> n a download of a file is completed as a result of calling Send and passing a FolderItem.

<div id="urlconnection.headersreceived">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.HeadersReceived

**HeadersReceived**(URL As `String</api/data_types/string>`, HTTPStatus As `Integer</api/data_types/integer>`)

> Called when headers are received from the server.

<div id="urlconnection.receivingprogressed">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.ReceivingProgressed

**ReceivingProgressed**(bytesReceived As `Int64</api/data_types/additional_types/int64>`, totalBytes As `Int64</api/data_types/additional_types/int64>`, newData As `String</api/data_types/string>`)

> Call periodically as data is received.

<div id="urlconnection.sendingprogressed">

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

</div>

<div class="rst-class">

forsearch

</div>

URLConnection.SendingProgressed

**SendingProgressed**(bytesSent As `Int64</api/data_types/additional_types/int64>`, bytesLeft As `Int64</api/data_types/additional_types/int64>`)

> Called periodically as data is sent/uploaded.

## Notes

Usage on Linux requires libsoup3 with a fallback to libsoup2-4.

<span class="title-ref">URLConnection</span> handles both standard "http" connections and secure "https" connections.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Standard Method Definitions

`GET` and `POST` are most commonly used, but there are other methods as well. For example, to get just the headers you can use the HEAD method. The full list of methods is available on the [W3 HTTP/1.1 Method Definition](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html) page.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### Cookies

When using <span class="title-ref">URLConnection</span> on macOS, cookies are shared globally across all sessions. On Windows and Linux they are exclusive to the <span class="title-ref">URLConnection</span> session. Once the connection ends, the cookies are gone.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

### macOS information (app transport security)

Starting with OS X 10.11, you have to use secure "https" connections or you will get this error: "The resource could not be loaded because the App Transport Security policy requires the use of a secure connection". To continue to connect to non-secure "http" connections that you do not control you'll have to provide a plist with a temporary exception specified for each site you are accessing via http:

``` xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSAppTransportSecurity</key>
    <dict>
        <key>NSExceptionDomains</key>
        <dict>
            <key>firstsite.com</key>
            <dict>
                <key>NSIncludesSubdomains</key>
                <true/>
                <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
                <true/>
            </dict>
            <key>secondsite.com</key>
            <dict>
                <key>NSIncludesSubdomains</key>
                <true/>
                <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
                <true/>
            </dict>
        </dict>
    </dict>
</dict>
</plist>
```

If you don't know the specific sites, you can request access to everything using a single key:

``` xojo
<key>NSAppTransportSecurity</key>
<dict>
  <!-- Include to allow all connections; avoid if possible -->
  <key>NSAllowsArbitraryLoads</key>
      <true/>
</dict>
```

Apple may reject an App Store submission if the app uses these settings without valid reasons.

For more information about this, refer to [NSAppTransportSecurity](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW33) in Apple's docs.

For more information: `Using Non-Secure URLs on macOS and iOS</topics/communication/internet/using_non-secure_urls_on_macos_and_ios>`, `Using a plist</topics/application_structure/ios/using_a_plist>`

To test a site to see what plist exceptions it might need you can use this Terminal command:

`/usr/bin/nscurl --ats-diagnostics --verbose https://example.com`

## Compatibility

|                       |     |
|-----------------------|-----|
| **Project Types**     | All |
| **Operating Systems** | All |

<div class="seealso">

`Object</api/data_types/additional_types/object>` parent class; `Using Non-Secure URLs on macOS and iOS</topics/communication/internet/using_non-secure_urls_on_macos_and_ios>`, `Using a plist</topics/application_structure/ios/using_a_plist>` topics; [Paw Extension](https://github.com/xojo/Paw-XojoURLConnectionGenerator) on GitHub

</div>