---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
` event to fire with an error number 107 unless the application is running with administrative permissions. This is due to security features built into the underlying OS.
You need to set the port property explicitly before any call to Listen or Connect as the Port property will be modified to reflect what the actual bound port is during the various stages of operation.
For instance, if you listen on port 8080 and a connection comes in, you can check the Port property to ensure that you're still listening on port 8080 (that the port hasn't been hijacked). Or, if you connect to a socket on port 8080, once the connection occurs, you can check to see what port the OS has bound you to. This will be a random-seeming port number.
This trick can be very useful when you do things like Listen on port 0. In that case, the OS will pick a port for you and listen on it. Then you can check the Port property to see which port the OS picked. This functionality is used for various protocols, such as FTP.
This example sets the Port to 8080.
``` xojo
TCPSocket1.Port = 8080
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.RemoteAddress
**RemoteAddress** As `String`
The address of the remote machine you are connected to.
This property is read-only.
Use this instead of the Address property to determine the address of the machine you are actually connected to.
This example reports the address of the remote machine that the user is connected to. It is in the Connected event.
``` xojo
TextField1.Text = Me.RemoteAddress
```
forsearch
HTTPSocket.RequestHeaders
**RequestHeaders** As `InternetHeaders`
Request headers are sent to the server along with the action (GET, POST, etc.). They can contain data that the server might use to process your request. Some examples of common request headers are for things such as referring pages, the client name, OS CPU, and so forth.
The default headers are:
Accept:*/*
Accept-Language:en
Connection:close
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Yield
**Yield** As `Boolean`
When you are using synchronous HTTP, your application may need to wait a noticeable amount of time to get or post a page. Setting *Yield* to `True` allows for events and other code to execute while waiting for a page. *Yield* is relevant when you pass the optional *Timeout* parameter with Get or GetHeaders. Set *Yield* to `True` just prior to a call to any of these methods.
## Method descriptions
forsearch
HTTPSocket.ClearRequestHeaders
**ClearRequestHeaders**
Clears all of the set request headers. See the description of the SetRequestHeaders method for information on headers.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Close
**Close**
Closes the socket's connection, closes any connections the socket may have, and resets the socket.
The only information that is retained after calling Close is the socket's port, address (in the case of `TCPSockets`), LastErrorCode properties, and data left in the socket's receive buffer. All other information is discarded.
This example closes the `EasyTCPSockets` that were open. The sockets were added to the main window.
``` xojo
Connector.Close
Listener.Close
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Connect
**Connect**
Attempts to connect.
For `TCPSockets`, the address and port properties must be set. For `UDPSockets`, the port property must be set. The Connect method binds a socket to a port. After calling Connect, the Port property will report the actual port you are bound to.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Disconnect
**Disconnect**
Disconnects the socket, resets it, and fires a `SocketCore` Error event with a 102 error to let you know that the socket has been disconnected.
This example disconnects the `EasyTCPSockets` that were opened.
``` xojo
Connector.Disconnect
Listener.Disconnect
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.EncodeFormData
**EncodeFormData**(Form As `Dictionary`) As `String`
Takes the key/value pairs from the passed `Dictionary` and formats them into a URL-encoded `String`. The result can then be used in the URL to send data to a form with a GET action or as content for a POST.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.EndOfFile
**EndOfFile** As `Boolean`
Returns `True` when there's no more data left to read.
This code reads the rows and columns of data from a tab-delimited text file into a `ListBox`:
``` xojo
Var f As FolderItem
Var textInput As TextInputStream
Var rowFromFile As String
f = FolderItem.ShowOpenFileDialog("text/plain") ' defined as a FileType
If f <> Nil Then
textInput = TextInputStream.Open(f)
textInput.Encoding = Encodings.UTF8
Do
rowFromFile = textInput.ReadLine
Var values() As String = rowFromFile.Split(Chr(9))
ListBox1.ColumnCount = values.Count
ListBox1.AddRow("")
Var col As Integer
For Each value As String In values
ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, col) = value
col = col + 1
Next
Loop Until textInput.EndOfFile
textInput.Close
End If
```
This example reads each pair of bytes from a file and writes them in reverse order to a new file. The user chooses the source file using the Open-file dialog box and saves the new file using the Save as dialog box. The EOF property is used to terminate the `Do...Loop`.
``` xojo
Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text")
If readFile <> Nil Then
Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
ReadStream.LittleEndian = True
Var writeFile As FolderItem = FolderItem.ShowSaveFileDialog("", "")
If writeFile <> Nil Then
Var writeStream As BinaryStream = BinaryStream.Create(writeFile, True)
writeStream.LittleEndian = True
Do Until ReadStream.EndOfFile
writeStream.WriteInt8(ReadStream.ReadInt8)
Loop
writeStream = Nil
End If
readStream = Nil
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Flush
**Flush**
Immediately sends the contents of internal write buffers to disk or to the output stream.
This function can be useful in point-to-point communication over sockets and similar connections: To optimize for transmission performance, some types of output streams try to collect small pieces of written data into one larger piece for sending instead of sending each piece out individually. By calling Flush, the data collection is stopped and the data is sent without further delay, reducing latency.
When using this on a stream that ends up as a file on disk, it is useful, too: Any short parts of previously written data are written to disk right away, ensuring the data is actually on disk if the application terminates abruptly, e.g. due to a crash.
Avoid calling this method too often. For example, do not call it between successive Write calls because you'll slow down performance without getting much benefit.
A typical use case would look like this:
``` xojo
mySocket.Write("you typed: ")
mySocket.Write(key)
mySocket.Write(".")
mySocket.Flush
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Get
**Get**(URL As `String`)
Synchronously downloads the content from the URL directly to the `FolderItem`. When the download has finished, `True` is returned if successful, `False` if there was an error. *Timeout* is the number of seconds to wait for the result. `ErrorCode` is -1 if the *Timeout* value is reached.
For the synchronous version of these methods, set the Yield property to `True` to allow for background activities while waiting.
forsearch
HTTPSocket.GetHeaders
**GetHeaders**(URL As `String`)
Synchronously Requests only the page headers from the specified URL. The headers are return as an `InternetHeaders`.
When running synchronously, set the `Yield` property to `True` to allow for background activities while waiting.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Listen
**Listen**
Attempts to listen for incoming connections on the currently specified port.
After calling Listen, the Port property will report the actual port you are bound to.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Lookahead
**Lookahead**(\[Encoding As `TextEncoding`\]) As `String`
Returns a `String`, containing the data that is available in the internal queue without removing it.
The optional *Encoding* parameter enables you to specify the text encoding of the data to be returned. The default is `Nil`. Use the `Encodings` module to specify an encoding.
This example adds the contents of the internal queue to a `TextArea`. The Listener `EasyTCPSocket` has been added to the window.
``` xojo
TextArea1.AddText(listener.Lookahead)
```
forsearch
HTTPSocket.PageHeaders
**PageHeaders** As `InternetHeaders`
Provides access to the headers received from the server. This can be used to access the headers in synchronous mode.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Poll
**Poll**
Polls the socket manually, which allows a socket to be used synchronously.
The `EasyTCPSocket` "Listener" has been added to the window.
``` xojo
Listener.Poll
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Post
**Post**(URL As `String`)
Synchronously issues a POST command to the URL and downloads the response directly to the FolderItem. When the download has finished, `True` is returned if successful, `False` if there was an error. *TimeOut* is the number of seconds to wait for the result.
For the synchronous versions of this method, set the `Yield` property to `True` to allow for background activities while waiting.
This example does a synchronous POST to a service that returns what you POSTed to it as JSON:
``` xojo
Var d As New Dictionary
d.Value("Test") = "TestValue"
d.Value("Value2") = "Testing"
Socket.SetFormData(d)
' This service returns the post data as the result
Var result As String
result = Socket.Post("http://httpbin.org/post", 30) ' Synchronous
result = DefineEncoding(result, Encodings.UTF8)
MessageBox(result)
```
To do this asynchronous, call Post without a timeout:
``` xojo
Var d As New Dictionary
d.Value("Test") = "TestValue"
d.Value("Value2") = "Testing"
Socket.SetFormData(d)
' This service returns the post data as the result
Socket.Post("http://httpbin.org/post")
```
The results will be available in the PageReceived event handler in the content parameter.
``` xojo
Sub PageReceived(url As String, httpStatus As Integer, headers As InternetHeaders, content As String)
Var data As String
data = DefineEncoding(content, Encodings.UTF8)
ResultArea.Value = data
End Sub
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Purge
**Purge**
Removes all data from the socket's internal receive buffer. It does not affect the socket's internal send buffer.
``` xojo
Listener.Purge
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Read
**Read**(Count As `Integer`, \[Enc As `TextEncoding`\]) As `String`
Reads *Count* bytes from the input stream and returns a `String`.
If provided, the optional parameter *Enc* specifies the text encoding to be defined for the `String` to be read.
If *Count* is higher than the amount of bytes currently available in the stream, all available bytes will be returned. Therefore, make sure to always consider the case that you get less than you requested. To see if you received all requested bytes, check the returned string's `String.Bytes` property (avoid using `Length` as it may give a different number if the encoding is not nil).
If not enough memory is available, you get back an empty string.
This example reads the first 1000 bytes from a `BinaryStream`.
``` xojo
Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text/plain")
If readFile <> Nil Then
Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
ReadStream.LittleEndian = True
TextArea1.Text = ReadStream.Read(1000, Encodings.UTF8)
End If
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.ReadAll
**ReadAll**(\[Encoding As `TextEncoding`\]) As `String`
Reads all the data from the internal buffer.
This example reads all the data in the buffer into a `TextArea`.
``` xojo
TextField1.AddText(listener.ReadAll)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.SendRequest
**SendRequest**(Method As `String`, URL As `String`, Timeout As `Integer`) As `String`
Allows the user to synchronously send a request using an HTTP method other than GET or POST. Supply the method as a `String`, URL as a `String` and a `FolderItem`. Return a `Boolean` to indicate if it was successful. Data is saved to the FolderItem.
Common others methods are OPTIONS, HEAD, PUT, DELETE, TRACE and CONNECT as per RFC 2616 describing the HTTP 1.1 protocol.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.SetFormData
**SetFormData**(Form As `Dictionary`)
Takes the key/value pairs from the passed `Dictionary` and converts it to a URL-encoded `String`.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.SetPostContent
**SetPostContent**(Content As `String`, ContentType As `String`)
Sets the content data and content type to be sent to the server for a POST command.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.SetRequestContent
**SetRequestContent**(Content As `String`, ContentType As `String`)
Sets the content data and content type to be sent to the server for any command except HEAD.
If you will be reusing a socket without using the `New` operator, you must clear this value for requests that do not have content associated with them. For instance, If you do a POST with content followed by a GET that should not have content, you should set the content to an empty string.
Set request content:
``` xojo
Dim data As String = "ID=1234"
MySocket.SetRequestContent(data, "application/x-www-form-urlencoded")
```
forsearch
HTTPSocket.SetRequestHeader
**SetRequestHeader**(Name As `String`, Value As `String`)
Sets the value of a request header.
Request headers are sent to the server along with the action (GET, POST, etc.). They can contain data that the server might use to process your request. Some examples of common request headers are for things such as referring pages, the client name, OS CPU, and so forth.
This example changes the user agent:
``` xojo
HTTPSocket1.SetRequestHeader("User-Agent:", "CustomUserAgentString")
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Write
**Write**(Data As `String`)
Writes the passed data to the output stream.
Note that in order to make sure that the data actually ends up on disk or gets sent to the socket it is connected to, the stream must either get closed or the `Flush` method be called. Otherwise, the data, if small, may end up temporarily in a write buffer before either a certain time has passed or more data is written. This buffering increases performance when writing lots of small pieces of data, but may be causing unwanted delays when another process, e.g. the other end of a socket connection, is waiting for the data. Consider calling the `Flush` method to reduce latencies that this buffering may cause in such cases.
If Write fails, an `IOException` will be raised.
This example displays the Save As dialog box and writes the contents of the TextArea1 to a text file.
``` xojo
Var f As FolderItem
Var stream As BinaryStream
f = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Untitled.txt")
If f<> Nil Then
stream = BinaryStream.Create(f, True)
stream.Write(TextArea1.Text)
stream.Close
End If
```
## Event descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.AuthenticationRequired
**AuthenticationRequired**(Realm As `String`, Headers As `InternetHeaders`, `ByRef` Name As `String`, `ByRef` Password As `String`) As `Boolean`
Executes when a site that requires authentication connects. AuthenticationRequired also supports Digest authentication.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.Connected
**Connected**
Executes when the connection is established with the server.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.DownloadComplete
**DownloadComplete**(URL As `String`, HTTPStatus As `Integer`, Headers As `InternetHeaders`, File As `FolderItem`)
Executes when a download is complete after using the Get or Post methods and passing the optional parameter. URL contains the URL that was downloaded. *File* is the `FolderItem` the data was downloaded to, and *Headers* is a dictionary of the HTTP headers that were returned by the server. The HTTPStatus code is also passed to this event. These codes are used for messages such as "Page not found" (error 404), and so forth.
forsearch
HTTPSocket.HeadersReceived
**HeadersReceived**(Headers As `InternetHeaders`, HTTPStatus As `Integer`)
Executes when the headers have been retrieved from the server.
forsearch
HTTPSocket.PageReceived
**PageReceived**(URL As `String`, HTTPStatus As `Integer`, Headers As `InternetHeaders`, Content As `String`)
Executes when a new page has been retrieved from the server. It provides the URL that was requested and the HTTP headers from the web server. The HTTPStatus code is also passed to this event. These codes are used for messages such as "Page not found" (error 404), and so forth.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.ProxyAuthenticationRequired
**ProxyAuthenticationRequired**(Realm As `String`, Headers As `InternetHeaders`, `ByRef` Name As `String`, `ByRef` Password As `String`) As `Boolean`
Executes when a site that requires via proxy authentication connects. ProxyAuthenticationRequired also supports Digest authentication.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.ReceiveProgress
**ReceiveProgress**(BytesReceived As `Integer`, TotalBytes As `Integer`, NewData As `String`)
Provides the current number of bytes received and the total number of bytes (if available). It executes periodically during the download process.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
HTTPSocket.SendProgress
**SendProgress**(BytesSent As `Integer`, BytesLeft As `Integer`)
Occurs when your network provider queues your data in chunks and is about to send the next chunk.
The parameters indicate the amount of progress that has been made during the send. Returns a `Boolean`.
Returning `True` from this event causes the send to be cancelled. This does not close the socket's connection; it only clears the buffer. After all of the data has been transferred you will get a final SendProgress event followed by a `SendComplete` event.
*bytesSent* is the number of bytes that were sent in the chunk, not the total number of bytes sent.
## Notes
Note
If you need HTTP 1.1 support, use `URLConnection` instead.
Use the HTTPSocket class to send and receive data via the HTTP protocol. Since this is a subclass of the `TCPSocket` class, all the standard socket APIs are also available. To perform secure communications (via HTTPS), use the `URLConnection` class instead. It is otherwise identical, except that it is subclassed from `SSLSocket` instead of `TCPSocket`. This makes all the options for encrypted communications available to `URLConnection` objects.
If you use a constructor in a subclass of HTTPSocket, you must call the super class's constructor in your subclass's constructor. The subclass fail when you try to download.
When using the optional Timeout parameter of the Get or GetHeaders methods the page will be received or posted in a synchronous manner. That is, your app will wait until the page has been received or posted before it proceeds. If Timeout is set to zero, the socket will wait indefinitely or until it receives an error.
To use synchronous mode, pass the optional parameter. For example,
``` xojo
Dim http As New HTTPSocket
MsgBox(http.Get("http://www.example.com", 30))
```
When using synchronous mode, you can set the Yield property to `True` to tell the socket to yield time to other events and code to execute while waiting. Insert a statement such as:
``` xojo
http.Yield = True
```
to allow background processes to execute while waiting.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### App transport security
Starting with OS X 10.11 and 2018r4, your apps 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". You can work around this by providing a plist with your app to indicate what non-secure URLs you are using. For more information:
- `Using Non-Secure URLs on macOS and iOS`
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### Xojo cloud
Web apps running on Xojo Cloud first have to use the `FirewallPort` class to open the port used to connect to an outside web server.
## Sample code
The following example retrieves the specified URL synchronously:
``` xojo
Dim socket1 As New HTTPSocket
Dim data As String = socket1.Get("http://www.example.com/", 30)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
For asynchronously transfers you need to subclass HTTPSocket, call get without timeout parameter and get result in `PageReceived` event.
The following example posts a simple form:
``` xojo
Dim form As Dictionary
Dim socket1 As New HTTPSocket
' create and populate the form object
form = New Dictionary
form.Value("firstname") = "Bob"
form.Value("lastname") = "Brown"
' setup the socket to POST the form
socket1.SetFormData(form)
socket1.Post("http://www.myformlocation.com/form.php")
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
To send one or more cookies with an HTTP request:
``` xojo
socket.SetRequestHeader("Cookie", Join(Array(cookie1, cookie2), "; "))
```
## Compatibility
All project types on all supported operating systems.
## See also
`TCPSocket` parent class; `URLConnection`, `URLConnection`, `SocketCore`, `TCPSocket`, `URLConnection` classes.