Submits the contents of the specified buffer to a script on the server.

Syntax

object.PostData( Resource, ResourceData, Buffer, [Options] )

Parameters

Resource

A string that specifies the resource that the data will be posted to on the server. Typically this is the name of an executable script.

ResourceData

A string or byte array that contains the data which will be provided to the script. If the script expects binary data, it is recommended that a byte array be used.

Buffer

A string or byte array that will contain the output generated by the script. Typically this is HTML content which is generated by the script as a result of processing the data that was posted to it.

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
httpPostDefault	The default post mode. The contents of the buffer are encoded and sent as standard form data. The data returned by the server is copied to the result buffer exactly as it is returned from the server.
httpPostConvert	If the data being returned from the server is textual, it 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. Note that this option does not have any effect on the form data being submitted to the server, only on the data returned by the server.
httpPostMultipart	The contents of the buffer being sent to the server consists of multipart form data. This causes the Content-Type request header field to be set to multipart/form-data and the contents of the buffer will be sent as-is without any encoding.
httpPostErrorData	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 PostData method uses the POST command to submit the contents of the specified buffer to a script on the server and returns the result in a string or byte array provided by the caller. This method will cause the current thread to block until the operation completes, a timeout occurs or the post is canceled. During the operation, 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 PostData 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. If the POST request fails, servers may also 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 httpPostErrorData option. When this option is enabled, the behavior of PostData 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 result buffer provided by the caller. If this option is used, your application should check the value of the ResultCode property to obtain the HTTP status code returned by the server. This will enable you to determine if the operation was successful.

If you need to submit XML formatted data to the server for processing, it is recommended that you use the PostXml method. There is also a PostJson method for submitting JSON formatted data. Both methods ensure that the data is sent to the server using the correct content type and encoding.

See Also

GetData Method, GetFile Method, PatchData Method, PostFile Method, PostJson Method, PostXml Method, PutData Method, PutFile Method, OnProgress Event

Copyright © 2024 Catalyst Development Corporation. All rights reserved.