` | bytesSent As `Int64`, bytesLeft As `Int64` | | ## Property descriptions

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

forsearch

URLConnection.AllowCertificateValidation **AllowCertificateValidation** As `Boolean` > When set to `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`.

forsearch

URLConnection.FollowRedirects **FollowRedirects** As `Boolean` > When set to `True`, the request will follow redirects. When `False` it will not. The default value is `True`.

forsearch

URLConnection.HTTPStatusCode **HTTPStatusCode** As `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 > ```

forsearch

URLConnection.Password **Password** As `String` > The password to be used to authentication. > > Unlike other supported operating systems where user authentication is done via the `AuthenticationRequested` event, on Android, the `UserName` and *Password* must be provided (via properties) before sending the request. > >

> >

> > Important > >

> > This property is only supported for Android. > >

forsearch

URLConnection.UserName **UserName** As `String` > The username to be used to authentication. > > Unlike other supported operating systems where user authentication is done via the `AuthenticationRequested` event, on Android, the *UserName* and `Password` must be provided (via properties) before sending the request. > >

> >

> > Important > >

> > This property is only supported for Android. > >

## Method descriptions

forsearch

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 > ```

forsearch

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

forsearch

URLConnection.RequestHeader **RequestHeader**(name As `String`) As `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. ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

URLConnection.RequestHeader **RequestHeader**(name As `String`, `Assigns` value As `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") > ```

forsearch

URLConnection.ResponseHeader **ResponseHeader**(name As `String`) As `String` > Gets a response header.

forsearch

URLConnection.ResponseHeaders **ResponseHeaders** As `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 > ```

forsearch

URLConnection.Send **Send**(method As `String`, URL As `String`, file As `FolderItem`, timeout As `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` event will be called with the file received from the server passed to it. ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

URLConnection.Send **Send**(method As `String`, URL As `String`, timeout As `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` event will be called with the content received from the server passed to it. > >

> >

> > Note > >

> > 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`. > >

> > 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) > ```

forsearch

URLConnection.SendSync **SendSync**(method As `String`, URL As `String`, file As `FolderItem`, timeout As `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. ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

forsearch

URLConnection.SendSync **SendSync**(method As `String`, URL As `String`, timeout As `Integer` = 0) As `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. > >

> >

> > Note > >

> > 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. > >

> > This method raises a `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) > ```

forsearch

URLConnection.SetRequestContent **SetRequestContent**(content As `String`, mimeType As `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

forsearch

URLConnection.AuthenticationRequested **AuthenticationRequested**(realm As `String`, `ByRef` name As `String`, `ByRef` password As `String`) As `Boolean` > Called when the connection requires HTTP basic authentication. Set the name and password and return `True`. > >

> >

> > Important > >

> > This event is not supported for Android. The `UserName` and `Password` properties must be populated before the connection is made. > >

> > Specify a name and password: > > ``` xojo > name = "MyUserName" > password = "MyPassword" > Return True > ```

forsearch

URLConnection.ContentReceived **ContentReceived**(URL As `String`, HTTPStatus As `Integer`, content As `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.

forsearch

URLConnection.Error **Error**(err As `RuntimeException`) > Called when an HTTP error occurs. > > The ErrorNumber values in the err exception vary by platform. Here are links to errors by platform: > > - [Windows HTTP Errors](https://msdn.microsoft.com/en-us/library/windows/desktop/aa383770(v=vs.85).aspx) > - [macOS NSURLError.h](https://github.com/apportable/Foundation/blob/master/System/Foundation/include/Foundation/NSURLError.h) > - [Linux libsoup status codes](https://libsoup.gnome.org/libsoup-3.0/enum.Status.html) > > Display information about the error: > > ``` xojo > ErrorLabel.Text = e.Reason > ```

forsearch

URLConnection.FileReceived **FileReceived**(URL As `String`, HTTPStatus As `Integer`, file As `FolderItem`) > n a download of a file is completed as a result of calling Send and passing a FolderItem.

forsearch

URLConnection.HeadersReceived **HeadersReceived**(URL As `String`, HTTPStatus As `Integer`) > Called when headers are received from the server.

forsearch

URLConnection.ReceivingProgressed **ReceivingProgressed**(bytesReceived As `Int64`, totalBytes As `Int64`, newData As `String`) > Call periodically as data is received.

forsearch

URLConnection.SendingProgressed **SendingProgressed**(bytesSent As `Int64`, bytesLeft As `Int64`) > Called periodically as data is sent/uploaded. ## Notes Usage on Linux requires libsoup3 with a fallback to libsoup2-4. URLConnection 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 URLConnection on macOS, cookies are shared globally across all sessions. On Windows and Linux they are exclusive to the URLConnection 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 NSAppTransportSecurity NSExceptionDomains firstsite.com NSIncludesSubdomains NSTemporaryExceptionAllowsInsecureHTTPLoads secondsite.com NSIncludesSubdomains NSTemporaryExceptionAllowsInsecureHTTPLoads ``` If you don't know the specific sites, you can request access to everything using a single key: ``` xojo NSAppTransportSecurity NSAllowsArbitraryLoads ``` 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`, `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 |

`Object` parent class; `Using Non-Secure URLs on macOS and iOS`, `Using a plist` topics; [Paw Extension](https://github.com/xojo/Paw-XojoURLConnectionGenerator) on GitHub