Write data to the server.

Syntax

object.Write( Buffer, [Length] )

Parameters

Buffer

A buffer variable that contains the data to be written to the server. If the variable is a String type, then the data will be written as a string of characters. This is the most appropriate data type to use if the server expects text data that consists of printable characters. If the string contains Unicode characters, it will be automatically converted to use standard UTF-8 encoding prior to being sent. If you wish to send the data without conversion, use a Byte array as the buffer instead of a String variable.

Length

A numeric value which specifies the number of bytes to write. Its maximum value is 2³¹-1 = 2147483647. If a value is specified for this argument and it is greater than the actual size of the buffer, then the Length argument will be ignored and the entire contents of the buffer will be written. If the argument is omitted, then the maximum number of bytes to write is determined by the size of the buffer.

Return Value

This method returns the number of bytes actually written to the server, or -1 if an error was encountered.

Remarks

The Write method sends the data in buffer to the server. If the connection is buffered, as is typically the case, the data is copied to the send buffer and control immediately returns to the program. If the control is blocking, the application will wait until the data can be sent. If the control is non-blocking and the write fails because it could not send all of the data to the server, the OnWrite event will be fired when the server can accept data again.

If the Write method is used to send the message contents to the server, the application must first call the CreateMessage method to specify the sender and the length of the message, followed by one or more calls to the AddRecipient method to specify each recipient of the message. When all of the message text has been submitted to the server, the application must call the CloseMessage method.

The message text is filtered by the Write method, and it will automatically normalize end-of-line character sequences to ensure the message meets the protocol requirements. The message itself must be in a standard RFC 822 or multi-part MIME message format, or the server may reject the message. Binary data, such as file attachments, should always be encoded. The MailMessage control can be used to compose and export a message in the correct format, which can then be submitted to the server.

It is recommended that most applications use the SendMessage method, which submits the message in a single method call.

See Also

AddRecipient Method, CloseMessage Method, CreateMessage Method, SendMessage Method

Copyright © 2023 Catalyst Development Corporation. All rights reserved.