Class

URLConnection

Description

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

Properties

Name	Type	Read-Only
AllowCertificateValidation	Boolean
HTTPStatusCode	Integer	✓
Password	String
UserName	String

Methods

Name	Parameters	Returns
ClearRequestHeaders
Disconnect
RequestHeader	name As String	String
	name As String, Assigns value As String
ResponseHeader	name As String	String
ResponseHeaders		Iterator
Send	method As String, URL As String, file As FolderItem, timeout As Integer = 60
	method As String, URL As String, timeout As Integer = 60
SendSync	method As String, URL As String, file As FolderItem, timeout As Integer = 0
	method As String, URL As String, timeout As Integer = 0	String
SetRequestContent	content As String, mimeType As String

Events

Name	Parameters	Returns
AuthenticationRequested	realm As String, ByRef name As String, ByRef password As String	Boolean
ContentReceived	URL As String, HTTPStatus As Integer, content As String
Error	err As RuntimeException
FileReceived	URL As String, HTTPStatus As Integer, file As FolderItem
HeadersReceived	URL As String, HTTPStatus As Integer
ReceivingProgressed	bytesReceived As Int64, totalBytes As Int64, newData As String
SendingProgressed	bytesSent As Int64, bytesLeft As Int64

Property descriptions

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.

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:

Var content As String
content = MyConnection.SendSync("GET", "http://127.0.0.1:8080/GetData", 30)
Var status As Integer = MyConnection.HTTPStatusCode

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.

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

URLConnection.ClearRequestHeaders

ClearRequestHeaders

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

mySocket.ClearRequestHeaders

URLConnection.Disconnect

Disconnect

Disconnects the socket.

A disconnected socket is not set to Nil, but is no longer in a useful state. You should create a new socket rather than attempting to re-use a disconnected socket.

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.

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:

Self.RequestHeader("Authorization") = "MyAPIKey"
mySocket.Send("GET", "http://www.webservice.com/GetData")

URLConnection.ResponseHeader

ResponseHeader(name As String) As String

Gets a response header.

URLConnection.ResponseHeaders

ResponseHeaders As Iterator

Used to iterate over all response headers.

Var connection As New URLConnection
Var headers() As Pair

For Each header As Pair In connection.ResponseHeaders
    headers.AddRow(header.Left : header.Right)
Next

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.

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:

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:

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:

Var outputFile As FolderItem = SpecialFolder.Documents.Child("data.json")
MyConnection.Send("GET", "https://www.mydomain.com/GetData", outputFile)

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.

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.

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:

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:

Var outputFile As FolderItem = SpecialFolder.Documents.Child("data.json")
MyConnection.SendSync("GET", "https://www.mydomain.com/GetData", outputFile, 30)

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:

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:

' 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

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:

name = "MyUserName"
password = "MyPassword"
Return True

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.

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:

Display information about the error:

ErrorLabel.Text = e.Reason

URLConnection.FileReceived

FileReceived(URL As String, HTTPStatus As Integer, file As FolderItem)

Called when a download of a file is completed as a result of calling Send and passing a FolderItem.

URLConnection.HeadersReceived

HeadersReceived(URL As String, HTTPStatus As Integer)

Called when headers are received from the server.

URLConnection.ReceivingProgressed

ReceivingProgressed(bytesReceived As Int64, totalBytes As Int64, newData As String)

Call periodically as data is received.

URLConnection.SendingProgressed

SendingProgressed(bytesSent As Int64, bytesLeft As Int64)

Called periodically as data is sent/uploaded.

Notes

Usage on Linux requires libsoup 2.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 page.

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

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

All project types on all supported operating systems.

URLConnection

Description

Properties

Methods

Events

Property descriptions

Method descriptions

Event descriptions

Notes

Standard Method Definitions

macOS information (app transport security)

Compatibility

See also