3144:The DocInput Object: Properties and Methods
KEYWORDS: DocInput Internet state AREA: General
The DocInput Object is an object from the NetMasters
Internet Solutions Pack deployed with Delphi 2.01.
It descibes the input information for a document
being transferred to the control. All of the internet
controls in the suite that can receive a doc use
this object as a property. The DocInput Object has
the following properties:
BytesTotal, BytesTransferred, DocLink, FileName,
Headers, PushStreamMode, State and Suspended.
BytesTotal is the total byte count of the item to be
transmitted. The default or initial value is zero.
The data type is a Long. It is a runtime and read
only property. This value is obtained from the header
property content-length. This value is used by the
control to determine the amount of information to be
transferred. It is also accessible to you to manage the
buffer that you will use to re-assemble the data after
transfer.
The BytesTransferred property is a property given to you
inside the OnDocInput event. It is a runtime read only
property that is of type long. It is set to zero when a new
transfer begins. It is updated at the beginning of the
OnDocInput Event. This value will reflect the value of the
last transfer when no other transfer is in progress. The
BytesTransferred property can be used to show progress on
a progress bar or to confirm that the actual amount transferred
corresponds to that which is expected.
The DocLink property tells the receiving control that the
source of the document will not be a sent via data streaming
or via an input file. It references a DocOutput.DocLink property
which becomes the source of data in the transfer. This property
is a read/write property that is runtime only. The property is
of type DocLink. It is a string type and the defaultvalue is ''.
When the DocLink property is set to a value other than '', the
FileName property is automatically set to ''. This property is
used to specify a source that is an internet control that has a
DocOutput.DocLink property set to correspond with it (i.e. they
are used in pairs).
The FileName property is a read/write runtime only property that
is of type string. It' default value is''. It must be a valid
filename. This property can be set by passing it as an argument
to a DocInput object. If this property is set to a value other
than '', then the DocLink property is set to ''.
The Headers property is a runtime readonly property. The
"headers"is a collection of DocHeader items that define the doc
being transferred. The contents of the headers property should
be modified before calling the GetDoc method. Each DocHeader
represents a MultiPurpose Internet Mail Extension(MIME). Mime is
the mechanism for specifying and describing the format of
Internet Message Bodies. (See rfc1341 for details). The headers
used depend on the protocol used but two are common to all
protocols:
1. content-type
content type indicates the MIME specification of the
ensuing document. "text/plain" is an example of this.
2. content-length
content length indicates the size of the documents in
bytes.
The state property is a runtime read only property of the
enumerated type DocStateConstants. The default value is
icDocNone. The state property is updated by the control itself
each time the DocInput event is activated.
The suspended property is a runtime read only property that is of
type boolean. It is set by calling the suspend method. If it is
set to true transfer is suspended.
The PushStream property is a read/write, runtime only property
that is of the type boolean. The default value is false. If the
FileName or DocLink properties are set to values other than ''
then the PushStream property is not accessible.
The DocInput object has 4 methods:
GetData, PushStream, SetData and Suspend.
The GetData method tells the DocInput object to retrieve the
current block of data when the DocOutput event is activated. This
method can only be called during the OnDocInput event and only
when the State property is set to icDocData(3). When using the
FileName or DocLink properties this method may be used to examine
data during transfer.
The PushStream method should only be called when the
PushStreamMode has been set to true and when data is available.
PushStream sets the State property based on the next step of the
document transfer and activates the DocInput event when
appropriate. It then returns to wait for the next call to
PushStream. SetData chould be called before calling PushStream.
The SetData method specifies the next data buffer to be
transferred when the DocInput event is activated. SetData is
called during a DocInput event or before calling SendDoc. If it
is used before calling SendDoc then it is an alternative to
sending the InputData parameters to InputData. The type should be
specified as a variant.
The Suspend method takes the form suspend(true) or
suspend(false). If the method has been called true twice then it
must be called false twice to resume transfer.
This is some example code on how to use the DocInput Object.
The full program that this code is from can be seen in the demos
sub directory of the Delphi 2.01 CD-Rom. The project name is
SimpMail.dpr. This example is a great exapmle of using the
headers property of the object. The DocInput event also shows
proper use and testing of the State property.
{Clear and repopulate MIME headers, using the component's
DocInput property. A separate DocInput OLE object could also be
used. See RFC1521/1522 for completeinformation on MIME types.}
procedure TMainForm.CreateHeaders;
begin
with SMTP1 do
begin
DocInput.Headers.Clear;
DocInput.Headers.Add('To', eTo.Text);
DocInput.Headers.Add('From', eHomeAddr.Text);
DocInput.Headers.Add('CC', eCC.Text);
DocInput.Headers.Add('Subject', eSubject.Text);
DocInput.Headers.Add('Message-Id', Format('%s_%s_%s',
[Application.Title,DateTimeToStr(Now), eHomeAddr.Text]));
DocInput.Headers.Add('Content-Type',
'TEXT/PLAIN charset=US-ASCII');
end;
end;
{Send a simple mail message}
procedure TMainForm.SendMessage;
begin
CreateHeaders;
with SMTP1 do
SendDoc(NoParam, DocInput.Headers, reMessageText.Text, '',
'');
end;
{Send a disk file. Leave SendDoc's InputData parameter blank and
specify a filename for InputFile to send the contents of a disk
file. You can use the DocInput event and GetData methods to do
custom encoding (Base64, UUEncode, etc.) }
procedure TMainForm.SendFile(Filename: string);
begin
CreateHeaders;
with SMTP1 do
begin
DocInput.Filename := FileName;
SendDoc(NoParam, DocInput.Headers, NoParam,
DocInput.FileName, '');
end;
end;
{The DocInput event is called each time the DocInput state
changes during a mail transfer. DocInput holds all the
information about the current transfer, including the headers,
the number of bytes transferred, and the message data itself.
Although not shown in this example, you may call DocInput's
SetData method if DocInput.State = icDocData to encode the data
before each block is sent.}
procedure TMainForm.SMTP1DocInput(Sender: TObject;
const DocInput: Variant);
begin
case DocInput.State of
icDocBegin:
SMTPStatus.SimpleText := 'Initiating document transfer';
icDocHeaders:
SMTPStatus.SimpleText := 'Sending headers';
icDocData:
if DocInput.BytesTotal > 0 then
SMTPStatus.SimpleText :=
Format('Sending data: %d of %d bytes (%d%%)',
[Trunc(DocInput.BytesTransferred),
Trunc(DocInput.BytesTotal),
Trunc(DocInput.BytesTransferred/DocInput.BytesTotal*100)])
else
SMTPStatus.SimpleText := 'Sending...';
icDocEnd:
if SMTPError then
SMTPStatus.SimpleText := 'Transfer aborted'
else
SMTPStatus.SimpleText := Format('Mail sent to %s
(%d bytes data)',
[eTo.Text,Trunc(DocInput.BytesTransferred)]);
end;
SMTPStatus.Update;
end;
TI
LiveJournal
PhotoFile