Тема: Объект DocOutput: свойства и методы

Объект DocOutput - объект из пакета Internet Solutions Pack фирмы NetManage, поставляемого в составе Delphi 2.01. Он описывает выходную информацию передаваемого документа. Все элементы управления, имеющие свойство DocOutput, используют этот тип. Он также является объектом, на который указывает событие DocOutput. Объект DocOutput имеет следующие свойства:

BytesTotal, BytesTransferred, DocLink, FileName, Headers, PushStreamMode, State и Suspend.

BytesTotal - счетчик общего количества байт передаваемого элемента. Значение по умолчанию и начальное значение равно нулю. Тип данных - Long. Данное свойство времени выполнения и только для чтения. Значение данного свойства получается из свойства заголовка "content-length" (длина содержимого). Это значение используется элементом управления для определения размера (объема) передаваемой информации. С помощью него также возможно управление буфером, который вы используете для "сборки" данных после их передачи.

Свойство BytesTranferred является свойством, передаваемым вам при наступлении события OnDocInput. Данное свойство времени выполнения, только для чтения и имеет тип long. При начале новой передачи значение свойства обнуляется. Обновляется в начале события OnDocInput. Значение данного свойства отражает величину последней передачи, когда другие передачи не осуществлялись. Свойство BytesTransferred может использоваться для показа линейки прогресса или для утверждения того, насколько фактически переданный размер соответствует ожидаемому.

Свойство DocLink сообщает получающему элементу управления о том, что источник не будет посылать документ через поток данных или входной файл. Оно ссылается на свойство DocOutput.DocLink, которое становится источником при передаче данных. Данное свойство является read/write-свойством (для чтения и записи) и доступно только во время выполнения программы. Свойство имеет тип DocLink. Это строковый тип, имеющий значение по умолчанию ''. Если значению данного свойства присваивается величина, отличная от '', свойство FileName автоматически устанавливается в ''. Данное свойство используется для определения источника, являющегося internet-компонентом с указывающим на объект свойством DocOutput.DocLink, т.е. они используются в парах.

Свойство FileName является read/write-свойством (для чтения и записи) только времени выполнения и имеет строковый тип. Значение по умолчанию ''. Это должно быть правильным именем файла. Данное свойство может быть установлено при его передаче в качестве аргумента объекту DocInput. Если значению данного свойства присваивается величина, отличная от '', свойство DocLink автоматически устанавливается в ''.

Свойство Headers является свойстом только для чтения и времени выполнения. "headers" - коллекция элементов DocHeader, которые определяют передаваемый документ. Содержимое свойства headers должно быть изменено перед вызовом метода GetDoc. Каждый DocHeader представляет собой MultiPurpose Internet Mail Extension (MIME). Mime является механизмом для определения и описания формата тела сообщения Интернет (Internet Message Bodies). (Для получения дополнительной информации смотри документ rfc1341). Используемые headers (заголовки) зависят от используемого протокола, но существуют два заголовка, независимые от протокола:

1. content-type (тип содержимого)
   content type указывает спецификацию MIME для следующего за заголовком документа. Примером этого является "text/plain".
2. content-length (размер содержимого)
   content length указывает размер документа в байтах.

Свойство suspended является свойством только для чтения и времени выполнения, и имеет логический тип. Устанавливается вызывом метода suspend. При установке значения, равного True, передача приостанавливается.

Свойство PushStream является read/write-свойством (для чтения и записи) только времени выполнения и имеет логический тип. Значение по умолчанию - False. Если свойству FileName или DocLink присваивается значение, отличное от '', то свойство PushStream становится недоступным.

Объект DocOutput имеет три метода: GetData, SetData и Suspend.

Метод GetData сообщает объекту DocInput об извлечении текущего блока данных в момент наступления события DocOutput. Данный метод может быть вызван только в течение события OnDocInput, и только когда свойство State установлено в icDocData(3). При использовании свойства FileName или DocLink, данный метод позволяет исследовать данные во время их передачи.

Метод SetData определяет следующий буфер передаваемых данных при наступлении события DocInput. SetData вызывается в течение события DocInput или перед вызовом SendDoc. Если метод используется перед вызовом SendDoc, он может служить альтернативой передачи параметров InputData в InputData. Тип должен быть определен как variant.

Метод Suspend передает форме команду suspend(true) или suspend(false). Если метод с параметром True был вызван дважды, то для продолжения передачи его необходимо дважды вызвать с параметром False.

Приведенный здесь код взят из демонстрационного проекта, расположенного в подкаталоге Delphi 2.01 demos\internet. Имя проекта HTTPDemo.dpr. Данный проект представляет собой пример использования свойств объекта BytesTransferred и state. Также показано использование различных типов данных, являющимися новыми для Delphi 2.01. Эти типы данных важны для использования OLE, и пользователи Delphi должны о них узнать как можно скорее, если они хотят начать использовать технологию OLE в своих приложениях.

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('Байт: %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
        { Теперь удаляем все HTML-тэги и отображаем текст }
        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;