Retrieve data from the server and store it in a local buffer.

Syntax

object.GetData( Resource, Buffer, [Length], [Options] )

Parameters

Resource

A string that specifies the resource on the server that will be accessed. If the resource specifies a file, then the contents of the file will be returned to the server. If the resource specifies a script or other executable content, it will be executed and the output will be transferred to the local system. The file pathing and name conventions must be that of the server.

Buffer

This parameter specifies the local buffer that the data will be stored in. If the variable is a String type, then the data will be returned as a string of characters. This is the most appropriate data type to use if the file on the server is a text file. If the remote file contains binary data, it is recommended that a Byte array variable be specified as the argument to this method.

Length

An optional integer argument that will contain the number of bytes copied into the buffer when the method returns.

Options

An optional integer value which specifies one or more options. This argument is constructed by using a bitwise operator with any of the following values:

Value	Description
httpTransferDefault	The default transfer mode. The resource data is downloaded to the local system exactly as it is stored on the server. If you are requesting a text-based resource, the data may use a different end-of-line character sequence. For example, the end-of-line character may be a single linefeed character instead of a carriage return and linefeed pair.
httpTransferConvert	If the resource being downloaded from the server is textual, the data is automatically converted so that the end of line character sequence is compatible with the Windows platform. Individual carriage return or linefeed characters are converted to carriage return/linefeed character sequences.
httpTransferCompress	This option informs the server that the client is willing to accept compressed data. If the server supports compression for the specified resource, then the data will be automatically expanded before being returned to the caller. This option is selected by default if compression has been enabled by setting the Compression property to True.
httpTransferErrorData	This option causes the client to accept error data from the server if the request fails. If this option is specified, an error response from the server will not cause the method to fail. Instead, the response is returned to the client and the method will succeed.

Return Value

A value of zero is returned if the operation was successful, otherwise a non-zero error code is returned which indicates the cause of the failure.

Remarks

The GetData method transfers data from the server to the local system, storing it in the specified buffer . This method will cause the current thread to block until the file transfer completes, a timeout occurs or the transfer is canceled. During the transfer, the OnProgress event will fire periodically, enabling the application to update any user interface objects such as a progress bar.

When encountering a server error during a request, the GetData method normally returns an error code, and no data is copied into the caller-provided buffer. The error code reflects the general cause of the failure, allowing the application to handle this error condition appropriately. Additionally, servers may provide further details about the failure, such as XML or JSON formatted data containing specific error codes or diagnostic messages.

To capture this error information, you can utilize the httpTransferErrorData option. When this option is enabled, the behavior of GetData changes; it does not return an error code for server error statuses. Instead, any error data provided in the server's response, regardless of its format, is copied into the buffer provided by the caller. If this option is used, your application should check the ResultCode property to obtain the HTTP status code returned by the server. This will enable you to determine if the operation was successful.

Specifying the httpTransferCompress option does not guarantee that the data returned by the server will actually be compressed, it only informs the server that the client is willing to accept compressed data. Whether or not a particular resource is compressed depends on the server configuration, and the server may decide to only compress certain types of resources, such as text files.

If compression has been enabled and the server returns compressed data, it will be automatically expanded before being returned to the caller. If the application is using the OnProgress event to determine the amount of data being returned by the server, it is important to keep in mind that the values reflect the size of the compressed data.

See Also

Compression Property, GetFile Method, PutData Method, PutFile Method, OnProgress Event

Copyright © 2024 Catalyst Development Corporation. All rights reserved.