3145:The DocOutput Object: Properties and Methods
KEYWORDS: DocOutput NetMasters Internet OnDocOutput state AREA: General
The DocOutput Object is an object from the NetMasters
Internet Solutions Pack deployed with Delphi 2.01.
It describes the output information for the
document being transferred. All controls with the DocOutput
property use this type. This is also the object that is the
referenced in the DocOutput event. The DocOutput object has the
following properties:
BytesTotal, BytesTransferred, DocLink,
FileName, Headers, PushStreamMode, State and Suspend.
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 OnDocOutput 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
OnDocOutput 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 sending control that the
source of the document will not be a sent via data streaming
or via an input file. It references a DocInput.DocLink property
which becomes the destination 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 default
value 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 DocInput.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. Its 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 read only 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 DocOutput 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 DocOutput object has three methods:
GetData, SetData and Suspend.
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 SetData method specifies the next data buffer to be
transferred when the DocOutput event is activated. SetData is
called during a DocOutput 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.
The example code shown here is from the example program in the
Delphi 2.01 demos\internet sub directory. The project name is
HTTPDemo.dpr. This project is an example of the BytesTransferred
property of the object, as well as the use and testing of the
state property. This project also shows the use of the variant
data type that was new to Delphi 2.01. This data type is
important to OLE and users should learn it ASAP if they want to
be a success in an OLE development environment.
procedure TForm1.HTTP1DocOutput(Sender: TObject;
const DocOutput: Variant);
var
S: String;
i: integer;
MsgNo, Header: String;
Parser: TSimpleHTMLParser;
ALine: String;
begin
Statusbar1.Panels[2].Text :=
Format('Bytes: %s',[DocOutput.BytesTransferred]);
case DocOutput.State of
icDocBegin:
begin
Memo1.Lines.Clear;
Data := '';
end;
icDocData:
begin
DocOutput.GetData(S, VT_BSTR);
Data := Data + S;
end;
icDocEnd:
begin
{ Now remove all the HTML tags and only display the text
}
Parser := TSimpleHTMLParser.Create(Data);
ALine := '';
while Parser.FToken <> etEnd do
begin
case Parser.FToken of
etHTMLTag:
begin
if Parser.TokenHTMLTagIs('BR') then
ALine := ALine + #13#10;
if Parser.TokenHTMLTagIs('P') then
ALine := ALine + #13#10#13#10;
end;
etSymbol: ALine := ALine + ' ' + Parser.FTokenString;
etLineEnd:
begin
Memo1.Lines.Add(ALine);
ALine := '';
end;
end;
Parser.NextToken;
end;
Memo1.Lines.Add(ALine);
Memo1.SelStart := 0;
SendMessage(Memo1.Handle, EM_ScrollCaret, 0, 0);
end;
end;
Refresh;
end;
TI
LiveJournal
PhotoFile